Last updated

Guide d'Intégration du SDK Web

Cette page explique comment implémenter le SDK Web pour Rokt Ads afin de compléter la boucle en reliant les conversions à vos campagnes. En reliant les conversions à votre engagement publicitaire, vous pouvez permettre une attribution plus précise, une optimisation en temps réel et une mesure de campagne.

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

remarque

Les instructions ci-dessous nécessiteront des ressources de développement pour être complétées. Si vous avez besoin d'une assistance supplémentaire, veuillez contacter votre responsable de compte Rokt.

remarque

Travaillez avec votre responsable de compte Rokt pour d'abord implémenter le SDK dans un environnement de développement. Cela vous permet de tester et de résoudre en profondeur les problèmes de votre intégration avant de la publier dans un environnement de production.

Configuration du 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 comment configurer un domaine de première partie pour votre intégration SDK, consultez First Party Domain Integration.

1. Initialiser le SDK de Rokt

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

Chaque site est différent, mais Rokt recommande d'inclure le script SDK sur chaque page. Cela assure la plus faible latence de livraison des offres et la plus grande précision d'identification des utilisateurs.

Applications Monopage (SPA) : Si votre site 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 Multipages (MPA) : Si votre site 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ée principale. 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.

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

Script d'initialisation 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 en production.
       isDevelopmentMode: true,
       // Identifiez l'utilisateur actuel :
       // Si vous n'avez pas l'adresse email de l'utilisateur, vous pouvez passer une valeur nulle
       // identifyRequest: {
       userIdentities: {
           // Si vous utilisez une adresse email non hachée, configurez-la dans 'email'.
           email: 'j.smith@example.com',
           // Si vous utilisez une adresse email hachée, configurez-la dans 'other' au lieu de 'email'.
           other: 'l'email hachée sha256 va ici'
       }
    },
    // Si l'utilisateur est identifié par son adresse email, définissez des attributs utilisateur supplémentaires.
    identityCallback: function(result) {
        if (result.getUser()) {
            result.getUser().setUserAttribute('clé-attribut', 'valeur-attribut');
        }
    }
};

// Chargez 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.6; 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"].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 un identifiant unique fourni 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 acheminer le SDK via votre propre domaine, suivez les instructions dans Configuration de Domaine de Premier Niveau, et définissez ROKT_DOMAIN sur le sous-domaine que vous avez créé.

Un sous-domaine personnalisé permet au SDK Rokt d'être acheminé 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és.

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 acheminées via apps.rokt-api.com.

1.3 Configurer votre environnement de données

Rokt maintient deux environnements de données : Développement pour étiqueter et stocker les données à des fins de test et Production pour collecter l'activité réelle des clients.

Si vous testez encore le SDK de Rokt, définissez isDevelopmentMode sur true.

Si vous avez terminé les tests et souhaitez commencer à collecter l'activité client en direct, définissez 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 voie les annonces les plus pertinentes en fonction de son comportement.

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

