Passer au contenu principal

​
Qu’est-ce qu’une single-page app (SPA) ?

​
Définition et objectif

Une single-page application (SPA) est un type d’application web conçue pour offrir une expérience utilisateur plus fluide et plus rapide en mettant à jour dynamiquement le contenu sans recharger toute la page. Les SPA sont généralement construites à l’aide de frameworks JavaScript modernes tels que React, Next.js ou Vue.js. De nombreuses SPA utilisent également le server-side rendering (SSR), ce qui ajoute de la complexité aux implémentations côté client telles que l’A/B testing et la personnalisation. Le principal avantage des SPA est d’améliorer l’expérience de navigation du visiteur en chargeant les ressources une seule fois et en mettant à jour le contenu dynamiquement, plutôt qu’en rechargeant toute la page après chaque action.

​
Défis de mise en œuvre et solutions

Les SPA introduisent des défis uniques pour des outils comme Kameleoon qui s’appuient sur les chargements de page pour appliquer des variations ou exécuter des scripts. Pour garantir des performances optimales, il est essentiel d’adapter la stratégie d’implémentation en fonction du type de SPA avec lequel vous travaillez. Dans les sections suivantes, nous décrirons les bonnes pratiques et les procédures pour gérer chaque scénario, garantissant une intégration fluide et un suivi précis du comportement des visiteurs sur votre site web.

​
Configuration native

Si votre site web est une SPA complète, l’activation de l’option « support for dynamic websites » garantit que Kameleoon recherche les changements d’URL. Lorsque l’URL change, tous les scripts Kameleoon sont réexécutés, y compris le ciblage et le code de variation. Kameleoon surveillera également les mises à jour de votre SPA en utilisant un MutationObserver pour suivre les changements dans le DOM, même lorsque l’URL de la page reste statique. Cela permet à Kameleoon d’appliquer (ou de réappliquer) les changements de variation dynamiquement à mesure que des mises à jour se produisent sur votre site web. Kameleoon prend en charge diverses modifications effectuées via le graphic editor, notamment :
  • Changements de style
  • Modifications de texte
  • Mises à jour de position (swap, insert before/after)
  • Sélecteurs CSS personnalisés
Cette approche garantit que toutes les modifications pertinentes sont appliquées de manière cohérente dans un environnement dynamique. Pour activer la prise en charge des sites web dynamiques :
  1. Cliquez sur Admin > Projects.
  2. Localisez la carte de votre projet et cliquez sur l’icône Edit.
  3. Cliquez sur Configuration et déployez le menu General.
  4. Faites défiler jusqu’à Advanced settings et activez Enable support for dynamic websites (Single Page App, Progressive Web App…) sur ON.
Plusieurs options sont disponibles pour vous aider à optimiser votre configuration :
  • Choisir la portée : vous pouvez activer la fonctionnalité pour l’ensemble du site ou la limiter à des éléments spécifiques à l’aide du Graphic editor. Restreindre la portée à des éléments sélectionnés permet de réduire le poids global du script. Découvrez comment marquer un élément comme dynamique ici.
  • Définir un attribut personnalisé (facultatif) : cette option améliore l’identification des éléments et aide à éviter les problèmes liés aux attributs et sélecteurs dynamiques. Si votre site web ne génère pas d’ID HTML stables ou uniques, vous pouvez définir un attribut personnalisé que Kameleoon utilisera pour identifier les éléments modifiés. Cet attribut a priorité sur l’ID de l’élément lors de la construction du sélecteur.
  • Éviter les sélecteurs d’ID dynamiques (facultatif) : cette option améliore également l’identification des éléments lorsqu’il s’agit d’attributs et de sélecteurs dynamiques. Par défaut, Kameleoon ignore les ID HTML qui contiennent des séquences numériques de plus de cinq chiffres. Vous pouvez définir votre propre expression régulière pour exclure des motifs d’ID supplémentaires si nécessaire.

​
Définir un attribut personnalisé

Vous pouvez définir un attribut personnalisé (par exemple, data-id, data-qa) pour identifier les éléments sur la page. Les attributs personnalisés sont particulièrement utiles lorsque votre site génère des ID dynamiques pour les éléments HTML. Le Graphic Editor de Kameleoon identifie les éléments à l’aide de sélecteurs CSS, qui se divisent en deux catégories :
  • Sélection basée sur l’ID : si l’élément a un ID, Kameleoon l’utilisera pour localiser et modifier l’élément lors du chargement de la page.
  • Sélecteur combinatoire : si aucun ID n’est trouvé, Kameleoon crée un chemin de sélecteur en utilisant l’élément parent le plus proche ayant un ID.
Dans les cas où vos ID sont dynamiques et changent fréquemment, le Graphic editor peut avoir du mal à identifier les éléments. Pour résoudre ce problème, vous pouvez ajouter un attribut personnalisé statique (par exemple, <button custom-id="1">) qui identifie de manière fiable les éléments entre les mises à jour.

