Configuration du site

Objectif

Gérer les paramètres avancés du site, notamment les URL chiffrées, les scripts, l’émulation du navigateur, les proxys, l’enregistrement des en-têtes de requête/réponse, le contrôle de page et le comportement d’accès.

Prérequis

• Le site cible a été créé.
• Avant de publier des scripts, testez d’abord le site.

Étapes

1. Allez dans « Gestion des sites > Liste des sites ».
2. Trouvez le site cible, puis cliquez sur la configuration.
3. Activez l’URL chiffrée si nécessaire afin d’éviter d’afficher directement l’adresse du site d’origine dans l’interface utilisateur.
4. Configurez l’émulation du navigateur, le proxy, les en-têtes de requête, les en-têtes de réponse, le contrôle de page et les scripts.
5. Enregistrez la configuration du site.
6. Utilisez un compte de test pour accéder au site cible et vérifier l’ouverture, la connexion, la navigation, les données API et le traitement des événements SSE.
7. Pour personnaliser le comportement par catégorie de compte, revenez à la liste des sites et ouvrez « Configuration de la catégorie de compte ».

Référence de configuration

Élément	Utilité	Remarques
URL chiffrée	Masquer l’adresse du site d’origine affichée dans l’interface utilisateur	Ne remplace pas l’authentification propre au site cible
Émulation du navigateur	Ajuster la marque du navigateur, le modèle d’appareil mobile, le fuseau horaire et d’autres informations d’identification	Revérifiez la compatibilité du site cible après modification
Paramètres de proxy	Configurer l’accès direct, le proxy système, PAC ou un serveur proxy fixe pour ce site	Une erreur de proxy peut empêcher l’ouverture du site ou provoquer des anomalies de connexion
En-têtes de requête	Enregistrer les en-têtes de requête indiqués pour lecture par les scripts de page via api.header(name, true)	Seuls les en-têtes configurés et passés réellement par le navigateur distant sont enregistrés
En-têtes de réponse	Enregistrer les en-têtes de réponse indiqués pour lecture par les scripts de page via api.header(name, false)	Les noms d’en-tête sont convertis en minuscules à la lecture
Script de page	Traiter le DOM, les formulaires, les boutons, les navigations et les améliorations de page	Limitez les URL correspondantes pour éviter les effets involontaires
Script SSE	Réécrire les données de flux Server-Sent Events	Adapté aux scénarios avancés; testez d’abord
Script d’interception d’API normale	Réécrire le body de réponse des API non SSE	Le script doit retourner la nouvelle chaîne de body de réponse
Contrôle de page	Masquer ou supprimer des éléments de page par URL et sélecteur	Les sélecteurs peuvent échouer après une refonte du site cible
Configuration de la catégorie de compte	Définir une logique de connexion différenciée selon les catégories de compte	À utiliser avec les comptes navigateur du site

Configuration des scripts

La zone « Configuration des scripts » de la page de configuration du site permet d’ajouter un ensemble de règles de script pour le site cible. Chaque règle s’exécute lorsque le navigateur distant accède au site cible, selon l’URL correspondante et le type de script.

Champ	Type	Description
name	string	Nom du script. Le format recommandé est « site-usage-version », par exemple crm-login-v1.
url	string	URL de correspondance. Vide, elle est généralement interprétée comme *; en production, indiquez une valeur aussi précise que possible.
pageScript	boolean	Indique s’il s’agit d’un script de page. Activé, le script s’exécute dans le contexte de la page et peut utiliser window.api.
sseScript	boolean	Indique s’il s’agit d’un script d’interception SSE. Visible et effectif seulement lorsque pageScript = false.
selector	string	Condition d’exécution du script de page. Si renseignée, le script ne s’exécute que si la page correspond à ce sélecteur CSS ou XPath.
content	string	Contenu JavaScript du script. Les paramètres et retours varient selon le type de script.

Script de page

Lorsque pageScript = true, le script s’exécute comme script de page. Il convient au DOM, aux formulaires, aux clics de boutons, à la navigation, aux overlays, à la lecture/écriture de données utilisateur et aux améliorations de page.

Comportement d’exécution :

1. Le navigateur distant accède à la page cible.
2. Le système initialise window.api dans la page et les iframes accessibles.
3. Si selector est configuré, le script s’exécute seulement lorsqu’un élément correspond au sélecteur.
4. Le script peut utiliser directement api.config, api.user, api.dom, api.utils et api.header(). Consultez l’annexe API de script pour l’API complète.

Exemple : attendre l’apparition d’un élément, masquer une zone publicitaire et lire la configuration produit.

await api.utils.wait(
  () => !!api.dom.querySelector(document, '.main-panel'),
  10000,
  200
);

const envName = api.config.envName || 'default';
console.log('current env:', envName);

const banner = api.dom.querySelector(document, '.ad-banner');
if (banner) {
  banner.style.display = 'none';
}

Script SSE

Lorsque pageScript = false et sseScript = true, le script intercepte les données Server-Sent Events. Le système enveloppe EventSource et fetch dans la page et traite les flux dont l’URL correspond et dont le type de contenu est text/event-stream.

Forme d’exécution :

async (data) => {
  // Contenu du script saisi dans content
}

