Guide d'Intégration du SDK Web

Cette page explique comment implémenter le SDK Web pour Rokt Ecommerce afin de fournir des expériences client plus pertinentes lors du passage en caisse. Le SDK vous permet de déclencher et de suivre ces expériences (comme l'affichage d'offres sur les pages de confirmation) en s'activant sur des pages configurées et en transmettant les données utilisateur et de transaction à Rokt pour la personnalisation et la mesure.

Votre représentant de compte dédié vous aidera à configurer votre compte pour le SDK Web. Ils vous fourniront à la fois la clé API nécessaire pour initialiser le SDK et des ressources supplémentaires nécessaires pour rendre les expériences les plus pertinentes pour vos clients.

remarque

Ces instructions nécessitent des ressources de développement pour être complétées. Si vous avez besoin d'une assistance supplémentaire, veuillez contacter votre gestionnaire de compte Rokt. Les boutiques Shopify peuvent configurer un emplacement Rokt en quelques secondes en utilisant l'application Rokt Ecommerce — aucun codage nécessaire !

remarque

Travaillez avec votre gestionnaire de compte Rokt pour d'abord implémenter le SDK dans un environnement de développement. Cela vous permet de tester et de dépanner minutieusement votre intégration avant de la déployer dans un environnement de production.

Configuration de domaine de première partie

Rokt recommande d'utiliser un domaine de première partie lors de l'intégration du SDK sur votre site. Cela garantit que le SDK de Rokt utilise votre propre domaine lors des appels à l'API de Rokt, offrant à vos clients une expérience fluide et minimisant le risque de contenu bloqué.

Pour apprendre à configurer un domaine de première partie pour votre intégration SDK, consultez Intégration de Domaine de Première Partie.

1. Initialiser le SDK Rokt

Pour initialiser le SDK, copiez et collez l'intégralité du script d'initialisation du SDK dans votre site.

Chaque site est différent, mais Rokt recommande d'inclure le script d'initialisation du SDK sur chaque page de votre site. Cela garantit que le SDK s'initialise toujours, offrant la latence de livraison d'offres la plus basse et la précision d'identification utilisateur la plus élevée.

Applications à page unique (SPA) : Si votre site Web est une SPA, insérez le script d'initialisation dans le <head> de la page principale index.html, ou l'emplacement principal où le reste de votre contenu est rendu.
Applications à pages multiples (MPA) : Si votre site Web est une MPA et que vous utilisez un système de rendu basé sur des modèles (le plus courant), placez le script d'initialisation dans le fichier de mise en page partagé principal. Si vous n'utilisez pas un système de rendu basé sur des modèles, placez le script dans chaque fichier HTML de votre site Web.

Notez que bien que chaque page puisse inclure le script, en raison de la mise en cache du navigateur, le SDK se chargera par défaut à partir du cache plutôt que d'être chargé à chaque chargement de page de votre site Web.

Script d'initialisation du SDK

<script type="text/javascript">

// Entrez votre clé API Rokt
const API_KEY = "YOUR_API_KEY";

// Entrez votre sous-domaine personnalisé si vous utilisez une configuration de domaine de première partie (optionnel)
const ROKT_DOMAIN = "https://apps.rokt-api.com";

window.mParticle = {
    config: {
        // Définissez l'environnement de données :
        // Réglez isDevelopmentMode sur true si vous testez encore votre intégration. 
        // Réglez isDevelopmentMode sur false si votre intégration est prête pour les données de production.
        isDevelopmentMode: true,
        // Identifiez l'utilisateur actuel :
        // Si vous n'avez pas l'adresse e-mail de l'utilisateur, vous pouvez passer une valeur null
        identifyRequest: {
            userIdentities: {
                // Si vous utilisez une adresse e-mail non hachée, définissez-la dans 'email'.
                email: 'j.smith@example.com',
                // Si vous utilisez une adresse e-mail hachée, définissez-la dans 'other' au lieu de `email`.
                other: 'sha256 hashed email goes here'
            }
        },
        // Si l'utilisateur est identifié par son adresse e-mail, définissez des attributs utilisateur supplémentaires.
        identityCallback: function(result) {
            if (result.getUser()) {
                result.getUser().setUserAttribute('attribute-key', 'attribute-value');
            }
        }
    }
};