identifyRequest: {
    userIdentities: {
        // Indiquez l'adresse e-mail brute de l'utilisateur dans 'email'
        email: 'j.smith@example.com',
        // Indiquez 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 à l’aide de SHA256.

Incluez toujours identifyRequest dans le script d'initialisation, même si vous ne disposez pas de 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 null. Le SDK s'initialisera toujours, et vous pourrez identifier l'utilisateur plus tard en suivant les instructions de 2. Identifier l'Utilisateur.

1.5 Définir des attributs utilisateur supplémentaires

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

// The identityCallback determines if the identifyRequest was successful.
identityCallback: function(result) {
    if (result.getUser()) {
        // If the user was identified, set additional user attributes with setUserAttribute.
        result.getUser().setUserAttribute('attribute-key', 'attribute-value');
    }
}

Pour une liste des attributs que Rokt recommande de collecter pour vos utilisateurs, voir Recommended user attributes.

2. Identifier l'Utilisateur

Lors de l'initialisation, le SDK soumet une 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 que le SDK a été initialisé (par exemple, lorsqu'il se connecte ou effectue un achat), vous devez appeler la méthode identify pour transmettre leur e-mail à Rokt. Cela garantit que les données sont correctement attribuées à l'utilisateur actuel.

Pour identifier l'utilisateur, créez d'abord 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 affecté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, voir Recommended user attributes.

Enfin, après avoir créé votre identifyRequest et votre identityCallback, pour définir des 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 leur 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 les attributs utilisateur lorsque l'utilisateur est identifié pendant l'initialisation du SDK et lorsque l'utilisateur est identifié après avoir fourni son adresse e-mail.

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

Pour définir les 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 comme 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 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` soit comme `+1 (222) 345-6789`.
age	33	L'âge du client.
dob	19900717	Date de naissance. Formatée comme `aaaammjj`.
gender	M	Le sexe 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 prévisible de la durée de vie du client.

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

4. Suivre les Vues de Page

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

Pour enregistrer une vue 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 URL (avec une valeur de repli sur "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 des pages.

// Attendre que le SDK soit complètement 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 URL en tant que nom d'écran,
              // par ex., "/products/shoes" → "shoes". 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, les requêtes, 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 de l'utilisateur entre les pages ou sites.
              "referring-page": document.referrer
           }
   );
});

La méthode logPageView du SDK web prend deux arguments :

Nom de Page : une chaîne pour le nom de la page chargée
Attributs Personnalisés : un objet de paires clé/valeur contenant des informations sur la page

Le champ du nom de la page doit être défini sur un nom de page générique. Par exemple, un site e-commerce pourrait avoir des centaines de pages de détails de produit. Pour les enregistrer correctement, vous devriez utiliser un nom générique (par ex. "Page Détail Produit") et ensuite enregistrer l'url et d'autres attributs de la page comme attributs.

5. Suivre les Conversions

Pour suivre une conversion, exécutez l'extrait de code suivant sur la page la plus appropriée qui se charge après qu'un client ait converti, comme une confirmation d'achat ou une page de "remerciement".

Lorsque vous collez l'extrait de code sur votre site, assurez-vous de :

Remplacer les attributs utilisateur d'exemple dans les appels .setUserAttribute par les valeurs réelles pour votre utilisateur ou client. Rokt recommande de définir au moins les attributs utilisateur suivants :
- firstname
- lastname
- zipcode
- mobile
Remplacer les attributs d'événement de conversion d'exemple par les valeurs réelles de votre événement de conversion.

Lors de l'enregistrement d'un événement de conversion, vous devez inclure autant d'attributs utilisateur et d'attributs d'événement que possible pour améliorer la capacité de Rokt à optimiser vos campagnes.

remarque

Lorsque vous initialisez le SDK Rokt, il capture automatiquement le Rokt Click ID et le Temps passé sur le site. Ceux-ci sont inclus lorsque vous enregistrez un événement de conversion.

// Définir les attributs utilisateur avant d'enregistrer l'événement de conversion
currentUser.setUserAttribute("firstname", "John");
currentUser.setUserAttribute("lastname", "Doe");
currentUser.setUserAttribute("zipcode", "98103");
currentUser.setUserAttribute("mobile", "3125551515");

// Enregistrer l'événement de conversion
mParticle.logEvent( 
  "conversion", // Le nom de l'événement
  mParticle.EventType.Transaction, // Le type d'événement
  { 
    "conversiontype": "signup",      // Type de conversion
    "confirmationref": "54321",     // ID de transaction / ID de commande
    "amount": "",                   // Montant de la transaction par exemple 300.5
    "currency": "",                 // Devise de la transaction par exemple USD
 
    // Vous pouvez suivre vos propres attributs d'événement personnalisés !
    "CUSTOM_EVENT_ATTRIBUTE_NAME" : "CUSTOM_EVENT_ATTRIBUTE_VALUE"
  }
);

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.
- Remarque: 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 d'outils de développement, vous devriez voir au moins une requête /experiences. Cela indique que le Web SDK s'est chargé avec succès.
Cliquez sur la requête /experiences (elle devrait avoir un statut de 200). Vérifiez l'onglet Charge utile/Requête pour vérifier les données partagées avec Rokt.
- Remarque: Pendant le test, vous pourriez voir un autre appel /experiences avec un statut de 204. Assurez-vous de réaliser la vérification sur l'appel avec un statut de 200.

Dépannage

Le SDK Web de Rokt fournit un rapport d'erreurs contextuel. Si vous rencontrez des difficultés pour valider votre intégration, la meilleure façon de résoudre 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 manquer 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 bonne page.
Si vous avez intégré en utilisant un gestionnaire de balises, assurez-vous que vous avez 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 que le SDK a été initialisé.

Annexe

Après avoir mis en place les placements et le suivi des vues de pages en suivant les instructions ci-dessus, vous pouvez souhaiter mettre en œuvre un suivi d'événements supplémentaires.

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 classé comme unknown.

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

En plus de suivre les événements personnalisés et les événements de conversion, voici quelques exemples d'événements commerciaux que vous pourriez vouloir suivre. Parlez à votre responsable de compte pour obtenir de l'aide pour identifier les meilleurs événements à suivre et comment les mettre en œuvre sur votre site :

purchase - lorsqu'un utilisateur effectue un achat ou une transaction.
sign_up - lorsqu'un utilisateur s'inscrit ou s'enregistre pour un événement ou un service.
first_time_deposit - lorsqu'un utilisateur effectue un dépôt.
subscription_started - lorsqu'un utilisateur commence un abonnement.
app_install - lorsqu'un utilisateur installe une application.
add_payment_info- lorsqu'un utilisateur ajoute des détails de paiement.
add_to_cart - lorsqu'un utilisateur ajoute un article à son panier.
add_to_wishlist - lorsqu'un utilisateur ajoute un article à sa liste de souhaits. .

Configuration du Domaine de Première Partie​

1. Initialiser le SDK de Rokt​

Script d'initialisation 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 Vues de Page​

5. Suivre les Conversions​

6. Testez votre intégration​

Dépannage​

Erreurs de syntaxe​

Erreurs d'initialisation​

Annexe​

Suivre des Événements Personnalisés​

Configuration du Domaine de Première Partie

1. Initialiser le SDK de Rokt

Script d'initialisation 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 Vues de Page

5. Suivre les Conversions

6. Testez votre intégration

Dépannage

Erreurs de syntaxe

Erreurs d'initialisation

Annexe

Suivre des Événements Personnalisés