Paramètre	Type	Description
data	string	Message SSE actuel ou texte de chunk de flux.

La valeur de retour doit être le nouveau texte SSE. Sans chaîne retournée, la page peut recevoir des données anormales.

Exemple : remplacer du texte dans les données SSE.

return data.replace('old text', 'new text');

Script d’interception d’API normale

Lorsque pageScript = false et sseScript = false, le script intercepte les réponses d’API normales. Le système fait correspondre l’URL de l’API, lit le body de réponse et le transmet au script pour réécriture.

Forme d’exécution :

async (data, api, url) => {
  // Contenu du script saisi dans content
}

Paramètre	Type	Description
data	string	Body de réponse original.
api	object	API de script. Voir l’annexe API de script.
url	string	URL de l’API actuellement interceptée.

La valeur de retour doit être la nouvelle chaîne de body de réponse.

Exemple : réécrire une réponse JSON d’API.

const obj = JSON.parse(data);
obj.debug = true;
obj.fromScript = url.includes('/api/');
return JSON.stringify(obj);

Règles de correspondance d’URL

Le champ url prend en charge les règles suivantes :

Écriture	Description	Exemple
*	Correspond à toutes les URL	*
regex:<expression>	Utilise une expression régulière pour faire correspondre l’URL	regex:/api/chat
exact:<URL complète>	Correspond exactement à l’URL complète	exact:https://example.com/api/user
script:<expression>	Exécute l’expression avec l’URL actuelle comme variable url	script:url.includes('/api/')
Chaîne simple	Vérifie si l’URL cible commence par cette chaîne	https://example.com/api/

Pour les scripts de production, préférez les chemins précis ou les préfixes stables afin de réduire le risque d’affecter des pages et API sans rapport.

En-têtes de requête et de réponse

Les en-têtes de requête et de réponse dans la configuration du site servent à enregistrer les headers indiqués. Les scripts de page peuvent les lire via api.header(). Consultez l’annexe API de script pour les paramètres complets.

Étapes :

1. Dans « En-têtes de requête », ajoutez les noms d’en-têtes à enregistrer, par exemple authorization, cookie.
2. Dans « En-têtes de réponse », ajoutez les noms d’en-têtes à enregistrer, par exemple content-type, set-cookie.
3. Enregistrez la configuration et accédez au site cible via le navigateur distant.
4. Lisez-les dans le script de page.

const authorization = await api.header('authorization', true);
const contentType = await api.header('content-type', false);

Remarques :

• Les noms de header sont convertis en minuscules à la lecture.
• Seuls les headers configurés et passés réellement par le navigateur distant peuvent être lus.
• Les en-têtes de réponse peuvent être des tableaux de chaînes; les scripts doivent gérer les tableaux et les valeurs vides.

Syntaxe des sélecteurs

Les sélecteurs de script et de contrôle de page prennent en charge CSS et XPath.

Écriture	Description
.button.primary	Sélecteur CSS.
xpath://div[@id="app"]	Sélecteur XPath.
.dialog:p	Retourne l’élément parent de l’élément correspondant.
.dialog:p2	Retourne le parent deux niveaux au-dessus de l’élément correspondant.
.header:bottom	Dans les méthodes de bordure d’overlay, utilise la bordure inférieure de l’élément cible.
.sidebar:right	Dans les méthodes de bordure d’overlay, utilise la bordure droite de l’élément cible.

Processus de modification

1. Enregistrez la configuration actuelle et le contenu des scripts.
2. Modifiez sur un site ou un compte de test.
3. Vérifiez l’ouverture, la connexion, la navigation, la déconnexion, les réponses API et les événements SSE.
4. Vérifiez que les règles de contrôle de page masquent ou suppriment les bons éléments.
5. Synchronisez la configuration vers le site de production.
6. Demandez aux utilisateurs concernés de rouvrir le site et de vérifier.

Vérification

• Les cartes de site dans l’interface utilisateur s’affichent selon la configuration.
• Avec l’URL chiffrée, l’interface n’affiche pas directement l’URL du site d’origine.
• Les scripts personnalisés prennent effet selon les règles de correspondance lorsque le navigateur distant accède au site cible.
• Les scripts de page lisent correctement la configuration, localisent les éléments et traitent le comportement de page.
• Les scripts SSE ne réécrivent que le flux d’événements cible et n’affectent pas les API normales.
• Les scripts d’interception d’API normale retournent un body de réponse valide.
• Après une refonte du site cible, les scripts et sélecteurs correspondent toujours correctement.

FAQ

• Testez les scripts sur un site de test avant la production.
• L’URL chiffrée n’affecte que l’affichage frontend et le chemin d’accès; elle ne contourne pas la politique de sécurité propre au site cible.
• Les scripts de page conviennent au DOM, aux formulaires et au comportement de page.
• Les scripts SSE ne conviennent qu’aux flux Server-Sent Events et ne doivent pas traiter les API JSON normales.
• Les scripts d’interception d’API normale doivent retourner une chaîne, sinon la page cible peut ne pas analyser la réponse.
• Les paramètres complets et exemples des API disponibles sont dans l’annexe API de script.
• La configuration de la catégorie de compte sert à définir des comportements différents pour plusieurs modes de connexion d’un même site.