// Charger le SDK
(function(e) { window.mParticle = window.mParticle || {}; window.mParticle.EventType = { Unknown: 0, Navigation: 1, Location: 2, Search: 3, Transaction: 4, UserContent: 5, UserPreference: 6, Social: 7, Other: 8, Media: 9 }; window.mParticle.eCommerce = { Cart: {} }; window.mParticle.Identity = {}; window.mParticle.Rokt = {}; window.mParticle.config = window.mParticle.config || {}; window.mParticle.config.rq = []; window.mParticle.config.snippetVersion = 2.7; window.mParticle.ready = function(e) { window.mParticle.config.rq.push(e); }; ["endSession", "logError", "logBaseEvent", "logEvent", "logForm", "logLink", "logPageView", "setSessionAttribute", "setAppName", "setAppVersion", "setOptOut", "setPosition", "startNewSession", "startTrackingLocation", "stopTrackingLocation"].forEach(function(e) { window.mParticle[e] = function() { var t = Array.prototype.slice.call(arguments); t.unshift(e); window.mParticle.config.rq.push(t); }; }); ["setCurrencyCode", "logCheckout"].forEach(function(e) { window.mParticle.eCommerce[e] = function() { var t = Array.prototype.slice.call(arguments); t.unshift("eCommerce." + e); window.mParticle.config.rq.push(t); }; }); ["identify", "login", "logout", "modify"].forEach(function(e) { window.mParticle.Identity[e] = function() { var t = Array.prototype.slice.call(arguments); t.unshift("Identity." + e); window.mParticle.config.rq.push(t); }; }); ["selectPlacements","hashAttributes","setExtensionData","use","getVersion","terminate"].forEach(function(e) { window.mParticle.Rokt[e] = function() { var t = Array.prototype.slice.call(arguments); t.unshift("Rokt." + e); window.mParticle.config.rq.push(t); }; }); var t = window.mParticle.config.isDevelopmentMode ? 1 : 0, n = "?env=" + t, a = window.mParticle.config.dataPlan; if (a) { var o = a.planId, r = a.planVersion; o && (r && (r < 1 || r > 1e3) && (r = null), n += "&plan_id=" + o + (r ? "&plan_version=" + r : "")); } var i = window.mParticle.config.versions, s = []; i && Object.keys(i).forEach(function(e) { s.push(e + "=" + i[e]); }); var c = document.createElement("script"); c.type = "text/javascript"; c.async = !0; window.ROKT_DOMAIN = ROKT_DOMAIN || 'https://apps.rokt-api.com'; mParticle.config.domain = ROKT_DOMAIN.split('//')[1]; c.src = ROKT_DOMAIN + "/js/v2/" + e + "/app.js" + n + "&" + s.join("&"); var l = document.getElementsByTagName("script")[0]; l.parentNode.insertBefore(c, l); })(API_KEY);
</script>

Lors de l'insertion du script d'initialisation dans votre site, configurez les paramètres suivants :

1.1 Entrez votre clé API Rokt

Définissez API_KEY sur la clé API Rokt fournie par votre gestionnaire de compte Rokt dédié.

Votre clé API Rokt est une information d'identification unique fournie par votre représentant de compte Rokt qui permet à votre site de se connecter et d'interagir en toute sécurité avec le SDK Rokt.

1.2 Entrez votre sous-domaine personnalisé (optionnel)

Si vous souhaitez router le SDK via votre propre domaine, suivez les instructions dans Configuration de domaine de première partie, et définissez ROKT_DOMAIN sur le sous-domaine que vous avez créé.

Un sous-domaine personnalisé permet au SDK Rokt d'être routé via votre propre domaine, réduisant ainsi le risque que les publicités ou les données soient bloquées par les navigateurs ou les bloqueurs de publicité.

Cette étape est optionnelle. Vous pouvez laisser ROKT_DOMAIN défini sur https://apps.rokt-api.com, mais les requêtes vers le SDK Rokt seront routées via apps.rokt-api.com.

1.3 Configurer votre environnement de données

Rokt maintient deux environnements de données : Développement pour l'étiquetage et le stockage des données à des fins de test et Production pour la collecte de l'activité réelle des clients.

Si vous êtes encore en train de tester le SDK Rokt, réglez isDevelopmentMode sur true.

Si vous avez terminé les tests et souhaitez commencer à collecter l'activité réelle des clients, réglez isDevelopmentMode sur false.

1.4 Identifier l'utilisateur

Lorsque le SDK est initialisé, il peut identifier l'utilisateur actuel afin que toutes les données collectées lui soient correctement attribuées et pour s'assurer qu'il voit les publicités les plus pertinentes en fonction de son comportement.

Le script d'initialisation du SDK inclut un objet appelé identifyRequest :

identifyRequest: {
    userIdentities: {
        // Définissez l'adresse e-mail brute de l'utilisateur dans 'email'
        email: 'j.smith@example.com',
        // Définissez l'adresse e-mail hachée de l'utilisateur dans 'other'
        other: 'sha256 hashed email goes here'
    }
}

Dans identifyRequest, passez l'adresse e-mail de l'utilisateur dans le champ email si elle n'est pas hachée ou other si elle est hachée en utilisant SHA256.

Incluez toujours identifyRequest dans le script d'initialisation, même si vous n'avez pas l'adresse e-mail de l'utilisateur au moment de l'initialisation.

remarque

Si vous n'avez pas l'adresse e-mail de l'utilisateur, passez une valeur nulle. Le SDK s'initialisera toujours, et vous pourrez identifier l'utilisateur plus tard en suivant les instructions dans 2. Identifier l'Utilisateur.

