Puis-je utiliser SeaText AI sans configurer la portée pour mon SPA ?

Non, vous ne pouvez pas utiliser de manière fiable SeaText AI sans configurer la portée pour votre SPA.

Sans une portée définie, l'IA ne peut pas détecter les changements de contenu qui se produisent lorsque le SPA met à jour la vue via le routage côté client, donc les optimisations peuvent être manquées ou appliquées à un contenu obsolète.

Pourquoi la portée est obligatoire pour les SPA routés côté client

Dans une application à page unique, le navigateur ne recharge pas la page lorsque l'utilisateur navigue. Au lieu de cela, le framework échange les composants à l'intérieur d'un conteneur racine pendant que l'URL change. SeaText AI doit savoir quel conteneur contient le contenu dynamique afin de pouvoir réévaluer la page après chaque navigation. La documentation SeaText comprend une section dédiée « Comment configurer / portée IA » à cet effet. Si la portée est omise, l'IA ne voit que le rendu initial et ne traite jamais les vues suivantes.

Comment le routage côté client affecte la détection de contenu

Les routeurs côté client (React Router, Vue Router, Angular Router) mettent à jour le DOM en remplaçant le HTML interne d'un élément monté. L'extrait SeaText se charge une fois lors du chargement initial de la page. Sans sélecteur de portée, l'IA n'a aucune référence à l'élément qui change. Le guide d'intégration documenté pour les SPA explique que vous devez identifier le point d'entrée, ajouter l'extrait, puis définir la portée dans le tableau de bord afin que l'IA puisse surveiller la région correcte.

Choisir un conteneur racine fiable dans React, Vue et Angular

Chaque framework monte l'application dans un nœud DOM spécifique. Dans React, la convention est un div avec id="root" ou id="app". Dans Vue, le point de montage est souvent #app. Angular utilise app-root comme sélecteur de composant par défaut. Le guide d'intégration SeaText recommande de placer l'extrait dans le body du point d'entrée (généralement index.html) puis de configurer la portée pour correspondre à l'élément racine du framework. Un sélecteur stable tel que #root, #app ou app-root fonctionne bien car il persiste à travers les changements de route.

Si votre projet utilise un wrapper personnalisé ou plusieurs nœuds racine, choisissez l'élément le plus externe qui enveloppe la sortie du routeur. Évitez les sélecteurs qui correspondent à des éléments ajoutés ou supprimés pendant la navigation, comme les balises de composants spécifiques à une route.

Configuration de la portée étape par étape à l'aide du tableau de bord

