Rokt UX Helper - Dépannage

Ce guide aborde les problèmes courants qui peuvent survenir lors de l'implémentation de la bibliothèque Rokt UX Helper et fournit des solutions.

Problèmes Courants

Expériences Non Rendu

Si vos expériences n'apparaissent pas sur la page :

1. Sélecteurs d'Éléments Ne Correspondent Pas: Assurez-vous que le targetElementSelector dans votre charge utile d'expérience correspond à l'ID ou à la classe de votre élément rokt-layout-view.

   // Vérifiez la configuration du plugin dans votre réponse
   console.log(experienceData.plugins.map(plugin => plugin.plugin.targetElementSelector));
   
   // Assurez-vous que ces sélecteurs correspondent à vos éléments
   console.log(document.querySelector('rokt-layout-view').id); // Doit correspondre à l'un des sélecteurs

2. Charge Utile Vide ou Invalide: Vérifiez que votre charge utile d'expérience est valide et contient des plugins.

   // Validez la structure de la charge utile
   if (!experienceData || !experienceData.plugins || experienceData.plugins.length === 0) {
     console.error('Aucune donnée d'expérience valide disponible');
   }

3. Élément Personnalisé Non Enregistré: Assurez-vous que les éléments personnalisés sont correctement enregistrés.

   // Vérifiez si l'élément est enregistré
   console.log(!!customElements.get('rokt-layout-view'));
   
   // Enregistrez manuellement si nécessaire
   import { registerCustomElements } from '@rokt/ux-helper-web';
   registerCustomElements();

4. Éléments de Superposition Multiples: Seul le premier rokt-layout-view avec l'attribut render-overlay recevra des expériences de superposition. Vérifiez votre implémentation si vous avez plusieurs éléments de superposition.

Problèmes de CDN

Si vous rencontrez des problèmes avec le chargement de la bibliothèque depuis le CDN :

1. Chemin CDN incorrect : Les chemins corrects pour la bibliothèque sont :

   <!-- Format CommonJS (pour une utilisation directe dans le navigateur) -->
   <script src="https://cdn.jsdelivr.net/npm/@rokt/ux-helper-web/dist/index.cjs"></script>
   
   <!-- Format ESM (pour les applications modernes) -->
   <script type="module">
     import * as RoktUXHelper from 'https://cdn.jsdelivr.net/npm/@rokt/ux-helper-web/dist/index.mjs';
   </script>

2. Problèmes de version : Si une version vous pose problème, essayez de spécifier une version exacte :

   <script src="https://cdn.jsdelivr.net/npm/@rokt/ux-helper-web@0.1.5/dist/index.cjs"></script>

3. Problèmes de CORS : Si vous rencontrez des erreurs CORS, assurez-vous que votre serveur est configuré pour autoriser le domaine du CDN.

4. Problèmes de réseau : Vérifiez l'onglet réseau de votre navigateur pour vous assurer que les fichiers CDN sont chargés correctement.

Erreurs de Console

"Échec de la construction de 'CustomElement'"

Si vous voyez des erreurs liées à la construction d'éléments personnalisés :

Uncaught DOMException: Failed to construct 'CustomElement': The result must not have attributes

Cela se produit généralement dans les anciens navigateurs ou avec des polyfills. Assurez-vous d'utiliser la dernière version de la bibliothèque et envisagez d'ajouter des polyfills pour les anciens navigateurs :

<script src="https://unpkg.com/@webcomponents/webcomponentsjs/webcomponents-bundle.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@rokt/ux-helper-web/dist/index.cjs"></script>

"Cannot read property 'renderExperiences' of null"

Cette erreur se produit lorsque vous essayez d'appeler des méthodes sur un élément qui n'existe pas dans le DOM :

Uncaught TypeError: Cannot read property 'renderExperiences' of null

Assurez-vous que l'élément existe avant d'essayer de l'utiliser :

const roktElement = document.getElementById('rokt-layout-placeholder');
if (roktElement) {
  roktElement.renderExperiences(experienceData);
} else {
  console.error('Element #rokt-layout-placeholder not found in DOM');
}

Problèmes de Mise en Page

"Avertissement : Plusieurs plugins de superposition détectés"

Si vous voyez un avertissement concernant plusieurs plugins de superposition :

AVERTISSEMENT : Plusieurs plugins de superposition détectés. Seul le premier sera rendu.

Cela signifie que vous avez plusieurs plugins ciblant le sélecteur body. Seul le premier sera rendu. Si vous avez besoin de rendre plusieurs superpositions, envisagez d'utiliser différentes stratégies de placement.

Expériences Non Visibles Mais Présentes dans le DOM

Si les expériences sont rendues dans le DOM mais ne sont pas visibles :

1. Vérifiez les Problèmes de CSS : Inspectez l'élément et vérifiez qu'aucun CSS ne masque le contenu :

   /* Ajoutez ceci temporairement pour déboguer */
   rokt-layout-view {
     border: 1px solid red;
     min-height: 50px;
   }

Problèmes de Gestion des Événements

Événements Ne Se Déclenchant Pas

Si vous ne recevez pas d'événements :

1. Écouteurs d'Événements Attachés Trop Tard : Assurez-vous que les écouteurs d'événements sont attachés avant de rendre les expériences :

   // Ordre correct
   roktElement.addEventListener('RoktUXEvent', handleUXEvent);
   roktElement.addEventListener('RoktPlatformEvent', handlePlatformEvent);
   roktElement.renderExperiences(experienceData);

2. Problèmes de Propagation des Événements : Vérifiez si les événements sont arrêtés de se propager dans un élément parent :

   // Utilisez la phase de capture pour intercepter les événements plus tôt
   document.addEventListener('RoktUXEvent', handleUXEvent, true);
   document.addEventListener('RoktPlatformEvent', handlePlatformEvent, true);

Événements de la Plateforme Non Traités

Si les événements de la plateforme Rokt ne sont pas correctement traités :

1. Charge Utile (Payload) Incorrecte de l'Événement : Assurez-vous de transmettre la charge utile complète de l'événement :

   roktElement.addEventListener('RoktPlatformEvent', (event) => {
     // Envoyez l'objet detail ENTIER, ne le modifiez pas
     sendToBackend(event.detail);
   });

2. Problèmes de Réseau : Vérifiez que les événements sont envoyés au bon point de terminaison avec la bonne authentification.

Problèmes Spécifiques à React

Erreurs TypeScript

Si vous rencontrez des erreurs TypeScript avec React :

1. Déclaration Manquante d'Élément Personnalisé : Assurez-vous d'avoir déclaré l'élément personnalisé :

   declare global {
     namespace JSX {
       interface IntrinsicElements {
         "rokt-layout-view": React.DetailedHTMLProps<
           React.HTMLAttributes<HTMLElement> & {
             ref?: React.RefObject<HTMLElement>;
           },
           HTMLElement
         >;
       }
     }
   }

2. Problèmes de Conversion de Type : Utilisez la conversion de type appropriée pour les événements :

   const handleUXEvent = (event: Event) => {
     // Convertir en CustomEvent pour accéder à la propriété detail
     const customEvent = event as CustomEvent;
     console.log(customEvent.detail);
   };

Problèmes de Ref

Si vous rencontrez des problèmes avec les refs (références) dans React :

// Utilisez le type de ref correct et le modèle d'accès
const roktRef = useRef<HTMLElement & {
  renderExperiences: (data: any) => void;
  close: () => void;
}>(null);

// Plus tard dans votre code
if (roktRef.current) {
  roktRef.current.renderExperiences(data);
}

Obtenir de l'aide

Si vous rencontrez toujours des problèmes après avoir essayé ces solutions, vous pouvez :

1. Vérifier le dépôt GitHub pour les problèmes ouverts ou en créer un nouveau
2. Consulter la documentation complète de l'API
3. Contacter le support Rokt pour une assistance supplémentaire