Aller au contenu principal

Guide de Migration du SDK Web

Ce guide explique comment migrer des anciennes versions du SDK Web de Rokt (version 2.5926.0 ou antérieure) vers la dernière version. Il est pertinent pour les implémentations de Rokt Ecommerce et Rokt Ads, et vous guide à travers les changements majeurs—comme le script d'initialisation mis à jour—et comment coordonner avec votre équipe de compte Rokt pour compléter la migration en douceur.

Initialisation du SDK Web​

Le plus grand changement introduit dans le nouveau SDK est la manière dont il est initialisé au sein de votre site web. Avant la version actuelle, Rokt vous permettait d'initialiser, ou de charger, le SDK en appelant soit les scripts launcher.js ou snippet.js depuis les balises <head> de chaque page de votre site.

Ces deux options ont été remplacées par un script d'initialisation unique.

Supprimer le script launcher.js obsolète​

Recherchez dans le code de votre site et supprimez toutes les instances du script launcher.js.

Il devrait ressembler à :

<script type="module">
  window.RoktLauncherScriptPromise = new Promise((resolve, reject) => {
      const target = document.head || document.body;
      const script = document.createElement("script");
      script.type = "text/javascript";
      script.src = "https://apps.rokt.com/wsdk/integrations/launcher.js";
      script.fetchPriority = "high";
      script.crossOrigin = "anonymous";
      script.async = true;
      script.id = "rokt-launcher";

      script.addEventListener('load', () => resolve());
      script.addEventListener('error', (error) => reject(error));

      target.appendChild(script);
  });
</script>

Supprimer le lanceur automatique snippet.js obsolète​

Si vous avez utilisé le lanceur automatique, recherchez dans le code de votre site et supprimez toute instance du script.

Il devrait ressembler à :

(function (r, o, k, t, n, e, w, a, _) {
  r._ROKT_ = n;
  r[n] = r[n] || {
    id: t,
    h: w,
    lc: [],
    it: new Date(),
    onLoaded: function (c) {
      r[n].lc.push(c);
    },
  };
  a = o.createElement("script");
  a.type = "text/javascript";
  a.async = !0;
  a.src = k;
  if (e) {
    a.integrity = e;
    a.crossOrigin = "anonymous";
  }
  _ = o.getElementsByTagName("script")[0];
  _.parentNode.insertBefore(a, _);
})(
  window,
  document,
  "https://apps.rokt.com/wsdk/integrations/snippet.js",
  "roktAccountid",
  "rokt"
);

Insérer le nouveau snippet d'initialisation du SDK​

Après avoir supprimé toute instance des anciens snippets du SDK, insérez le nouveau snippet d'initialisation du SDK dans la balise <head> de chaque page de votre site. Si votre site est une application multi-pages qui utilise des modèles, assurez-vous de mettre à jour vos modèles afin que ce nouveau snippet soit exécuté le plus tôt possible à chaque chargement de page.

Nouveau snippet d'initialisation du SDK Web Rokt​

<script type="text/javascript">

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

// Si vous avez configuré un domaine de première partie, définissez-le comme la valeur de DOMAIN au lieu du domaine par défaut apps.rokt-api
const ROKT_DOMAIN = "https://apps.rokt-api.com";

// Configurez vos paramètres de configuration SDK
window.mParticle = {
    config: {
        // Spécifiez l'environnement de données avec isDevelopmentMode:
        // 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 avez l'adresse e-mail de l'utilisateur, incluez-la dans un objet appelé `userIdentities` à l'intérieur de `identifyRequest` comme indiqué ci-dessous.  
        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'
            },
        }
    },
};

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

Le nouveau snippet introduit plusieurs nouvelles options de configuration :

Clé API Rokt​

Auparavant, vous deviez entrer votre ID de compte Rokt dans votre snippet SDK. Cette exigence a été remplacée par la clé API Rokt.

remarque

Votre représentant de compte Rokt vous fournira votre clé API Rokt.

Domaine de premier niveau​

Le nouveau SDK Web vous permet de router les requêtes vers Rokt via votre propre sous-domaine. Cela est appelé une "intégration de domaine de premier niveau" et peut aider à empêcher le blocage du contenu.

Pour utiliser un sous-domaine personnalisé avec votre intégration, suivez les instructions dans Intégration de Domaine de Premier Niveau, puis remplacez la valeur de DOMAIN dans votre snippet d'initialisation par votre propre sous-domaine :

const DOMAIN = "votre-nouveau-sous-domaine-ici";

Mode développement​

Auparavant, vous pouviez définir sandbox: true dans votre snippet SDK pour tester votre intégration.

Désormais, le SDK Rokt inclut une option de configuration appelée isDevelopmentMode. En définissant cette option sur true, le SDK Rokt collectera et transférera les données en tant que données de "développement" (c'est-à-dire de test). Lorsque vous avez terminé de tester votre intégration, changez isDevelopmentMode à false.

Identification de l'utilisateur lors de l'initialisation​

Lors de l'initialisation, le SDK soumet une identifyRequest à Rokt en utilisant soit l'adresse e-mail brute de l'utilisateur, soit son adresse e-mail hachée (selon ce que vous pouvez fournir) pour identifier l'utilisateur actuel. Vous pouvez fournir soit l'adresse e-mail brute, soit l'adresse e-mail hachée dans identifyRequest à l'intérieur des paramètres de configuration de vos scripts d'initialisation avec :

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'
  },
}