1.5 Définir des attributs utilisateur supplémentaires

Le script d'initialisation inclut une fonction de rappel (callback) qui vous permet de définir des attributs utilisateur supplémentaires si l'utilisateur est identifié avec succès via son adresse e-mail :

// Le identityCallback détermine si le identifyRequest a réussi.
identityCallback: function(result) {
    if (result.getUser()) {
        // Si l'utilisateur a été identifié, définissez des attributs utilisateur supplémentaires avec setUserAttribute.
        result.getUser().setUserAttribute('attribute-key', 'attribute-value');
    }
}

Pour une liste des attributs que Rokt recommande de collecter pour vos utilisateurs, consultez Attributs utilisateur recommandés.

2. Identifier l'utilisateur

Lors de l'initialisation, le SDK soumet un identifyRequest à Rokt avec l'adresse e-mail de l'utilisateur pour identifier l'utilisateur actuel.

En plus d'identifier l'utilisateur lors de l'initialisation, chaque fois que l'utilisateur fournit son adresse e-mail après l'initialisation du SDK (par exemple, lorsqu'il se connecte ou effectue un achat), vous devez appeler la méthode identify pour transmettre son e-mail à Rokt. Cela garantit que les données sont correctement attribuées à l'utilisateur actuel.

Pour identifier l'utilisateur, commencez par créer un objet identifyRequest pour contenir l'adresse e-mail de l'utilisateur.

Si vous fournissez une adresse e-mail non hachée, utilisez :

const identifyRequest = { 
    userIdentities: { 
        email: 'j.smith@example.com' 
    }
};

Si vous fournissez une adresse e-mail hachée, utilisez :

const identifyRequest = { 
    userIdentities: { 
        other: 'sha256 hashed email goes here' 
    }
};

Ensuite, vous avez la possibilité de définir des attributs utilisateur supplémentaires lors de l'identification d'un utilisateur en créant une fonction de rappel. Si le identifyRequest réussit, alors les attributs utilisateur que vous définissez avec setUserAttribute sont assignés à l'utilisateur.

const identityCallback = function(result) { 
    if (result.getUser()) { 
        result.getUser().setUserAttribute('attribute-key', 'attribute-value');	
    }
};

Pour une liste des attributs que Rokt recommande de collecter pour vos utilisateurs, consultez Attributs utilisateur recommandés.

Enfin, après avoir créé votre identifyRequest et votre identityCallback pour définir tous les attributs supplémentaires, appelez la méthode identify, en passant les objets identifyRequest et identityCallback que vous venez de créer :

mParticle.Identity.identify(identifyRequest, identityCallback);

Par exemple, pour identifier un utilisateur nommé Jane Smith avec l'adresse e-mail j.smith@example.com (et vous n'avez pas besoin de hacher son adresse e-mail), vous utiliseriez :

const identifyRequest = { 
    userIdentities: { 
        email: 'j.smith@example.com' 
    }
};

const identityCallback = function(result) { 
    if (result.getUser()) { 
        result.getUser().setUserAttribute('firstname', 'Jane');
        result.getUser().setUserAttribute('lastname', 'Smith');
    }
};

mParticle.Identity.identify(identifyRequest, identityCallback);

3. Définir les attributs utilisateur

Les exemples ci-dessus montrent comment définir des attributs utilisateur lorsque l'utilisateur est identifié lors de l'initialisation du SDK et lorsque l'utilisateur est identifié après avoir fourni son adresse e-mail.

Cependant, après que l'utilisateur a été identifié, vous pouvez définir des attributs utilisateur à tout moment. Ces attributs sont inclus avec vos placements publicitaires ou événements enregistrés. Vous pouvez également définir des attributs utilisateur directement lors de l'insertion d'un placement.

Pour définir des attributs utilisateur, exécutez ce qui suit :

// Pour récupérer l'utilisateur actuel, appelez getCurrentUser.
const currentUser = mParticle.Identity.getCurrentUser();

// Une fois que vous avez défini avec succès l'utilisateur actuel dans une constante appelée `currentUser`, vous pouvez définir des attributs utilisateur avec :
currentUser.setUserAttribute("user-attribute-key", "user-attribute-value");

// Pour définir un attribut de liste, définissez la valeur de l'attribut sur un tableau de chaînes. Par exemple :
currentUser.setUserAttribute("favorite-genres", ["documentary", "comedy", "romance", "drama"]);

// Pour supprimer un attribut utilisateur, appelez removeUserAttribute et passez le nom de l'attribut. Tous les attributs utilisateur partagent le même espace de clés.
currentUser.removeUserAttribute("attribute-to-remove");

Attributs utilisateur recommandés

Rokt recommande de définir autant que possible les attributs utilisateur suivants :

