Aller au contenu principal

Web UX Helper

Rokt UX Helper est un projet open source qui vous aide à rendre de belles expériences client dans un environnement serveur-à-serveur. Vous pouvez trouver et contribuer au projet sur GitHub.

Vue d'ensemble​

Rokt UX Helper exploite la technologie des composants web pour fournir une solution simple et maintenable pour rendre les expériences Rokt sur votre site web. L'élément personnalisé rokt-layout-view gère le rendu des expériences en fonction de la charge utile reçue de votre serveur.

Étapes d'intégration​

Ce document décrit le processus d'intégration de Rokt UX Helper dans votre projet web, qui fonctionne en parallèle avec l'intégration Server-to-Server (S2S) pour offrir des expériences pertinentes à vos clients lors de leur passage en caisse.

📦 Guide d'installation​

La bibliothèque est disponible en tant que package npm. Pour l'installer, utilisez les commandes suivantes :

npm install @rokt/ux-helper-web@stable

Pour tester de nouvelles fonctionnalités, utilisez @latest au lieu de @stable :

npm install @rokt/ux-helper-web@latest

🔹 Explication des tags de version​

  • @stable : Ce tag pointe vers la dernière version prête pour la production de la bibliothèque. Il est recommandé pour les applications qui nécessitent stabilité et fiabilité.
  • @latest : Ce tag pointe vers la version la plus récente, incluant de nouvelles fonctionnalités et améliorations qui peuvent ne pas encore être complètement testées. Utilisez-le uniquement à des fins de développement et de test pour accéder aux dernières mises à jour avant qu'elles ne soient officiellement marquées comme stables.

Utilisation du CDN​

Si vous préférez utiliser un CDN, vous pouvez inclure la bibliothèque directement dans votre HTML :

<!-- Utilisez la dernière version stable -->
<script src="https://cdn.jsdelivr.net/npm/@rokt/ux-helper-web/dist/index.cjs"></script>

<!-- Ou utilisez la dernière version avec les fonctionnalités les plus récentes -->
<script src="https://cdn.jsdelivr.net/npm/@rokt/ux-helper-web@latest/dist/index.cjs"></script>

Le package fournit également différents formats de modules :

<!-- 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>

Ajouter rokt-layout-view​

Pour commencer à utiliser Rokt UX Helper, vous devez ajouter le script Rokt UX Helper intégré, ajouter rokt-layout-view à la partie pertinente de votre vue HTML et ajouter votre JavaScript.

<head>
  <!-- Lien vers votre JavaScript Rokt UX Helper -->
  <script src="https://cdn.jsdelivr.net/npm/@rokt/ux-helper-web/dist/index.cjs"></script>
</head>

<body>
  <!-- Votre contenu -->

  <!-- Notez l'ID qui est utilisé dans le JavaScript ci-dessous -->
  <rokt-layout-view id="rokt-layout-placeholder"></rokt-layout-view>

  <!-- Votre contenu -->

  <!-- Ceci est le JavaScript qui gère les événements décrits ci-dessous -->
  <script src="./index.js"></script>
</body>

Enregistrer l'élément et rendre le payload​

Maintenant que vous avez ajouté votre rokt-layout-view, vous devez l'enregistrer et passer le payload à rendre.

index.js
// Cette fonction chargerait les données d'expériences depuis votre service backend ou similaire
const payload = fetchExperienceData();

const roktElement = document.getElementById("rokt-layout-placeholder");
roktElement.renderExperiences(payload);

// Remarque : Les éléments personnalisés sont automatiquement enregistrés lorsque la bibliothèque est chargée,
// donc vous n'avez pas besoin d'appeler explicitement registerCustomElements()

Gestion des expériences superposées​

Pour prendre en charge les expériences superposées qui ciblent le sélecteur body, ajoutez l'attribut render-overlay :

<body>
  <!-- Votre contenu -->

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

  <!-- Votre contenu -->
  <script src="./index.js"></script>
</body>

Gestion des événements​

Rokt UX Helper fournit deux types d'événements pour vous aider à suivre les interactions des utilisateurs et à communiquer avec la plateforme Rokt.

Événements UX​

Utilisez les événements UX pour recevoir des retours en temps réel sur les interactions des utilisateurs :