​
Éviter les sélecteurs d’ID dynamiques

Par défaut, Kameleoon évite d’utiliser les ID d’élément qui contiennent des nombres générés dynamiquement de plus de cinq chiffres consécutifs. À la place, il construit un chemin en utilisant un élément parent statique proche ayant un ID. Vous pouvez personnaliser ce comportement en spécifiant une expression régulière pour exclure certains ID dynamiques, garantissant un ciblage plus précis.

​
Configuration personnalisée

Si votre site web n’est pas une SPA complète ou si vous devez gérer des parties spécifiques du site, reportez-vous à la section ci-dessous. Il existe quatre cas d’usage différents pour les configurations SPA personnalisées.

​
SPA partielles

Pour activer cette option pour des pages spécifiques, désactivez-la dans Advanced settings et ajoutez le code suivant à votre Global script : 
if (document.location.href.includes('mySPApage')) {
     Kameleoon.API.Core.enableSinglePageSupport();
 }
Remplacez « mySPApage » par l’URL de votre funnel.

​
Changements de page sans changement d’URL

Dans les cas où le DOM est mis à jour sans changement d’URL, appuyez-vous sur des indicateurs alternatifs pour recharger Kameleoon. Voici un exemple utilisant sessionStorage pour détecter les changements de page. Vous pouvez ajouter le code à votre Global script : 
window.kam_step = JSON.parse(window.sessionStorage.getItem('formStep'))?.step;
 Kameleoon.API.Core.runWhenConditionTrue(() => {
     return window.kam_step != JSON.parse(window.sessionStorage.getItem('formStep'))?.step;
 }, () => {
     Kameleoon.API.Core.load();
 });

​
Détecter les changements de page avec pathname

Pour les pages où vous devez réexécuter Kameleoon, mais uniquement lorsque le pathname change (en ignorant les paramètres de requête), détectez les changements en utilisant le pathname au lieu d’une URL complète. Le code ci-dessous peut être ajouté à votre Global script : 
if (document.location.href.includes('configurator')) {
     window.kam_configurator_url = document.location.pathname;
 `Kameleoon.API.Core.runWhenConditionTrue(() => {     return window.kam_configurator_url != document.location.pathname; }, () => {     Kameleoon.Gatherer.Referrer.update(window.kam_configurator_url);     Kameleoon.API.Core.load(); });`
 } else {
     Kameleoon.API.Core.enableSinglePageSupport();
 }

​
Réappliquer le code de variation sans recharger Kameleoon

Dans certains cas, certains éléments de la page sont dynamiques, et lorsque le code est réhydraté, il peut écraser le code Kameleoon déjà appliqué. Pour éviter cela, vous avez deux options :
  • Vous pouvez informer Kameleoon lorsque la page ou un élément spécifique a fini d’être rendu en utilisant l’une des méthodes suivantes :
    • Définissez une variable window ; par exemple, window.pageLoadForKam = true.
    • Déclenchez un événement sur la page que Kameleoon peut écouter. Par exemple, en utilisant pageLoaded ou contentUpdated : window.addEventListener('pageLoaded', () -> { runKameleoonVariationCode }).
    • Ajoutez une classe ou un attribut spécifique à la balise <body> ou à l’élément cible. Ensuite, dans le code de variation, utilisez cette classe ou cet attribut pour effectuer des changements sur la page ou des éléments spécifiques.
  • Dans le code de variation, vous pouvez définir le quatrième argument de la fonction runWhenElementPresent sur true. Cet argument active la prise en charge des éléments dynamiques et des single-page applications (SPA). Lorsque cette option est activée, si le sélecteur CSS spécifié pour l’élément n’est pas trouvé par Kameleoon lors du chargement initial de la page, Kameleoon surveillera le DOM pour ce sélecteur. Une fois l’élément apparu dans le DOM, Kameleoon exécutera la fonction de rappel. De plus, si un nouvel élément correspondant au sélecteur est ajouté ultérieurement à la page, Kameleoon réexécutera le rappel avec l’élément nouvellement ajouté.