Clé de l'attribut utilisateur	Valeur d'exemple	Remarques
firstname	John	Le prénom du client.
lastname	Doe	Le nom de famille du client.
mobile	3125551515	Les numéros de téléphone peuvent être formatés soit comme `1112345678` ou `+1 (222) 345-6789`.
age	33	L'âge du client.
dob	19900717	Date de naissance. Formatée comme `yyyymmdd`.
gender	M	Le genre du client. Par exemple, `M`, `Male`, `F`, ou `Female`.
city	Brooklyn	La ville du client.
state	NY	L'état du client.
zip	11201	Le code postal du client.
title	Mr	Le titre du client. Par exemple, `Mr`, `Mrs`, `Ms`.
language	en	Langue associée à l'achat.
value	52.25	La valeur du client.
predictedltv	136.23	La valeur totale de la durée de vie prédite du client.

Tous les attributs utilisateur (y compris les attributs de liste et les balises) doivent avoir des noms distincts.

4. Suivre les événements du tunnel de conversion

Le SDK Rokt vous permet de mettre en œuvre le suivi des événements pour collecter des données décrivant les parcours de vos utilisateurs sur votre site. Vous pouvez ensuite utiliser ces données pour optimiser l'expérience de vos utilisateurs.

Il existe trois principaux types d'événements que vous pouvez suivre avec le SDK :

Événements de consultation de page (Page View Events) : Ce sont des événements que vous pouvez déclencher lorsqu'une page de votre site est chargée.
Événements personnalisés (Custom Events) : Ce sont des événements libres que vous créez pour suivre des informations spécifiques à votre site.
Événements commerciaux (Commerce Events) : Ce sont des événements spécifiques au commerce électronique qui peuvent décrire les différentes étapes de l'expérience d'achat, y compris l'ajout d'articles à un panier et la réalisation d'un achat final.

Lors de la première intégration avec le SDK Rokt, commencez par mettre en œuvre le suivi des consultations de pages. Pour en savoir plus sur le suivi des événements personnalisés et commerciaux, consultez l'Annexe.

Suivre les consultations de pages

L'un des types d'événements les plus basiques que vous pouvez suivre est la consultation de page.

Pour enregistrer une consultation de page, utilisez la méthode logPageView() après l'initialisation du SDK.

Dans l'exemple ci-dessous, l'événement inclut :

Un screen_name dérivé du dernier segment du chemin de l'URL (avec un retour par défaut à "home").
L'url complète de la page actuelle.
La referring-page, capturée à partir de document.referrer.

Cela est utile pour suivre la navigation des utilisateurs sur votre site sans avoir besoin de spécifier manuellement les identifiants de page.

// Attendre que le SDK soit entièrement chargé avant d'enregistrer l'événement
window.mParticle.ready(function() {
    mParticle.logPageView(
        // Nom de l'événement : "page view" identifie le type d'événement enregistré
        "page view",
        {
            // Capturer le dernier segment du chemin de l'URL comme nom d'écran,
            // par exemple, "/products/shoes" → "shoes". Par défaut, "home" si le chemin est vide.
            "screen_name": location.pathname.split("/").filter(Boolean).pop() || "home",

            // Enregistrer l'URL complète de la page actuelle (y compris le protocole, le chemin, la requête et le hash)
            "url": window.location.toString(),

            // Capturer l'URL de la page qui a référé l'utilisateur à celle-ci,
            // si disponible. Cela aide à suivre la navigation des utilisateurs entre les pages ou les sites.
            "referring-page": document.referrer
        }
    );
});

5. Afficher un Placement

La principale valeur du SDK Rokt est débloquée grâce à la méthode selectPlacements, qui sert un placement hyper-pertinent pour vos clients en fonction des attributs que vous fournissez.

Une fois que l'intégration Rokt a été initialisée, vous pouvez appeler la méthode selectPlacements sur n'importe quelle page ou composant de votre site où vous souhaitez qu'un placement soit servi. Vous devez appeler selectPlacements dès que la page a été chargée, que le SDK a été initialisé, et que les attributs suggérés montrés dans l'exemple de code ci-dessous sont disponibles pour être inclus dans votre appel.

Vous pouvez également passer un identifiant de page à identifier comme montré dans l'extrait ci-dessous. Cela identifie de manière unique la page où le placement Rokt sera ajouté, et est utile si vous avez un processus de paiement en plusieurs étapes qui utilise la même URL sur plusieurs pages. Vous pouvez utiliser n'importe quelle valeur pour votre identifiant de page, mais voici quelques exemples :

stg.rokt.conf - Une page de confirmation dans un environnement de staging (ou de test).
prod.rokt.conf - Une page de confirmation dans un environnement de production.
stg.rokt.payments - Une page de paiements dans un environnement de staging (ou de test).
prod.rokt.payments - Une page de paiements dans un environnement de production.

Lors de l'appel de selectPlacements, vous devez fournir au moins les attributs email, firstname, lastname, billingzipcode et confirmationref. Des attributs supplémentaires que vous pourriez vouloir inclure sont montrés dans l'exemple.

