Rokt UX Helper - Dépannage

Ce guide aborde les problèmes courants qui peuvent survenir lors de la mise en œuvre de la bibliothèque Rokt UX Helper et fournit des solutions.

Problèmes Courants

Expériences Ne S'affichant Pas

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

1. Sélecteurs d'Élément 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.

   // Check the plugin configuration in your response
   console.log(experienceData.plugins.map(plugin => plugin.plugin.targetElementSelector));
   
   // Make sure these selectors match your elements
   console.log(document.querySelector('rokt-layout-view').id); // Should match one of the selectors

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

   // Validate the payload structure
   if (!experienceData || !experienceData.plugins || experienceData.plugins.length === 0) {
     console.error('No valid experience data available');
   }

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

   // Check if the element is registered
   console.log(!!customElements.get('rokt-layout-view'));
   
   // Register manually if needed
   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 pour charger la bibliothèque depuis le CDN :

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

   <!-- CommonJS format (for direct browser usage) -->
   <script src="https://cdn.jsdelivr.net/npm/@rokt/ux-helper-web/dist/index.cjs"></script>
   
   <!-- ESM format (for modern applications) -->
   <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 vérifier 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>

"Impossible de lire la propriété 'renderExperiences' de 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 :

WARNING: Multiple overlay plugins detected. Only rendering the first one.

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 cache le contenu :

   /* Add this temporarily to debug */
   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 :

   // Correct order
   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 :

   // Use capturing phase to intercept events earlier
   document.addEventListener('RoktUXEvent', handleUXEvent, true);
   document.addEventListener('RoktPlatformEvent', handlePlatformEvent, true);

Événements de Plateforme Non Traités

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

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

   roktElement.addEventListener('RoktPlatformEvent', (event) => {
     // Send the ENTIRE detail object, don't modify it
     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 d'Élément Personnalisé Manquante : 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) => {
     // Cast to CustomEvent to access detail property
     const customEvent = event as CustomEvent;
     console.log(customEvent.detail);
   };

Problèmes de Références

Si vous avez des problèmes avec les références React :

// Use correct ref type and access pattern
const roktRef = useRef<HTMLElement & {
  renderExperiences: (data: any) => void;
  close: () => void;
}>(null);

// Later in your 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