roktElement.addEventListener('RoktUXEvent', (event) => {
    // Utilisez ces événements pour adapter votre expérience utilisateur
    console.log('RoktUXEvent reçu :', event.detail);
});
Tous les événements UX
ÉvénementDescription
OfferEngagementDéclenché lorsque l'utilisateur interagit avec l'offre
PositiveEngagementDéclenché lorsque l'utilisateur interagit positivement avec l'offre
LayoutInteractiveDéclenché lorsqu'une mise en page est rendue et interactive
LayoutClosedDéclenché lorsque l'utilisateur ferme une mise en page
LayoutCompletedDéclenché lorsque la progression de l'offre se termine sans plus d'offres à afficher
LayoutFailureDéclenché lorsqu'une mise en page échoue à s'afficher

Événements de la plateforme​

Les événements de la plateforme sont essentiels pour l'intégration et doivent être envoyés à Rokt via votre backend. Ces événements retournent une charge utile JSON complète avec les données de l'événement et les détails de l'intégration :

roktElement.addEventListener('RoktPlatformEvent', (event) => {
    // Transmettez cette charge utile à Rokt via votre backend
    fetch('/api/rokt-events', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(event.detail)
    });
});
Exemple de charge utile d'événement de la plateforme
{
    "events": [
        {
            "eventType": "SignalImpression",
            "eventTime": "2024-12-05T04:42:54.683Z",
            "sessionId": "b23d004d-b2e6-43e9-b254-d9193e650000",
            "parentGuid": "9b6f0e5b-621d-4597-8a73-71d6a5b43a74",
            "pageInstanceGuid": "b23d004d-b2e6-4b82-b7a2-84a13b6c57c5",
            "metadata": [
                {
                    "name": "clientTimeStamp",
                    "value": "2024-12-05T04:42:54.683Z"
                },
                {
                    "name": "captureMethod",
                    "value": "ClientProvided"
                }
            ]
        }
    ],
    "integration": {
        "name": "UX Helper Web",
        "version": "1.0",
        "framework": "JS",
        "platform": "Web",
        "layoutSchemaVersion": "1.3.0",
        "deviceLocale": "en-GB",
        "deviceModel": "Desktop Computer",
        "deviceType": "Desktop",
        "operatingSystem": "MacOS",
        "operatingSystemVersion": "10.15.7",
        "packageName": "UX Helper Web",
        "packageVersion": "1.0"
    },
    "pluginId": "3333926045359669274"
}

Pour plus de détails sur les événements de la plateforme, consultez la référence API.

Envoi d'événements aux mises en page​

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

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

Cet exemple envoie un événement de mise à jour d'un article du panier auquel les mises en page peuvent répondre, comme la mise à jour des offres promotionnelles en fonction des quantités.

Résumé​

L'intégration de rokt-layout-view dans votre projet est simple et offre un moyen flexible de gérer les vues et les expériences. En suivant les étapes décrites dans ce guide, vous pouvez ajouter rokt-layout-view à votre projet et profiter pleinement des fonctionnalités puissantes offertes par Rokt UX Helper.

Exemple complet​

HTML​

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Rokt UX Helper</title>
    <link rel="stylesheet" href="./index.css" />

    <!-- Charger Rokt UX Helper depuis le CDN -->
    <script src="https://cdn.jsdelivr.net/npm/@rokt/ux-helper-web/dist/index.cjs"></script>
  </head>
  <body>
    <h1>Démo de Rokt UX Helper</h1>

    <!-- Notez l'ID utilisé dans le JavaScript ci-dessous -->
    <!-- Il est possible d'utiliser un seul élément `rokt-layout-view` pour gérer vos mises en page intégrées et superposées -->
    <rokt-layout-view
      id="rokt-layout-placeholder"
      render-overlay
    ></rokt-layout-view>

    <script src="./index.js"></script>
  </body>
</html>

JavaScript​

index.js
// Cette fonction chargerait les données d'expériences depuis votre service backend
const payload = fetchExperienceData();

const roktElement = document.getElementById("rokt-layout-placeholder");

roktElement.addEventListener("RoktUXEvent", (event) => {
  console.log("RoktUXEvent reçu : ", event.detail);
});

roktElement.addEventListener("RoktPlatformEvent", (event) => {
  console.log("RoktPlatformEvent reçu : ", event.detail);

  // Envoyer à votre backend pour transmettre à Rokt
  fetch("/api/rokt-events", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify(event.detail),
  });
});

// Rendre l'expérience avec les données de votre backend
roktElement.renderExperiences(payload);

🙋 FAQ​

Qu'est-ce que le rokt-layout-view ?​

Le rokt-layout-view est un élément personnalisé utilisé pour rendre les Rokt Layouts sur votre site web. C'est un composant web qui peut être ajouté à votre vue HTML et utilisé pour rendre le payload de l'expérience.