remarque

Tant les attributs utilisateur définis avant un appel à selectPlacements en utilisant currentUser.setUserAttribute que les attributs définis dans un appel à selectPlacements sont envoyés à Rokt. Cependant, si vous définissez un attribut utilisateur deux fois (avant l'appel à selectPlacements, et dans l'appel à selectPlacements), la valeur la plus récente définie dans l'appel à selectPlacements est utilisée.

Par exemple, si vous définissez le prénom de l'utilisateur en utilisant currentUser.setUserAttribute("firstname", "Johnathan") mais que vous incluez également "firstname": "John" dans l'objet attributes de selectPlacements, alors la valeur "John" est envoyée à Rokt.

window.mParticle.ready(async function () {
    const selection = await window.mParticle.Rokt.selectPlacements({
        identifier: "yourPageIdentifier",
        attributes: {
            "email": "j.smith@example.com", // Adresse email du client utilisée lors du paiement
            "firstname": "Jenny",           // Prénom du client
            "lastname": "Smith",            // Nom de famille du client
            "confirmationref": "54321",     // Numéro de référence de commande / confirmation
            "billingzipcode": "90210",      // Code postal de facturation du client
            "amount": "100.00",             // Montant de la transaction en décimal, par ex. 300.5
            "paymenttype": "VISA",          // Par ex. Carte cadeau | Chase, Visa
            "ccbin": "372888",              // BIN de la carte de crédit, par ex. 372888
            "mobile": "123-456-7890",       // Numéro de mobile / cellulaire du client
            "country": "USA",               // Code pays ISO Alpha-2
            "language": "en",               // Code de langue ISO 639-1 à 2 lettres
            "currency": "USD",              // Devise de la transaction, par ex. USD
            "billingaddress1": "",          // Adresse ligne 1 du client
            "billingaddress2": "",          // Adresse ligne 2 du client
            "age": "29",                    // Âge du client
            "gender": "f",                  // Sexe du client m / f
            "cartItems": JSON.stringify(["item 1", "item 2", "item 3"]), // Contenu du panier sous forme de chaîne
        
            // Vous pouvez également transmettre ici des attributs supplémentaires pertinents pour la transaction
            // Voir le lien ci-dessous pour une liste complète des attributs
            "shippingtype": "Priority Express"
        }
    });
});

S'abonner à un emplacement

En vous abonnant à un événement d'emplacement, vous pouvez recevoir des notifications qui sont déclenchées lorsqu'un emplacement est prêt ou lorsqu'un client interagit avec une offre.

window.mParticle.ready(async function () {
  // sélection
  const selection = await window.mParticle.Rokt.selectPlacements({
    // ajouter des attributs
  });
 
  // Écouter lorsque l'emplacement devient interactif/prêt à être affiché
  selection.on('PLACEMENT_INTERACTIVE').subscribe(() => {
    // Logique à exécuter après que l'emplacement soit devenu interactif
  });
 
  // Écouter lorsque l'utilisateur interagit positivement ou négativement avec une offre
  selection.on('OFFER_ENGAGEMENT').subscribe(function () {
    // Logique à exécuter après l'interaction avec l'offre
  });
});

Fonctionnalité supplémentaire via des extensions

Le lanceur d'intégration de base de Rokt gère la plupart des scénarios de commerce électronique, mais certaines fonctionnalités nécessitent des extensions. Vous pouvez activer ces extensions en appelant mParticle.Rokt.use() avant d'invoquer selectPlacements(). Cela permet d'ajouter des capacités optionnelles, telles que des emplacements de vente incitative après achat, sans modifier votre intégration de base.

Par exemple, pour afficher des emplacements de vente incitative sur une page de remerciement, assurez-vous d'activer d'abord l'extension ThankYouPageJourney :

window.mParticle.ready(async function() {
    // Activer l'extension nécessaire avant de sélectionner les emplacements
    await window.mParticle.Rokt.use("ThankYouJourney");

    const selection = await mParticle.Rokt.selectPlacements({
      identifier: "yourPageIdentifier",
      attributes: {
        "email": "j.smith@example.com"
        // Tous les attributs utilisateur supplémentaires que vous souhaitez transmettre à Rokt
      },
    });
})

Fermer un emplacement

Si votre site est une application monopage (single page application), une fois que vous avez servi un emplacement en appelant selectPlacements, il est important de fermer l'emplacement après que l'utilisateur a navigué vers une autre page. Cela empêche l'emplacement d'être toujours affiché à l'utilisateur lorsqu'il revient en arrière.

Pour fermer et supprimer un emplacement, appelez .close() sur l'objet d'emplacement que vous avez créé :

// Ferme l'emplacement appelé 'selection'
selection.close();

remarque

Pour une liste complète des attributs pris en charge, voir Attributs de données.

Votre équipe dédiée Rokt configurera vos dispositions d'emplacement pour vous afin qu'elles correspondent à votre marque et à votre guide de style UX.