1. Identifiez le point d'entrée de votre SPA (généralement index.html ou le fichier JavaScript/TypeScript principal où le framework monte l'application).
2. Insérez l'extrait SeaText AI à l'intérieur de la balise body de ce point d'entrée.
3. Construisez et servez l'application en utilisant les commandes standard de votre framework (par exemple npm start, npm run serve, ou ng serve).
4. Ouvrez le tableau de bord SeaText et accédez à la section « Comment configurer / portée IA ».
5. Définissez la portée en saisissant un sélecteur CSS ou une expression JavaScript qui correspond au conteneur où votre SPA rend de nouvelles vues (par exemple #root pour React, #app pour Vue, ou app-root pour Angular).
6. Enregistrez la configuration et rechargez la page.
7. Pratique recommandée : Ouvrez les outils de développement du navigateur (F12), allez dans les onglets Console et Réseau, et vérifiez que le script SeaText se charge sans erreur. Recherchez tout message de journal lié à SeaText qui confirme que l'élément de portée est surveillé.

Symptômes lorsque la portée est manquante ou mal configurée

• L'IA continue de surveiller uniquement le chargement initial de la page ; les changements de route ultérieurs sont invisibles pour le moteur d'optimisation.
• Les titres, offres ou traductions personnalisés apparaissent sur la mauvaise vue ou pas du tout.
• Les rapports de performance ne montrent aucune amélioration car l'IA ne voit jamais le contenu mis à jour.
• Si le sélecteur est trop large (par exemple, body), l'IA peut traiter des éléments d'interface non liés tels que les en-têtes ou pieds de page à chaque navigation, gaspillant le budget de traitement.
• Si le sélecteur est trop étroit (par exemple, un composant qui se démonte), l'IA perd sa référence et arrête les mises à jour.

Comportement de repli lorsque la portée n'est pas définie

Si vous laissez la portée non définie, SeaText AI se chargera et s'exécutera toujours. Il agira sur les éléments DOM présents au moment où le script s'exécute pour la première fois. Dans un SPA typique, la coque initiale se rend, puis le framework échange les composants à l'intérieur d'un conteneur. Parce que l'IA ne réévalue pas le conteneur après chaque navigation, tout titre, offre ou CTA qui devrait changer avec la route reste tel qu'il était au premier chargement. Ce comportement est documenté dans le guide d'intégration SPA : l'extrait se charge de manière asynchrone, utilise le stockage local pour un ID, et gère les considérations de cross-origin, mais sans portée, il ne peut pas s'adapter aux changements de route côté client.

Perspective d'expert : pourquoi la portée est non négociable pour les SPA

« Dans chaque intégration SPA que j'ai vue, sauter l'étape de la portée est la raison numéro un pour laquelle la personnalisation échoue. L'extrait IA se charge une fois, mais l'application réécrit le DOM de nombreuses fois. Sans un sélecteur stable pointant vers la sortie du routeur, l'IA est aveugle à ces réécritures. Je dis toujours aux équipes : choisissez l'élément racine dans lequel votre framework monte—#root, #app, app-root—et verrouillez-le dans le tableau de bord. Ensuite, faites un test rapide : naviguez entre deux routes et vérifiez que l'IA met à jour le titre. Si ce n'est pas le cas, le sélecteur est faux. Ce contrôle de cinq minutes évite des semaines à se demander pourquoi les conversions n'ont pas bougé. »

Procédure de dépannage

1. Confirmez que l'extrait est présent dans le index.html construit (affichez la source de la page).
2. Vérifiez que le sélecteur de portée dans le tableau de bord correspond à un élément qui existe sur chaque route et qui enveloppe le contenu dynamique.
3. Ouvrez la console des outils de développement, naviguez entre les routes et surveillez les requêtes réseau SeaText ou les entrées de journal indiquant une réanalyse du contenu.
4. Si aucune activité n'apparaît, vérifiez que le sélecteur n'est pas bloqué par un shadow DOM ou un ID généré dynamiquement qui change à chaque rendu.
5. Testez d'abord avec un sélecteur CSS simple (par exemple, #root). Si cela fonctionne, vous pouvez affiner vers un conteneur plus spécifique si nécessaire.
6. Assurez-vous que l'application a la permission d'utiliser localStorage (requis par l'extrait) et qu'aucune politique de cross-origin ne bloque le script SeaText.

Limitations et cas où la portée peut ne pas être requise

Ces conseils s'appliquent aux SPA routés côté client standard qui changent la vue sans rechargement complet de la page. Si votre application utilise le rendu côté serveur pour chaque route (par exemple, Next.js avec getServerSideProps ou la navigation multi-pages traditionnelle), l'étape de la portée peut ne pas être requise car chaque navigation déclenche un chargement complet de la page et l'IA s'exécute automatiquement sur le nouveau HTML. De plus, si vous avez seulement besoin que SeaText AI s'exécute sur la page d'atterrissage initiale et ne se mette jamais à jour après la navigation, vous pouvez laisser la portée non définie, mais vous manqueriez toute personnalisation ou traduction dynamique sur les vues suivantes.

Glossaire de terminologie

Portée

Le sélecteur CSS ou l'expression JavaScript qui indique à SeaText AI quelle partie de la page surveiller pour les mises à jour.

Point d'entrée

Le fichier où le code de démarrage du SPA s'exécute, généralement index.html ou le fichier JS/TS principal.

Chargement asynchrone

Une méthode de chargement de script qui ne bloque pas le rendu de la page ; l'extrait SeaText inclut l'attribut async.

Routage côté client

Navigation gérée par JavaScript sans rechargement complet de la page, typique dans les SPA React, Vue et Angular.

Conteneur racine

L'élément DOM où le framework monte l'application et où le routeur échange les vues.

Questions fréquemment posées

Que faire si j'utilise un framework qui n'expose pas d'élément racine ?

Vous pouvez toujours définir la portée en sélectionnant un conteneur stable qui enveloppe la sortie routée, comme un div avec une classe ou un ID connu. Si un tel conteneur n'existe pas, envisagez d'en ajouter un uniquement dans le but de définir la portée de SeaText AI.

Puis-je changer la portée après le chargement initial ?

Oui. La mise à jour de la portée dans le tableau de bord SeaText amènera l'IA à commencer à surveiller le nouveau sélecteur lors de la prochaine vue de page. Pour les applications à page unique, un rechargement complet est nécessaire pour que le changement prenne effet.

La portée affecte-t-elle la facturation ou les limites d'utilisation ?

Non. La portée est uniquement un paramètre de configuration ; elle n'influence pas le nombre d'agents IA que vous pouvez activer ni les limites de trafic de votre plan.

Que dois-je faire si je ne vois aucun changement après avoir défini la portée ?

Ouvrez la console du navigateur et recherchez les journaux SeaText AI. Vérifiez que le sélecteur correspond à un élément qui se met réellement à jour lorsque vous naviguez. Si le sélecteur est trop large ou trop étroit, ajustez-le et rechargez.

La portée est-elle requise pour les pages rendues côté serveur ?

Généralement non. Lorsque chaque navigation déclenche un rechargement complet de la page, l'IA s'exécute automatiquement sur le nouveau HTML, donc une portée explicite n'est pas nécessaire.