Guide d'Intégration du SDK Web

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

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

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 gestionnaire de compte Rokt.

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 résoudre 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 dans 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 Intégration de Domaine de Première Partie.

1. Initialiser le SDK 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 garantit la latence la plus faible pour la livraison des offres et la précision la plus élevée pour l'identification des utilisateurs.

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 chargerait par défaut à partir du cache plutôt que d'être chargé à chaque chargement de page de votre site web.

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 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 nulle
       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é avec son adresse e-mail, définissez des attributs utilisateur supplémentaires.
    identityCallback: function(result) {
        if (result.getUser()) {
            result.getUser().setUserAttribute('attribute-key', 'attribute-value');
        }
    }
};

// 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.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 sur 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 référence 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 acheminer 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 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 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éfinir l'adresse e-mail brute de l'utilisateur dans 'email'
        email: 'j.smith@example.com',
        // Définir 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 grâce à 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éfinir 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 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 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 attribué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 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 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é d'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` 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 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 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 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 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 comme nom d'écran,
              // par exemple, "/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, 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 de l'utilisateur entre les pages ou les sites.
              "referring-page": document.referrer
           }
   );
});

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

Nom de la 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 de commerce électronique pourrait avoir des centaines de pages de détails de produit. Pour les enregistrer correctement, vous devriez utiliser un nom générique (par exemple "Page de détail du produit") puis enregistrer l'url et d'autres attributs de la page en tant qu'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 page de confirmation d'achat ou une page de "remerciement".

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

Remplacer les attributs d'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 d'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 devriez inclure autant d'attributs d'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 sur le site. Ceux-ci sont inclus lorsque vous enregistrez un événement de conversion.

// Définir les attributs de l'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 ex. 300.5
    "currency": "",                 // Devise de la transaction ex. 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 filtrage.
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 des outils de développement, vous devriez voir au moins une requête /experiences. Cela indique que le SDK Web 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 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 rencontrez des difficultés pour 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'
    }
);

En plus de suivre des événements personnalisés et des événements de conversion, voici quelques exemples d'événements commerciaux que vous pourriez vouloir suivre. Parlez avec votre gestionnaire de compte pour vous aider à identifier les meilleurs événements à suivre et comment les implémenter 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 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 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