6. Testez votre intégration

Rokt recommande de tester votre nouvelle intégration pour s'assurer que le SDK s'initialise correctement et que les événements sont enregistrés avec succès.

Ouvrez une nouvelle fenêtre de navigateur.
Ouvrez le panneau des outils de développement de votre navigateur. Pour la plupart des navigateurs, vous pouvez le faire en cliquant avec le bouton droit de la souris sur votre écran et en cliquant sur Inspecter.
Depuis le panneau des outils de développement, allez à l'onglet Réseau et tapez experiences dans la barre de filtre.
Naviguez vers le site et la page où vous avez intégré le SDK.
- Note : Assurez-vous d'ouvrir le panneau des outils de développement avant de naviguer vers votre site pour garantir que l'appel /experiences est enregistré par le navigateur.
Dans l'onglet Réseau du panneau des outils de développement, vous devriez voir au moins une requête /experiences. Cela indique que le Web SDK a été chargé avec succès.
Cliquez sur la requête /experiences (elle devrait avoir un statut de 200). Vérifiez l'onglet Payload/Request pour vérifier les données partagées avec Rokt.
- Note : Pendant les tests, vous pourriez voir un autre appel /experiences avec un statut 204. Assurez-vous de vérifier l'appel avec un statut 200.

Dépannage

Le SDK Web de Rokt fournit un rapport d'erreurs contextuel. Si vous avez des difficultés à valider votre intégration, la meilleure façon de déboguer le problème est d'utiliser l'onglet Console dans le panneau des outils de développement de votre navigateur.

Bien que vous puissiez rencontrer des erreurs non liées au SDK Rokt, certaines erreurs courantes du SDK Rokt à vérifier sont :

Erreurs de syntaxe

Assurez-vous de ne pas oublier de virgules dans votre code d'intégration.

Pour vérifier les erreurs de syntaxe :

Allez dans le panneau des outils de développement de votre navigateur et sélectionnez l'onglet Console.
Si le fichier où vous avez placé le SDK Web contient une erreur, elle devrait être consignée dans la console. Cliquez sur le fichier pour voir le code et l'erreur signalée.
Toute erreur est indiquée dans le fichier. En particulier, vérifiez que tous les attributs sont séparés par des virgules comme indiqué ci-dessous.

Incorrect :

email: ''
emailsha256: '',

Correct :

email: '',
emailsha256: '',

Erreurs d'initialisation

Assurez-vous que le script d'initialisation du SDK a été placé sur la page correcte.
Si vous avez intégré en utilisant un gestionnaire de balises (tag manager), assurez-vous d'avoir configuré vos déclencheurs de balises pour que l'initialisation se charge sur les bonnes pages, et que vos balises selectPlacements et de journalisation des conversions se déclenchent après l'initialisation du SDK.

Annexe

Après avoir implémenté les placements et le suivi des vues de page en suivant les instructions ci-dessus, vous pouvez souhaiter implémenter un suivi d'événements supplémentaire.

Suivre des événements personnalisés

Vous pouvez définir et suivre des événements personnalisés en appelant logEvent et en passant le nom de l'événement, le type d'événement, et un objet JSON contenant une liste de tous les attributs personnalisés pour l'événement.

Les types d'événements personnalisés pris en charge sont :

Navigation
Location
Search
Transaction
UserContent
UserPreference
Social
Other

Le type d'événement est optionnel ; si vous omettez le type d'événement, l'événement est simplement catégorisé comme unknown.

mParticle.logEvent(
    // Le nom de l'événement
    'event-name',
    // Le type d'événement
    mParticle.EventType.Other,
    // Inclure des attributs d'événement personnalisés pour décrire davantage l'événement
    {
        'custom-attribute-name': 'custom-attribute-value'
    }
);

Suivre les événements commerciaux

Le suivi d'un événement commercial nécessite trois étapes :

Définir le ou les produits qui sont achetés dans une variable en utilisant la méthode createProduct.
Créer un objet pour contenir un résumé de la transaction.
Appeler la méthode logProductAction, en incluant vos définitions de produits dans un tableau et le résumé de la transaction.

1. Définir le produit

Lors de la définition du produit, créez un nouveau produit en utilisant la méthode mParticle.eCommerce.createProduct, en passant les attributs suivants et un objet JSON optionnel contenant des attributs de produit personnalisés que vous pouvez définir sous forme de paires clé/valeur.

remarque

Les attributs de produit doivent être ajoutés dans l'ordre indiqué ci-dessous. Si vous n'avez pas de valeur pour l'un des attributs optionnels, vous devez définir la valeur sur null. Vous ne pouvez pas sauter ou omettre d'attributs à l'exception de l'objet JSON optionnel pour les attributs personnalisés.