Identifier l'utilisateur​

Si vous ne pouvez pas fournir l'adresse e-mail de l'utilisateur lors de l'initialisation du SDK, vous devez identifier l'utilisateur dès qu'il fournit son adresse e-mail en appelant la méthode identify après l'initialisation du SDK.

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

const identityRequest = { 
    userIdentities: { 
        email: 'j.smith@example.com' 
    }
}; 
mParticle.Identity.identify(identityRequest);

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

const identityRequest = { 
    userIdentities: { 
        other: 'sha256 hashed email goes here' 
    }
}; 
mParticle.Identity.identify(identityRequest);

Définir les attributs utilisateur​

Une fois que vous avez identifié l'utilisateur actuel, vous pouvez définir des attributs utilisateur descriptifs qui seront inclus avec tous les 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 après que le SDK a été initialisé et que vous avez identifié l'utilisateur :

// Pour récupérer l'utilisateur actuel, appelez getCurrentUser. Cela ne réussira que si vous avez identifié l'utilisateur lors de l'initialisation du SDK ou en appelant la méthode identify.
const currentUser = mParticle.Identity.getCurrentUser();

// Une fois que vous avez réussi à définir l'utilisateur actuel sur une constante appelée `currentUser`, vous pouvez définir des attributs utilisateur avec :
currentUser.setUserAttribute("user-attribute-name", "user-attribute-value");
// Remarque : tous les attributs utilisateur (y compris les attributs de liste et les tags) doivent avoir des noms distincts.

// Rokt recommande de définir autant que possible les attributs utilisateur suivants :
currentUser.setUserAttribute("firstname", "John"); 
currentUser.setUserAttribute("lastname", "Doe");
// Les numéros de téléphone peuvent être formatés soit comme '1234567890', soit comme '+1 (234) 567-8901'
currentUser.setUserAttribute("mobile", "3125551515");
currentUser.setUserAttribute("age", "33");
currentUser.setUserAttribute("gender", "M");
currentUser.setUserAttribute("city", "Brooklyn");
currentUser.setUserAttribute("state", "NY");
currentUser.setUserAttribute("zip", "123456");
currentUser.setUserAttribute("dob", "yyyymmdd");
currentUser.setUserAttribute("title", "Mr");
currentUser.setUserAttribute("language", "en");
currentUser.setUserAttribute("value", "52.25");
currentUser.setUserAttribute("predictedltv", "136.23"); 

// 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");

Insertion des emplacements​

Le script utilisé pour insérer un emplacement sur votre site a également été remplacé dans le nouveau SDK.

Méthode selectPlacements obsolète :

Auparavant, pour insérer un emplacement, vous deviez appeler selectPlacements après que le script de lancement du SDK Rokt ait été complété :

<script type="module">
  await window.RoktLauncherScriptPromise;

  const launcher = await window.Rokt.createLauncher({
      accountId: "rokt-account-id",
      sandbox: true,
  });

  await launcher.selectPlacements({
      attributes: {
          email: "",
          firstname: "",
          lastname: "",
          confirmationref: "",
          billingzipcode: "",
          amount: "",
          paymenttype: "",
          ccbin: "",
          mobile: "",
          country: "",
          language: "",
          currency: "",
          billingaddress1: "",
          billingaddress2: "",
          age: "",
          gender: "",
          cartItems: JSON.stringify(cartItems),
      },
  });
</script>

Cela a été remplacé par la méthode mParticle.Rokt.selectPlacements :

Nouvelle méthode selectPlacements :

Pour insérer un emplacement, appelez la nouvelle méthode mParticle.Rokt.selectPlacements après avoir initialisé le SDK. Comme dans la section précédente, vous pouvez fournir une liste d'attributs pour améliorer la pertinence du contenu affiché à votre client.

const selection = await window.mParticle.Rokt.selectPlacements({
    attributes: {
        "email": "j.smith@example.com", // Adresse e-mail 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": "",                   // Montant de la transaction en décimal, par ex. 300.5
        "paymenttype": "",              // Par ex. Carte cadeau | Chase, Visa
        "ccbin": "",                    // Bin de la carte de crédit, par ex. 372888
        "mobile": "",                   // Numéro de mobile / cellulaire du client
        "country": "",                  // Code pays ISO Alpha-2
        "language": "",                 // Code de langue ISO 639-1 à 2 lettres
        "currency": "",                 // Devise de la transaction, par ex. USD
        "billingaddress1": "",          // Adresse ligne 1 du client
        "billingaddress2": "",          // Adresse ligne 2 du client
        "age": "",                      // Âge du client
        "gender": "",                   // 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 des attributs supplémentaires pertinents pour la transaction ici
        // Voir le lien ci-dessous pour une liste complète des attributs
        shippingtype: "Priority Express"
    }
});

Implémenter le suivi des événements​

Le nouveau SDK de Rokt facilite la collecte des événements et des attributs utilisateur. Pour apprendre comment implémenter ces nouvelles méthodes de suivi sur votre site, consultez les nouveaux guides Démarrage pour le commerce électronique ou Démarrage pour les annonceurs.

Cet article vous a-t-il été utile ?
Last updated Oct 29, 2025