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 serveur à serveur (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 balises de versionLien direct vers 🔹 Explication des balises de version

  • @stable : Cette balise pointe vers la dernière version prête pour la production de la bibliothèque. Elle est recommandée pour les applications nécessitant stabilité et fiabilité.
  • @latest : Cette balise pointe vers la version la plus récente, incluant de nouvelles fonctionnalités et améliorations qui peuvent ne pas encore être entièrement testées. Utilisez-la 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 :

<!-- Use the latest stable version -->
<script src="https://cdn.jsdelivr.net/npm/@rokt/ux-helper-web/dist/index.cjs"></script>

<!-- Or use the latest version with newest features -->
<script src="https://cdn.jsdelivr.net/npm/@rokt/ux-helper-web@latest/dist/index.cjs"></script>

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

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

Ajouter rokt-layout-viewLien direct vers Ajouter rokt-layout-view

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

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

<body>
  <!-- Your content -->

  <!-- Note the ID which is used in the JavaScript below -->
  <rokt-layout-view id="rokt-layout-placeholder"></rokt-layout-view>

  <!-- Your content -->

  <!-- This is the JavaScript that handles events described below -->
  <script src="./index.js"></script>
</body>

Enregistrer l'élément et rendre la charge utileLien direct vers Enregistrer l'élément et rendre la charge utile

Maintenant que vous avez ajouté votre rokt-layout-view, vous devez l'enregistrer et transmettre la charge utile à rendre.

index.js
// This function would load the experiences data from your backend service or similar
const payload = fetchExperienceData();

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

// Note: The custom elements are automatically registered when the library is loaded,
// so you don't need to explicitly call registerCustomElements()

Gestion des expériences en superpositionLien direct vers Gestion des expériences en superposition

Pour prendre en charge les expériences en superposition qui ciblent le sélecteur de corps, ajoutez l'attribut render-overlay :

<body>
  <!-- Your content -->

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

  <!-- Your content -->
  <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) => {
    // Use these events to tailor your user experience
    console.log('RoktUXEvent received:', 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é lorsqu'une mise en page est fermée par l'utilisateur
LayoutCompletedDéclenché lorsque la progression de l'offre se termine sans plus d'offres à afficher
LayoutFailureDéclenché lorsqu'une mise en page ne parvient pas à s'afficher

Événements de plateformeLien direct vers Événements de plateforme

Les événements de plateforme sont essentiels pour l'intégration et doivent être envoyés à Rokt via votre backend. Ces événements renvoient 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) => {
    // Forward this payload to Rokt via your 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 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 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 :

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

Cet exemple envoie un événement de mise à jour d'article de 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 dans votre projet et tirer pleinement parti 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" />

    <!-- Load Rokt UX Helper from CDN -->
    <script src="https://cdn.jsdelivr.net/npm/@rokt/ux-helper-web/dist/index.cjs"></script>
  </head>
  <body>
    <h1>Rokt UX Helper Demo</h1>

    <!-- Note the ID which is used in the JavaScript below -->
    <!-- It is possible to use a single `rokt-layout-view` element to handle your embedded and overlay layouts -->
    <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
// This function would load the experiences data from your backend service
const payload = fetchExperienceData();

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

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

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

  // Send to your backend to forward to Rokt
  fetch("/api/rokt-events", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify(event.detail),
  });
});

// Render the experience with the payload from your 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 mises en page Rokt sur votre site web. C'est un composant web qui peut être ajouté à votre vue HTML et utilisé pour rendre la charge utile 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 de corps, 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 du DOM.

Comment déterminer si j'ai besoin d'expériences intégrées ou en superposition ?Lien direct vers Comment déterminer si j'ai besoin d'expériences intégrées ou en superposition ?

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 souhaitez que l'expérience respecte la disposition du contenu environnant
<rokt-layout-view id="rokt-placement"></rokt-layout-view>

Expériences en superpositionLien direct vers Expériences en superposition

Les expériences en superposition apparaissent au-dessus de votre contenu, couvrant potentiellement 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 la concentration 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 gestionnaire de compte Rokt peut vous aider à déterminer quel type convient le mieux à vos besoins en fonction de vos objectifs commerciaux et de vos exigences de conception.

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 le 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('Experience is successfully rendered and interactive');
  }
});

Que dois-je faire si j'ai besoin de plusieurs emplacements de placement ?Lien direct vers Que dois-je faire si j'ai besoin de plusieurs emplacements de placement ?

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

Comment déboguer les problèmes d'intégration ?Lien direct vers Comment déboguer les problèmes d'intégration ?

Vérifiez votre console de navigateur pour tout avertissement ou erreur provenant de 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 shadow. 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 composants Web (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 changements de 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 Aug 4, 2026