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'ensembleLien direct vers 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égrationLien direct vers É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'installationLien direct vers 📦 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 versionLien direct vers 🔹 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 CDNLien direct vers 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-viewLien direct vers 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 payloadLien direct vers 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éesLien direct vers 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énementsLien direct vers 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 UXLien direct vers É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 plateformeLien direct vers É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 pageLien direct vers 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éLien direct vers 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 completLien direct vers Exemple complet

HTMLLien direct vers 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>

JavaScriptLien direct vers 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);

🙋 FAQLien direct vers 🙋 FAQ

Qu'est-ce que le rokt-layout-view ?Lien direct vers 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 ?Lien direct vers 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 ?Lien direct vers 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 ?Lien direct vers Comment déterminer si j'ai besoin d'expériences intégrées ou superposées ?

Expériences intégréesLien direct vers 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éesLien direct vers 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 ?Lien direct vers 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 ?Lien direct vers 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 ?Lien direct vers 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 ?Lien direct vers 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 ?Lien direct vers 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 ?Lien direct vers 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 ?Lien direct vers 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