Quelles sont les interfaces pour le rokt-layout-view ?​

L'interface rokt-layout-view est définie dans le package @rokt/ux-helper-web. Vous pouvez trouver l'interface ici : RoktLayoutViewInterface

export interface RoktLayoutViewInterface extends HTMLElement {
  renderExperiences(data: ExperiencesResponseInterface): void;
  close(): void;
  send<T>(name: string, data?: T): Promise<void>;
}

Comment gérer les expériences en superposition ?​

Pour prendre en charge les expériences en superposition qui ciblent le sélecteur body, ajoutez l'attribut render-overlay à votre élément rokt-layout-view. Il est recommandé de placer l'élément de superposition à la fin de la balise <body> pour assurer un empilement correct des z-index et éviter les conflits potentiels dans le DOM.

Comment déterminer si j'ai besoin d'expériences intégrées ou superposées ?​

Expériences intégrées​

Les expériences intégrées s'intègrent directement dans la mise en page de votre page à des points spécifiques. Utilisez-les lorsque :

  • Vous souhaitez que l'expérience apparaisse dans le flux de votre page
  • Vous avez un emplacement spécifique où le contenu doit être affiché
  • Vous voulez que l'expérience respecte la mise en page du contenu environnant
<rokt-layout-view id="rokt-placement"></rokt-layout-view>

Expériences superposées​

Les expériences superposées apparaissent au-dessus de votre contenu, pouvant potentiellement couvrir des parties de votre page. Utilisez-les lorsque :

  • Vous souhaitez que l'expérience apparaisse comme une boîte de dialogue modale ou un popup
  • Le contenu doit attirer l'attention et le focus de l'utilisateur
  • L'expérience doit être visuellement séparée du contenu principal de la page
<rokt-layout-view id="rokt-overlay" render-overlay></rokt-layout-view>

Votre Rokt Account Manager peut vous aider à déterminer quel type convient le mieux à vos besoins en fonction de vos objectifs commerciaux et de vos exigences en matière de design.

Comment puis-je détecter si l'expérience a été rendue avec succès ?​

Vous pouvez écouter l'événement RoktUXEvent avec le type d'événement LayoutInteractive, qui est déclenché lorsqu'une mise en page est rendue avec succès et prête pour l'interaction :

roktElement.addEventListener('RoktUXEvent', (event) => {
  if (event.detail.eventName === 'LayoutInteractive') {
    console.log('L'expérience est rendue avec succès et interactive');
  }
});

Que dois-je faire si j'ai besoin de plusieurs emplacements ?​

Vous pouvez ajouter plusieurs éléments rokt-layout-view avec des IDs différents pour cibler différents emplacements sur votre page. Chaque élément doit avoir un ID unique qui correspond au sélecteur cible dans vos expériences configurées.

Comment puis-je déboguer les problèmes d'intégration ?​

Vérifiez la console de votre navigateur pour tout avertissement ou erreur provenant du Rokt UX Helper. Vous pouvez également utiliser l'inspecteur d'éléments du navigateur pour examiner les éléments rokt-layout-view et leur contenu DOM ombré. Pour un débogage plus détaillé, consultez le guide de dépannage.

Le Web UX Helper est-il compatible avec tous les navigateurs ?​

Le Web UX Helper est compatible avec tous les navigateurs modernes qui prennent en charge les Web Components (Chrome, Firefox, Safari, Edge). Pour les navigateurs plus anciens, vous devrez peut-être utiliser des polyfills.

Quels événements puis-je envoyer au rokt-layout-view ?​

Vous pouvez envoyer divers événements pour communiquer avec les mises en page rendues. Un exemple courant est l'événement V2_UPDATE_CART_ITEM, qui vous permet d'informer les mises en page des modifications du panier :

await roktElement.send('V2_UPDATE_CART_ITEM', {
  cartItemId: "item-123",
  quantity: 2
});

Cela aide à créer des expériences dynamiques qui réagissent aux actions des utilisateurs dans votre application. Pour plus d'événements, consultez la référence API.

Comment puis-je contribuer au projet ?​

En tant que projet open source, nous accueillons les contributions ! Visitez notre répertoire GitHub pour soumettre des problèmes, créer des pull requests ou explorer le code source.

Existe-t-il des guides avancés pour le Web UX Helper ?​

Oui, pour une utilisation plus avancée, consultez le Guide Avancé du Web UX Helper.

Cet article vous a-t-il été utile ?
Last updated Oct 29, 2025