Rokt UX Helper - Utilisation Avancée

Ce guide couvre les scénarios d'utilisation avancée et les fonctionnalités de la bibliothèque Rokt UX Helper.

Support de Placements Multiples

Rokt UX Helper prend en charge plusieurs placements sur une seule page. Chaque placement nécessite son propre élément rokt-layout-view avec un ID unique :

<!-- Placement principal -->
<rokt-layout-view id="rokt-primary"></rokt-layout-view>

<!-- Placement secondaire -->
<rokt-layout-view id="rokt-secondary"></rokt-layout-view>

<!-- Placement en superposition -->
<rokt-layout-view id="rokt-overlay" render-overlay></rokt-layout-view>

Lors du rendu des expériences, chaque placement n'affichera que les plugins qui correspondent à son sélecteur :

// Obtenir les données d'expérience qui contiennent plusieurs plugins
const experienceData = await fetchExperienceData();

// Rendre les expériences à tous les éléments de placement
document.querySelectorAll('rokt-layout-view').forEach(element => {
  element.renderExperiences(experienceData);
});

Ciblage des Éléments

Les plugins dans la charge utile de l'expérience sont associés à l'élément rokt-layout-view approprié en fonction de la propriété targetElementSelector dans la configuration du plugin. Les règles de correspondance sont :

1. Sélecteur d'ID : Un plugin avec targetElementSelector: "#rokt-primary" ciblera l'élément avec id="rokt-primary".
2. Sélecteur de Classe : Un plugin avec targetElementSelector: ".placement-class" ciblera les éléments avec class="placement-class".
3. Sélecteur de Body : Un plugin avec targetElementSelector: "body" ciblera les éléments avec l'attribut render-overlay.

Communication d'Événements

Envoi d'Événements aux Layouts

Vous pouvez également envoyer des événements aux layouts rendus en utilisant la méthode send. Ceci est utile pour communiquer avec les layouts en fonction des actions dans votre application :

// Envoyer un événement de mise à jour du panier à tous les layouts rendus
await roktElement.send('V2_UPDATE_CART_ITEM', {
    cartItemId: "item-123",
    quantity: 2
});

Ceci est utile pour les mises à jour dynamiques des expériences rendues basées sur les interactions des utilisateurs ou les changements de données externes.

Gestion des événements de tous les emplacements

Pour centraliser la gestion des événements, vous pouvez écouter les événements au niveau du document :

document.addEventListener('RoktUXEvent', (event) => {
  const { pluginId, eventName, data } = event.detail;
  console.log(`Événement UX du plugin ${pluginId} :`, eventName, data);
});

document.addEventListener('RoktPlatformEvent', (event) => {
  // Transférez tous les événements de la plateforme à votre backend
  fetch('/api/rokt-events', {
    method: 'POST',
    body: JSON.stringify(event.detail)
  });
});

Nettoyage et gestion des erreurs

Nettoyage approprié

Lorsque vous retirez un composant contenant rokt-layout-view, assurez-vous d'effectuer un nettoyage approprié :

// En JS vanilla
function cleanup() {
  const roktElement = document.getElementById('rokt-placement');
  if (roktElement) {
    roktElement.close();
  }
}

// En React
useEffect(() => {
  return () => {
    if (roktRef.current) {
      roktRef.current.close();
    }
  };
}, []);

Gestion des erreurs

Implémentez une gestion appropriée des erreurs lors de l'utilisation du Rokt UX Helper :

try {
  const experienceData = await fetchExperienceData();
  if (!experienceData || !experienceData.plugins || experienceData.plugins.length === 0) {
    console.warn('Aucune expérience à rendre');
    return;
  }

  roktElement.renderExperiences(experienceData);
} catch (error) {
  console.error('Échec du rendu des expériences Rokt :', error);
  // Implémentez un comportement de secours si nécessaire
}

// Écoutez les échecs de mise en page
roktElement.addEventListener('RoktUXEvent', (event) => {
  if (event.detail.eventName === 'LayoutFailure') {
    console.error('Échec du rendu de la mise en page :', event.detail);
    // Implémentez un comportement de secours
  }
});

Considérations de performance

Pour une performance optimale lors de l'utilisation du Rokt UX Helper :

1. Chargement différé (Lazy Loading) : Envisagez de charger de manière différée la bibliothèque Rokt UX Helper, surtout si les expériences ne sont pas visibles immédiatement :

// Chargez la bibliothèque uniquement lorsque nécessaire
function loadRoktUXHelper() {
  return import('@rokt/ux-helper-web').then(() => {
    console.log('Rokt UX Helper chargé');
    // Initialisez et rendez les expériences
  });
}

// Utilisez avec Intersection Observer pour un chargement basé sur la visibilité
const observer = new IntersectionObserver((entries) => {
  if (entries[0].isIntersecting) {
    loadRoktUXHelper();
    observer.disconnect();
  }
}, { threshold: 0.1 });

observer.observe(document.getElementById('rokt-container'));