Attribut du produit	Description	Type de données	Requis
Nom	Le nom du produit acheté.	String	Oui
SKU	L'unité de gestion des stocks pour le produit.	String	Oui
Prix	Le prix du produit.	Decimal	Oui
Quantité	Le nombre d'unités.	Integer	Non
Variante	La version spécifique du produit, si vous proposez des variantes. Par exemple : taille ou couleur.	String	Non
Catégorie	La catégorie à laquelle appartient le produit.	String	Non
Marque	Le nom de la marque pour le produit.	String	Non
Position	La position.	String	Non
Code promo	Le code promo pour le produit.	String	Non

var product1 = mParticle.eCommerce.createProduct(
    'Double Room - Econ Rate',  // Name (required)
    'econ-1',                   // SKU (obligatoire)
    100.00,                     // Prix (obligatoire)
    4,                          // Quantité
    'variant',                  // Variante
    'room',                     // Catégorie
    'lodge-o-rama',             // Marque
    'banner',                   // Position
    null,                       // Code promo
    // Ajoutez tous les attributs personnalisés optionnels dans un objet de paires clé/valeur
    {
        'ocean-view': true,
        'balcony': false
    }     
);

2. Résumer la transaction

Créez un résumé de la transaction dans un objet appelé transactionAttributes.

var transactionAttributes = {
    Id: 'foo-transaction-id',
    Revenue: 430.00,
    Tax: 30
};

3. Enregistrer l'événement commercial

Pour enregistrer l'événement commercial, appelez mParticle.eCommerce.logProductAction, et définissez ProductActionType sur l'un des types d'actions pris en charge listés ci-dessous.

Incluez vos définitions de produit dans un tableau. Si vous n'avez qu'une seule définition de produit, incluez-la quand même dans un tableau comme montré dans l'exemple.

Vous pouvez également définir des attributs d'événement personnalisés pour l'événement commercial dans customAttributes.

// Plusieurs types d'"actions de produit" sont pris en charge, tels que AddToCart et Checkout. Cet exemple utilise l'action de produit Purchase.
mParticle.eCommerce.logProductAction(
    // Le type d'action de produit enregistré. Dans cet exemple, le type est "Purchase"
    mParticle.ProductActionType.Purchase,
    // Le tableau contenant les définitions de produit que vous avez déjà créées à l'étape 1.
    [product1],
    // Attributs personnalisés décrivant l'événement commercial
    customAttributes = { 
        'sale': true
    },
    // Cet espace est destiné à spécifier des indicateurs personnalisés pour les intégrations mParticle par Rokt. Les clients Rokt Ecommerce peuvent ignorer cette section en entrant 'null'.
    null, 
    // L'objet transactionAttributes que vous avez déjà créé à l'étape 2.
    transactionAttributes
);

Lors de l'appel de la méthode logProductAction, vous devez spécifier le type d'action de produit.

Types d'actions de production prises en charge

AddToCart
RemoveFromCart
Checkout
CheckoutOption
Click
ViewDetail
Purchase
Refund
AddToWishlist
RemoveFromWishlist
Unknown

Passer des options supplémentaires de lancement d'intégration

Le SDK Rokt peut accepter des paramètres optionnels supplémentaires pour configurer le comportement de l'intégration.

Pour inclure une option de lancement optionnelle, incluez-la dans l'objet window.mParticle.config.launcherOptions dans le script d'initialisation :

// Incluez ceci comme partie du script d'initialisation à l'étape 1 ci-dessus
window.mParticle.config.launcherOptions = {
    noFunctional: true,
    // Voir toutes les options de lancement optionnelles qui peuvent être définies ci-dessous
};

Gérer les préférences de cookies des clients

Utilisez cette option pour respecter les préférences de désinscription des clients en désactivant les cookies fonctionnels, qui sont normalement utilisés pour la personnalisation et les expériences de paiement améliorées.

Paramètre	Type	Par défaut
`noFunctional`	boolean	`false`

Un indicateur booléen permettant la gestion de la préférence de l'utilisateur pour les cookies fonctionnels. Les cookies fonctionnels vous permettent de fournir les expériences client les plus pertinentes et optimales sur votre propre site, avec une personnalisation améliorée. Ils aident également à alimenter des fonctionnalités avancées au sein du paiement (par exemple, vendre des Upsells). En pratique, définir la valeur sur true empêche Rokt d'utiliser des identifiants de suivi de première partie.

Pour une discussion plus détaillée, voir Indicateurs de consentement aux cookies.

Mesurer la performance de chargement des pages dans les applications monopage (SPA)

Fournissez le timestamp du chargement d'une page virtuelle afin que Rokt puisse mesurer avec précision la performance dans les SPAs et détecter les anomalies pouvant affecter l'expérience client.

Paramètre	Type	Par défaut
`pageInitTimestamp`	Date	`PerformanceNavigationTiming.responseStart`

