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 :

<!-- Primary placement -->
<rokt-layout-view id="rokt-primary"></rokt-layout-view>

<!-- Secondary placement -->
<rokt-layout-view id="rokt-secondary"></rokt-layout-view>

<!-- Overlay placement -->
<rokt-layout-view id="rokt-overlay" render-overlay></rokt-layout-view>

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

// Get the experience data that contains multiple plugins
const experienceData = await fetchExperienceData();

// Render experiences to all placement elements
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 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 Corps : Un plugin avec targetElementSelector: "body" ciblera les éléments avec l'attribut render-overlay.

Communication d'Événements

Envoi d'Événements aux Dispositions

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

// Send a cart update event to all rendered layouts
await roktElement.send('V2_UPDATE_CART_ITEM', {
    cartItemId: "item-123",
    quantity: 2
});

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

Gestion des Événements de Tous les Placements

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(`UX Event from plugin ${pluginId}:`, eventName, data);
});

document.addEventListener('RoktPlatformEvent', (event) => {
  // Forward all platform events to your backend
  fetch('/api/rokt-events', {
    method: 'POST',
    body: JSON.stringify(event.detail)
  });
});

Nettoyage et Gestion des Erreurs

Nettoyage Approprié

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

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

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

Gestion des Erreurs

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

try {
  const experienceData = await fetchExperienceData();
  if (!experienceData || !experienceData.plugins || experienceData.plugins.length === 0) {
    console.warn('No experiences to render');
    return;
  }

  roktElement.renderExperiences(experienceData);
} catch (error) {
  console.error('Failed to render Rokt experiences:', error);
  // Implement fallback behavior if needed
}

// Listen for layout failures
roktElement.addEventListener('RoktUXEvent', (event) => {
  if (event.detail.eventName === 'LayoutFailure') {
    console.error('Layout failed to render:', event.detail);
    // Implement fallback behavior
  }
});

Considérations de Performance

Pour des performances optimales lors de l'utilisation de Rokt UX Helper :

1. Chargement Paresseux : Envisagez de charger paresseusement la bibliothèque Rokt UX Helper, surtout si les expériences ne sont pas visibles immédiatement :

// Load the library only when needed
function loadRoktUXHelper() {
  return import('@rokt/ux-helper-web').then(() => {
    console.log('Rokt UX Helper loaded');
    // Initialize and render experiences
  });
}

// Use with Intersection Observer for visibility-based loading
const observer = new IntersectionObserver((entries) => {
  if (entries[0].isIntersecting) {
    loadRoktUXHelper();
    observer.disconnect();
  }
}, { threshold: 0.1 });

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