Utilisez le code ci-dessous avec parcimonie et uniquement lorsque cela est absolument nécessaire. Limitez son utilisation au nombre minimum de cas et évitez de l’appliquer à plusieurs éléments simultanément pour maintenir des performances de page optimales. Soyez attentif au potentiel de boucle infinie si le code source de la page modifie l’élément à chaque mise à jour.
const insertMyNewCTA = () => {
     if (document.querySelector("#kameleoonElement-myNewCTA") == null) {
 `    Kameleoon.API.Core.runWhenElementPresent(         '#myElement',         ([myElement]) => {             myElement.insertAdjacentHTML('beforebegin', "<button id='kameleoonElement-myNewCTA'>More info</button>");         },         null, true     ); }`
 }
 insertMyNewCTA();

​
Récupérer les données du dataLayer

Lors de l’utilisation de GTM comme méthode de récupération pour définir les valeurs de custom data, Kameleoon s’appuie sur un dataLayer défini pour accéder à ses valeurs. Si le dataLayer est mis à jour après chaque changement d’URL en empilant de nouvelles entrées au lieu de supprimer les anciennes, Kameleoon peut récupérer des valeurs obsolètes. Cette récupération se produit parce que les anciennes données persistent à travers les pages, et Kameleoon peut s’exécuter avant que le dataLayer ne soit mis à jour. Pour éviter ce problème, assurez-vous que les entrées obsolètes sont supprimées avant d’en ajouter de nouvelles. Vous pouvez également implémenter un code personnalisé pour attendre les changements dans la longueur du dataLayer avant de récupérer les dernières valeurs : 
`window.dataLayerLength = window.dataLayerLength || 0; Kameleoon.API.Core.runWhenConditionTrue(() => { return window.dataLayer && window.dataLayerLength != window.dataLayer.length }, () => { window.dataLayerLength = window.dataLayer.length //then, retrieve and use dataLayer info here })`

​
Considérations générales

​
Écouteurs d’événements, timeouts et intervalles

Utilisez Kameleoon.API.Utils pour gérer les écouteurs d’événements, les timeouts ou les intervalles. Ces méthodes garantissent que les écouteurs et les minuteurs sont automatiquement supprimés lorsqu’un changement d’URL se produit sans rechargement de la page. Ces suppressions évitent les doublons lors de la réexécution de Kameleoon.

​
ID d’élément uniques

Lors de l’ajout d’éléments via Kameleoon, assurez-vous que leur id commence par kameleoonElement. Cette convention de nommage garantit que l’élément est supprimé avant que Kameleoon ne s’exécute à nouveau, évitant les duplications ou conflits. Exemple : <div id="kameleoonElement-myNewCTA"></div>

​
Incrémentation des pages vues

Kameleoon ne compte une nouvelle page que lorsque tous ses scripts sont réexécutés, ce qui se produit dans deux conditions :
  • Lorsque Kameleoon.API.Core.enableSinglePageSupport() est appelée, combinée à un changement d’URL.
  • Lorsque Kameleoon.API.Core.load() est explicitement déclenchée.
En suivant toutes les directives ci-dessus, vous pouvez vous assurer que les variations sont implémentées efficacement et de manière cohérente sur les SPA, améliorant l’expérience utilisateur tout en maintenant l’intégrité des données. Pour toute assistance supplémentaire, n’hésitez pas à contacter l’équipe Kameleoon.

​
Alternatives

​
SDK REACT et JS

Kameleoon propose un SDK React et un SDK JavaScript/TypeScript conçus pour les single-page applications. Ces SDK fournissent une méthode alternative pour exécuter des expériences et gérer des feature flags au sein de votre SPA en intégrant le SDK dans le code de votre application. Pour une liste complète des fonctionnalités disponibles pour les SPA, consultez notre documentation SDK.

​
Plugin GatsbyJS

Kameleoon fournit également un plugin dédié pour les applications GatsbyJS. Pour intégrer Kameleoon à votre application GatsbyJS, suivez les instructions décrites dans cet article.

​
Framework Next.js

Si votre site web est construit avec Next.js, il y a un point important à considérer lors de l’utilisation du Graphic editor de Kameleoon. Les sites web Next.js se chargent d’une manière spécifique qui pourrait entrer en conflit avec les changements de Kameleoon s’ils se produisent trop rapidement, ce qui pourrait entraîner un affichage incorrect de la page.

​
Solution recommandée

L’équipe Kameleoon a créé un guide de configuration Next.js dédié qui résout automatiquement ce problème. Cette configuration garantit :
  • Kameleoon se charge rapidement et efficacement.
  • Votre page s’affiche en douceur sans flickering.
  • Les changements apparaissent au bon moment sans casser votre site.
  • La navigation entre les pages fonctionne correctement.
Consultez le guide étape par étape : Implémentation avec Next.js

​
Approches alternatives

Si vous ne pouvez pas utiliser la configuration recommandée ci-dessus, il existe d’autres moyens d’éviter les conflits. Votre développeur peut ajouter un simple signal qui indique à Kameleoon « la page est prête pour les changements maintenant ».
  • Méthode 1 : Indicateur de page prête
    • Ajoutez un marqueur à l’élément <body> une fois la page entièrement chargée. Configurez ensuite vos expériences Kameleoon pour qu’elles ne s’exécutent que lorsque ce marqueur est présent.
  • Méthode 2 : Événement personnalisé
    • Utilisez la file d’attente de commandes de Kameleoon pour envoyer un signal lorsque votre page est prête : Events.trigger('my page is hydrated').
    • Configurez ensuite vos expériences pour utiliser le critère de ciblage Custom event afin d’attendre ce signal avant d’effectuer des changements. Pour plus de détails sur la mise en œuvre des événements personnalisés et d’autres ciblages, consultez cet article
La configuration Next.js dédiée gère tout cela automatiquement, vous n’aurez donc pas à vous soucier de ces détails techniques.