Dans le cas où le lanceur d'intégration (Integration Launcher) est initialisé sur une page virtuelle d'une SPA, cette valeur vous permet de fournir le timestamp de l'initialisation de la page. Cela permet à Rokt de mesurer correctement la performance de chargement par rapport à la page qui l'a déclenchée, sans facteurs externes tels que le temps pris par l'utilisateur pour atteindre cette page. Avec ces informations, Rokt peut détecter toute anomalie dans les temps de chargement pouvant affecter l'efficacité de l'intégration.

Lier l'activité client avec un ID de session Rokt

Transmettez un ID de session Rokt précédemment généré pour garantir que l'activité à travers différentes parties de l'expérience soit correctement liée.

Paramètre	Type	Par défaut
`sessionId`	string	—

ID de session Rokt à transmettre dans le cas où vous avez déjà généré votre ID de session.

Par exemple, il est possible que votre ID de session soit généré en se connectant avec le backend de Rokt avant de visiter une page où votre balise est affichée. Dans ce cas, vous devez fournir l'ID de session Rokt précédemment généré en tant que ce paramètre afin que Rokt puisse associer les deux interactions ensemble.

Activez cette option lorsque vous souhaitez avoir un contrôle total sur la façon dont les liens Rokt et des annonceurs s'ouvrent (par exemple, à l'intérieur d'un WebView au lieu d'un navigateur).

Paramètre	Type	Par défaut
`overrideLinkNavigation`	boolean	`false`

Lorsque cette option est définie sur true, Rokt ne gérera plus directement l'ouverture des liens. À la place, un événement partenaire LINK_NAVIGATION_REQUEST sera émis.

Ce drapeau est utile dans les scénarios où les partenaires nécessitent une gestion personnalisée des liens. Un cas d'utilisation courant est la gestion de différents comportements de lien—comme l'ouverture des liens dans un WebView tout en utilisant un navigateur externe pour les liens de Rokt et des annonceurs. Pour distinguer entre les liens Rokt et ceux des annonceurs, les partenaires peuvent vérifier si l'URL contient la sous-chaîne "rokt.com".

Pour garantir une gestion correcte des événements, un mécanisme de temporisation est en place. Si un événement LINK_NAVIGATION_REQUEST n'est pas consommé dans les 3 secondes, une erreur sera levée. Cette précaution garantit que des abonnements actifs existent du côté du partenaire pour traiter l'événement et, si ce n'est pas le cas, Rokt en sera informé.

Configuration de domaine de première partie​

1. Initialiser le SDK Rokt​

Script d'initialisation du SDK​

1.1 Entrez votre clé API Rokt​

1.2 Entrez votre sous-domaine personnalisé (optionnel)​

1.3 Configurer votre environnement de données​

1.4 Identifier l'utilisateur​

1.5 Définir des attributs utilisateur supplémentaires​

2. Identifier l'utilisateur​

3. Définir les attributs utilisateur​

Attributs utilisateur recommandés​

4. Suivre les événements du tunnel de conversion​

Suivre les consultations de pages​

5. Afficher un Placement​

S'abonner à un emplacement​

Fonctionnalité supplémentaire via des extensions​

Fermer un emplacement​

6. Testez votre intégration​

Dépannage​

Erreurs de syntaxe​

Erreurs d'initialisation​

Annexe​

Suivre des événements personnalisés​

Suivre les événements commerciaux​

1. Définir le produit​

2. Résumer la transaction​

3. Enregistrer l'événement commercial​

Types d'actions de production prises en charge​

Passer des options supplémentaires de lancement d'intégration​

Gérer les préférences de cookies des clients​

Mesurer la performance de chargement des pages dans les applications monopage (SPA)​

Lier l'activité client avec un ID de session Rokt​

Personnaliser la façon dont les liens s'ouvrent dans votre expérience​

Configuration de domaine de première partie

1. Initialiser le SDK Rokt

Script d'initialisation du SDK

1.1 Entrez votre clé API Rokt

1.2 Entrez votre sous-domaine personnalisé (optionnel)

1.3 Configurer votre environnement de données

1.4 Identifier l'utilisateur

1.5 Définir des attributs utilisateur supplémentaires

2. Identifier l'utilisateur

3. Définir les attributs utilisateur

Attributs utilisateur recommandés

4. Suivre les événements du tunnel de conversion

Suivre les consultations de pages

5. Afficher un Placement

S'abonner à un emplacement

Fonctionnalité supplémentaire via des extensions

Fermer un emplacement

6. Testez votre intégration

Dépannage

Erreurs de syntaxe

Erreurs d'initialisation

Annexe

Suivre des événements personnalisés

Suivre les événements commerciaux

1. Définir le produit

2. Résumer la transaction

3. Enregistrer l'événement commercial

Types d'actions de production prises en charge

Passer des options supplémentaires de lancement d'intégration

Gérer les préférences de cookies des clients

Mesurer la performance de chargement des pages dans les applications monopage (SPA)

Lier l'activité client avec un ID de session Rokt

Personnaliser la façon dont les liens s'ouvrent dans votre expérience