Guide d'Intégration du SDK Web+

Platform

WebiOSAndroidFlutterReact NativeMAUICordova

For Rokt Ecommerce partners. This complete guide is for ecommerce businesses integrating Rokt into transaction experiences they own. It is not an advertiser implementation guide. Advertisers should use the Rokt Ads integration guides.

Cette page explique comment implémenter le SDK+ Rokt Ecommerce Web. Le SDK+ transmet les données utilisateur et transactionnelles à Rokt sur les pages configurées afin que Rokt puisse afficher des expériences pertinentes, telles que des offres sur les pages de confirmation.

1. Initialize the Rokt SDK+#

Incluez le script d'initialisation du SDK+ sur chaque page de votre site. Le cache du navigateur signifie que le SDK+ se charge à partir du cache sur les pages suivantes plutôt que de le recharger.

Pour les applications monopage : Insérez le script dans le head de votre index.html principal, ou partout où votre contenu est rendu.

Pour les applications multipages : Placez le script dans votre fichier de mise en page partagé principal. Si vous n'utilisez pas un système de rendu basé sur des modèles, ajoutez-le à chaque fichier HTML.

Configuration de domaine de première partie

L'utilisation d'un domaine de première partie lors de l'intégration du SDK+ Web dans votre site garantit que le SDK+ 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 savoir comment configurer un domaine de première partie pour votre intégration SDK+, consultez Intégration de domaine de première partie.

Rokt Web SDK+ initialization

<script type="text/javascript">

// Enter your Rokt API key
const API_KEY = "YOUR_API_KEY";

// Enter your custom subdomain if you are using a first-party domain configuration (optional)
const ROKT_DOMAIN = "https://apps.rokt-api.com";

window.mParticle = {
  config: {
      // Set the data environment:
      // Set isDevelopmentMode to true if you are still testing your integration. 
      // Set isDevelopmentMode to false if your integration is ready for production data.
      isDevelopmentMode: true,
      // Identify the current user:
      // If you do not have the user's email address, you can pass in a null value
      identifyRequest: {
          userIdentities: {
              // If you're using an un-hashed email address, set it in 'email' (preferred).
              email: 'j.smith@example.com',
              // If you're using a hashed email address, set it in 'email_sha256' instead of 'email'.
              email_sha256: 'sha256 hashed email goes here',
              // Customer phone number in E.164 format.
              mobile_number: '+13125551515',
              // If you're using a hashed mobile number, set it in 'mobile_sha256' instead of 'mobile_number'.
              mobile_sha256: 'sha256 hashed mobile goes here',
              // Partner's internal customer/account identifier (if the user is logged in).
              customerid: 'cust_10482'
          }
      },
      // If the user is identified with their email address, set additional user attributes.
      identityCallback: function(result) {
          if (result.getUser()) {
              result.getUser().setUserAttribute('attribute_key', 'attribute_value');
          }
      }
  }
};

// Load the 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.8; 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","hashSha256","setExtensionData","use","getVersion","terminate","onShoppableAdsReady"].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("&"); c.onerror = function() { var u = ["https://apps.","rokt","ecommerce",".com"].join(""); window.ROKT_DOMAIN = u; mParticle.config.domain = u.split("//")[1]; var d = document.createElement("script"); d.type = "text/javascript"; d.async = !0; d.src = u + "/js/v2/" + e + "/app.js" + n + "&" + s.join("&"); var f = document.getElementsByTagName("script")[0]; f.parentNode.insertBefore(d, f); }; 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, vous verrez des champs personnalisables pour :

1Entering your Rokt API key#

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

2Entering a custom first-party domain#

Suivez les instructions dans Configuration de domaine de première partie, et définissez ROKT_DOMAIN sur votre sous-domaine personnalisé. Acheminer le SDK+ Rokt via votre propre domaine réduit le risque que les bloqueurs de publicités et les navigateurs bloquent les publicités ou les données.

3Setting your data environment#

Définissez isDevelopmentMode sur true lors des tests pour acheminer les données vers l'environnement de développement, et false pour envoyer l'activité client en direct à la production.

4Identifying your user and setting attributes#

Dans identifyRequest, transmettez l'e-mail brut et non haché de l'utilisateur dans le champ email. Incluez mobile_number et customerid lorsque disponibles — plus de signaux améliorent la résolution d'identité. Une fois identifié, utilisez le identityCallback pour définir des attributs utilisateur supplémentaires. Pour une liste des attributs recommandés, consultez Attributs utilisateur.

identityCallback

// 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');
    }
}

remarque

Incluez toujours identifyRequest dans le script d'initialisation. Si vous n'avez pas l'e-mail de l'utilisateur à l'initialisation, définissez email sur null — le SDK+ s'initialisera quand même, et vous pourrez identifier l'utilisateur plus tard via Étape 2.

2. Identify the User#

Le script d'initialisation SDK+ identifie l'utilisateur actuel en utilisant les identifiants que vous avez fournis dans l'objet identifyRequest du script. Après l'initialisation du SDK, vous devez garder l'identité de l'utilisateur synchronisée chaque fois qu'il se connecte, se déconnecte ou fournit un identifiant (par exemple, lors du paiement) en utilisant la méthode appropriée décrite ci-dessous.

Identifiants utilisateur pris en charge

Afficher les identifiants utilisateur pris en charge

Champ	Type	Description
email	string	Adresse e-mail brute, non hachée.
email_sha256	string	E-mail haché en SHA-256. Utilisez à la place de email lorsque seule la forme hachée est disponible.
mobile_sha256	string	Numéro de mobile haché en SHA-256. Utilisez à la place de mobile_number lorsque seule la forme hachée est disponible.
mobile_number	string	Numéro de téléphone au format E.164 (par exemple, +13125551515).
customerid	string	Identifiant interne client/compte. Envoyez sur chaque page pour les utilisateurs connectés.

Pour identifier l'utilisateur :

1Create an identifyRequest object#

Créez un objet identifyRequest pour contenir les identifiants de l'utilisateur. Vous devez intégrer l'adresse e-mail brute, non hachée de l'utilisateur dans le champ email.

2Create an identityCallback#

Pour définir des attributs utilisateur supplémentaires, créez un identityCallback. Si le identifyRequest réussit, alors tous les attributs utilisateur que vous définissez dans le rappel sont attribués à l'utilisateur identifié.

3Send the request using the method that matches the user's action#

Passez le identifyRequest (et éventuellement identityCallback) à la méthode qui correspond à l'action de l'utilisateur :

• mParticle.Identity.login : appelez lorsque l'utilisateur se connecte ou crée un compte.
• mParticle.Identity.identify : appelez lorsque vous obtenez l'e-mail de l'utilisateur en cours de session sans transition de connexion (par exemple, un invité entre son e-mail lors du paiement).
• mParticle.Identity.logout : appelez lorsque l'utilisateur se déconnecte.

Appeler ces méthodes fait évoluer l'enregistrement SDK de l'état actuel de l'utilisateur. Les méthodes login et logout enregistrent également automatiquement un événement correspondant pour améliorer l'attribution de Rokt.

Par exemple, pour identifier un utilisateur nommé Jane Smith avec l'adresse e-mail j.smith@example.com, le numéro de mobile +13125551515, et l'ID client cust_10482 :

Example user identification

// 1. Create the identifyRequest object
const identifyRequest = {
  userIdentities: {
      email: 'j.smith@example.com',
      // If you are passing a hashed email address, set it inside the 'email_sha256' field instead of 'email'.
      email_sha256: 'SHA-256 hashed email address',
      mobile_number: '+13125551515',
      // If you are passing a hashed mobile number, set it inside the 'mobile_sha256' field instead of 'mobile_number'.
      mobile_sha256: 'SHA-256 hashed mobile number',
      customerid: 'cust_10482'
  }
};
// 2. User attributes are set using identityCallback
const identityCallback = function(result) {
  if (result.getUser()) {
      result.getUser().setUserAttribute('firstname', 'Jane');
      result.getUser().setUserAttribute('lastname', 'Smith');
  }
};
// 3. Call one of the following methods that best matches the user's action:
mParticle.Identity.login(identifyRequest, identityCallback); // Call when the user logs in or creates an account
mParticle.Identity.identify(identifyRequest, identityCallback); // Call when you obtain the user's email mid-session, but not during a login
mParticle.Identity.logout({}); // Call when the user logs out

3. Set User Attributes#

Définissez progressivement les attributs utilisateur tout au long du parcours client complet, pas seulement lors du paiement. Plus vous définissez d'attributs, mieux Rokt peut résoudre l'identité du client et fournir des offres pertinentes.

Définissez les attributs dès que possible

Définissez de nouveaux attributs utilisateur dès qu'ils sont disponibles. Une collecte d'attributs plus précoce donne à Rokt plus de signaux pour améliorer la rapidité et la pertinence des placements rendus sur la page de confirmation.

Set User Attributes

// To retrieve the current user, call getCurrentUser.
const currentUser = mParticle.Identity.getCurrentUser();

// Once you have successfully set the current user to a const called `currentUser`, you can set user attributes with:
currentUser.setUserAttribute("firstname", "Jane");
currentUser.setUserAttribute("lastname", "Smith");
currentUser.setUserAttribute("mobile_number", "+13125551515");
currentUser.setUserAttribute("birthyear", 1990);
currentUser.setUserAttribute("gender", "F");

// Address attributes (collect the billing address at checkout)
currentUser.setUserAttribute("billingaddress1", "123 Main St");
currentUser.setUserAttribute("billingaddress2", "Apt 4B");
currentUser.setUserAttribute("billingcity", "Brooklyn");
currentUser.setUserAttribute("billingstate", "NY");
currentUser.setUserAttribute("billingzipcode", "11201");
currentUser.setUserAttribute("country", "US");

// Lifecycle and loyalty attributes
currentUser.setUserAttribute("customertype", "logged_in");
currentUser.setUserAttribute("newcustomer", false);
currentUser.setUserAttribute("loyaltytier", "gold");
currentUser.setUserAttribute("loyaltyid", "LOY-7781");
currentUser.setUserAttribute("customersegment", "vip");

// Marketing attribution
currentUser.setUserAttribute("utmsource", "google");
currentUser.setUserAttribute("utmmedium", "cpc");
currentUser.setUserAttribute("utmcampaign", "spring_sale");

// To set a list attribute, set the value of the attribute to an array of strings. For example:
currentUser.setUserAttribute("favorite_genres", ["documentary", "comedy", "romance", "drama"]);

// To remove a user attribute, call removeUserAttribute and pass in the attribute name. All user attributes share the same key space.
currentUser.removeUserAttribute("attribute_to_remove");

Attributs utilisateur

Définissez autant d'attributs suivants que vous pouvez collecter.

Afficher tous les attributs utilisateur

Champ	Type	Description
firstname	string	Prénom du client. Utilisé pour la personnalisation.
lastname	string	Nom de famille du client. Utilisé pour la personnalisation.
mobile_number	string	Numéro de téléphone formaté comme 1112345678 ou +1 (222) 345-6789. Utilisé pour la résolution d'identité et la pertinence.
birthyear	integer	Année de naissance du client (par exemple 1990). Champ de date de naissance préféré. Alternatifs : dob (yyyymmdd), age. Utilisé pour l'éligibilité et la pertinence.
dob	string	Date de naissance, yyyymmdd. Alternative à birthyear. Utilisé pour l'éligibilité et la pertinence.
age	integer	Âge du client. Alternative à birthyear. Utilisé pour l'éligibilité et la pertinence.
gender	string	Genre du client. Par exemple, M, F, Male, ou Female. Utilisé pour la pertinence.
title	string	Titre honorifique. Par exemple, Mr, Mrs, Ms. Utilisé pour la personnalisation.
language	string	Code de langue ISO 639-1 associé à l'achat. Utilisé pour la pertinence.
billingaddress1	string	Adresse de rue (par exemple 123 Main St). Utilisé pour la résolution d'identité et la pertinence.
billingaddress2	string	Appartement/unité (par exemple Apt 4B). Utilisé pour la résolution d'identité.
billingcity	string	Ville de facturation. Utilisé pour la pertinence.
billingstate	string	État / province / région de facturation. Utilisé pour la pertinence et l'éligibilité.
billingzipcode	string	Code postal complet (préférence américaine pour ZIP+4). Utilisé pour la résolution d'identité et la pertinence.
country	string	Code de pays ISO 3166-1 alpha-2 (par exemple US, GB, AU). Utilisé pour l'éligibilité et la pertinence.
newcustomer	boolean	Indique si c'est un premier acheteur (true / false). Utilisé pour la pertinence.
customertype	string	Indique si l'utilisateur est authentifié (guest / logged_in). Utilisé pour la pertinence.
loyaltytier	string	Niveau du programme de fidélité partenaire. Utilisé pour la pertinence et l'éligibilité.
loyaltyid	string	ID de membre du programme de fidélité. Utilisé pour la résolution d'identité.
predictedltv	decimal	Valeur totale à vie prédite, généralement produite par un modèle d'apprentissage automatique partenaire. Utilisé pour la pertinence.
subscriptionstatus	string	État de l'abonnement si applicable (active, trial, churned, paused, none). Utilisé pour la pertinence et l'éligibilité.
customersegment	string	Segmentation interne du partenaire (par exemple, vip, at_risk, new, reactivated). Utilisé pour la pertinence.
acquisitionchannel	string	Comment le client a été initialement acquis. Utilisé pour la pertinence.
utmsource	string	Source d'attribution marketing. Utilisé pour la pertinence.
utmmedium	string	Moyen d'attribution marketing. Utilisé pour la pertinence.
utmcampaign	string	Campagne d'attribution marketing. Utilisé pour la pertinence.
utmcontent	string	Variante de contenu d'attribution marketing. Utilisé pour la pertinence.
utmterm	string	Terme / mot-clé d'attribution marketing. Utilisé pour la pertinence.
referrer	string	URL de référence — signal d'intention. Utilisé pour la pertinence.

remarque

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

4. Log Events#

Enregistrez les vues de page, les événements commerciaux et les événements personnalisés pour que Rokt puisse comprendre où se trouve chaque client dans son parcours.

Event category

Les vues de page indiquent à Rokt sur quelle page se trouve le client. Enveloppez chaque appel dans mParticle.ready() pour qu'il se déclenche après l'initialisation du SDK+. Sur les pages transactionnelles (PLP, PDP, panier, paiement, confirmation), déclenchez également l'événement commercial correspondant depuis Commerce events pour envoyer les détails au niveau du produit et de la commande.

Page type

Enregistrez ceci lorsque le client arrive sur la page d'accueil de votre site, y compris les racines de chemin vides comme /.

Field	Type	Description
screenname	string	Last segment of the URL path (e.g. /products/shoes → shoes). Defaults to home if the path is empty.
pagetype	string	Type of page being viewed: home, PLP, PDP, cart, checkout, confirmation.
url	string	Full URL of the current page.
title	string	Page title (from document.title).
sitesection	string	Top-level site section (e.g. mens, womens, support).
referringpage	string	Referring URL captured from document.referrer.

Example home page view

window.mParticle.ready(function() {
mParticle.logPageView("page_view", {
  screenname: "home",
  pagetype: "home",
  url: window.location.toString(),
  title: document.title,
  sitesection: "root",
  referringpage: document.referrer
});
});

5. Show a Placement#

Sur chaque page de paiement et de confirmation où vous souhaitez que Rokt affiche du contenu, appelez selectPlacements avec l'un des identifiants de page pris en charge et les attributs client + transaction. Rokt utilise ces signaux pour choisir et afficher l'offre la plus pertinente.

Les attributs passés dans selectPlacements remplacent toutes les valeurs antérieures définies via setUserAttribute. Fournissez toujours la valeur la plus récente.

Identifiants de page

• stg.rokt.conf: A confirmation page in a staging (or testing) environment.
• prod.rokt.conf: A confirmation page in a production environment.
• stg.rokt.payments: A payments page in a staging (or testing) environment.
• prod.rokt.payments: A payments page in a production environment.

Placement position

Passez le même ensemble d'attributs, quel que soit le positionnement. La référence complète des attributs est ci-dessous.

Afficher tous les attributs de placement

Field	Type	Description
email	string	Customer email address (unhashed). Used for identity resolution and Shoppable Ads order confirmation.
firstname	string	Customer first name. Used for personalization and Shoppable Ads order fulfillment.
lastname	string	Customer last name. Used for personalization and Shoppable Ads order fulfillment.
mobile_number	string	Customer mobile number (E.164 format, e.g. +13125551515). Used for identity resolution and Shoppable Ads.
confirmationref	string	Order / confirmation reference number. Used for relevance, deduplication, and Shoppable Ads order reconciliation.
currency	string	Transaction currency (ISO 4217, e.g. USD, GBP, AUD, JPY). Used for relevance and Shoppable Ads.
country	string	ISO 3166-1 alpha-2 country code. Used for eligibility and relevance.
language	string	Customer's preferred language (ISO 639-1, e.g. en, de, fr). Used for relevance.
totalprice	decimal	Total cart value including tax and shipping. Used for relevance.
amount	decimal	Cart subtotal before tax and shipping. Distinct from totalprice. Required for Pay+ on the payments page; also used by Shoppable Ads.
cartItems	array	Structured array of cart-line objects. See Cart items reference under Commerce Events. Used for relevance.
couponcode	string	Promo code applied, if any. Used for relevance.
newcustomer	boolean	Whether this is a first-time buyer. Used for relevance.
customertype	string	Whether the user is authenticated (guest / logged_in). Used for relevance.
value	decimal	Customer cumulative purchase value. Used for relevance.
subscriptionstatus	string	Subscription state if applicable (active, trial, churned, paused, none). Used for relevance and eligibility.
customersegment	string	Partner internal segmentation (vip, at_risk, new, reactivated). Used for relevance.
paymenttype	string	Payment method selected (credit_card, paypal, apple_pay, gift_card). Used for Pay+ eligibility and Shoppable Ads payment method prioritization.
paymentServiceProvider	string	Comma-separated list of payment methods accepted on the page (e.g. "cardpayment,paypal"). Accepted values: applepay, googlepay, paypal, venmo, affirm, afterpay, klarna, alipay, amazonpay, cardpayment, rakutenpay. Must be camelCase. Used for Pay+ eligibility.
ccbin	string	Credit card BIN (6-8 digits). Used for relevance.
billingaddress1	string	Billing street address. Used for identity resolution and relevance.
billingaddress2	string	Billing apartment/unit. Used for identity resolution.
billingcity	string	Billing city. Used for relevance.
billingstate	string	Billing state / region. Used for relevance.
billingzipcode	string	Billing ZIP / postcode. Used for identity resolution, relevance, and Shoppable Ads.
billingname	string	Full cardholder name on the billing address. Used for identity resolution and payment validation.
shippingmethod	string	Shipping method selected (standard, express, next_day). Used for relevance.
shippingname	string	Full recipient name on the shipping address. Used for Shoppable Ads order fulfillment.
shippingaddress1	string	Shipping street address. Used for relevance and Shoppable Ads order fulfillment.
shippingcity	string	Shipping city. Used for relevance and Shoppable Ads order fulfillment.
shippingstate	string	Shipping state / region. Used for relevance and Shoppable Ads order fulfillment.
shippingzipcode	string	Shipping ZIP / postcode. Used for relevance and Shoppable Ads order fulfillment.
shippingcountry	string	Shipping country (ISO 3166-1 alpha-2). Used for relevance and Shoppable Ads order fulfillment.
partnerpaymentreference	string	Non-guessable identifier used to look up the customer's vaulted payment method. Required for Shoppable Ads card forwarding; if absent, card forwarding is unavailable.
last4digits	string	Last 4 digits of the card used on the primary transaction. Displayed to the customer for confirmation during Shoppable Ads.
plcc	string	"yes" or "no" — whether the customer has a private-label credit card with the partner. Used for Pay+ relevance.
discountamount	decimal	Order-level discount applied (e.g. 10.00). Used for Pay+ relevance.
prescreen	string	"yes" or "no" — whether the customer has pre-qualified for a credit offer. Used for Pay+ relevance.

remarque

Ne pas envoyer les articles du panier sous forme de chaînes séparées par des virgules ou sous forme de blob JSON sérialisé. Envoyez un vrai tableau JSON pour que les champs restent typés. Pour la référence complète des champs d'article de panier, voir la section Articles de panier sous Événements de commerce.

Les placements en superposition s'affichent au-dessus de votre page de confirmation dans un conteneur géré par Rokt, ne nécessitant aucune modification du DOM de votre page. Utilisé pour les annonces de remerciement standard et les annonces achetables.

Pour insérer un placement en superposition, appelez selectPlacements une fois que la page de confirmation est chargée :

Example overlay selectPlacements call

window.mParticle.ready(async function () {
const selection = await window.mParticle.Rokt.selectPlacements({
  identifier: "prod.rokt.conf",
  attributes: {
    // Identity
    email: "j.smith@example.com",
    firstname: "Jenny",
    lastname: "Smith",
    mobile_number: "+13125551515",

    // Transaction
    confirmationref: "ORDER-10482",
    currency: "USD",
    country: "US",
    language: "en",
    totalprice: 149.99,
    couponcode: "SUMMER20",

    // Customer context
    newcustomer: false,
    customertype: "logged_in",
    value: 2340.00,
    subscriptionstatus: "active",
    customersegment: "vip",

    // Payment (include paymenttype + paymentServiceProvider for Pay+)
    paymenttype: "credit_card",
    paymentServiceProvider: "cardpayment",
    ccbin: "411112",

    // Cart contents — see the Placement Attributes reference for the full
    // attribute set and the Cart items reference for the per-line shape.
    cartItems: [
      { cartitemid: "SKU-001", productsku: "SKU-001", productname: "Trail Runner v3", itemprice: 129.95, quantity: 1 }
    ]
  }
});
});

6. Subscribe to Placement Events#

Le SDK+ émet des événements tout au long du cycle de vie de l'emplacement. Abonnez-vous à ces événements pour exécuter une logique personnalisée lorsqu'un emplacement est prêt, lorsqu'un client interagit avec un emplacement, ou lorsque l'enveloppe de placement interstitial passe d'un état à un autre.

Lifecycle event source

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

Subscribe to Placement Events

window.mParticle.ready(async function () {
const selection = await window.mParticle.Rokt.selectPlacements({
  // add attributes
});

// Listen for when the placement becomes interactive/ready to display
selection.on('PLACEMENT_INTERACTIVE').subscribe(() => {
  // Logic to run after Placement has become interactive
});

// Listen for when user engages positively or negatively with an offer
selection.on('OFFER_ENGAGEMENT').subscribe(function () {
  // Logic to run after offer is engaged with
});
});

7. Appendix#

Référence pour fermer les emplacements dans les applications monopage, activer les extensions pour les fonctionnalités avancées, et configurer le comportement optionnel du lanceur.

Fermer un emplacement

Dans les applications monopage, appelez .close() sur l'objet d'emplacement après que l'utilisateur ait navigué ailleurs pour que l'emplacement ne persiste pas lors de la navigation arrière.

Close a placement

// Closes the placement called 'selection'
selection.close();

Pay+

Si vous utilisez Pay+, vous devez fermer votre emplacement après que l'utilisateur ait navigué ailleurs.

Fonctionnalité supplémentaire via des extensions

Certaines fonctionnalités nécessitent des extensions. Activez-les en appelant mParticle.Rokt.use() avant selectPlacements(). Par exemple, pour afficher des emplacements de vente incitative sur une page de remerciement, activez d'abord l'extension ThankYouPageJourney :

Enable the ThankYouPageJourney extension

window.mParticle.ready(async function() {
// Enable the necessary extension prior to selecting placements
await window.mParticle.Rokt.use("ThankYouPageJourney");

const selection = await mParticle.Rokt.selectPlacements({
  identifier: "yourPageIdentifier",
  attributes: {
    "email": "j.smith@example.com"
    // Any additional user attributes you want to pass to Rokt
  },
});
})

Passage d'options supplémentaires pour le lanceur d'intégration

Configurez le comportement optionnel en définissant window.mParticle.config.launcherOptions dans le script d'initialisation :

launcherOptions config

// Include this as part of the initialization script in step 1 above
window.mParticle.config.launcherOptions = {
  noFunctional: true,
  noTargeting: true,
  // See all optional launcher options that can be set below
};

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

Utilisez ces options pour respecter les préférences de désactivation des clients en désactivant les cookies fonctionnels ou de ciblage.

Paramètre	Type	Défaut	Description
noFunctional	boolean	false	Définissez sur true pour empêcher Rokt d'utiliser des identifiants de suivi de première partie lorsque le client a désactivé les cookies fonctionnels. Les cookies fonctionnels alimentent la personnalisation de première partie et les fonctionnalités avancées de paiement comme les Upsells.
noTargeting	boolean	false	Définissez sur true pour empêcher Rokt d'utiliser des identifiants de suivi intersites pour la session lorsque le client a désactivé les cookies de ciblage. Les identifiants fonctionnels restent actifs à moins que noFunctional ne soit également défini sur true.

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

Mesurer la performance de chargement des pages dans les applications monopage

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

Paramètre	Type	Défaut
pageInitTimestamp	Date	PerformanceNavigationTiming.responseStart

Lorsque le lanceur s'initialise sur une page virtuelle dans une SPA, transmettez le timestamp de l'initialisation de cette page pour que Rokt puisse mesurer la performance de chargement par rapport à la page qui l'a déclenchée.

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

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

Paramètre	Type	Défaut
sessionId	string	—

Si vous avez généré un ID de session Rokt à partir d'une interaction backend antérieure, transmettez-le ici pour que Rokt puisse l'associer à l'activité front-end.

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

Activez cette option lorsque vous souhaitez 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	Défaut
overrideLinkNavigation	boolean	false

Lorsqu'il est défini sur true, Rokt cesse de gérer directement l'ouverture des liens et émet à la place un événement partenaire LINK_NAVIGATION_REQUEST. Pour distinguer les liens Rokt et des annonceurs des vôtres, vérifiez si l'URL contient "rokt.com".

Abonnez-vous à l'événement sur la sélection retournée par selectPlacements. Chaque événement transporte une seule chaîne url — le lien activé par le client. Ouvrez-le immédiatement, dans le contexte dont vous avez besoin (un onglet de navigateur, un WebView, etc.), pour éviter de dégrader l'expérience client.

Handle LINK_NAVIGATION_REQUEST

const selection = await window.mParticle.Rokt.selectPlacements({
  // identifier and attributes as in the examples above
});

selection.on("LINK_NAVIGATION_REQUEST").subscribe((event) => {
  // event.url is the link the customer activated — open it immediately
  window.open(event.url);
});

Si un événement LINK_NAVIGATION_REQUEST n'est pas consommé dans les 3 secondes, une erreur est levée — assurez-vous qu'un abonnement actif existe pour traiter l'événement.

8. Test Your Integration#

Pour confirmer que le SDK+ s'initialise, identifie l'utilisateur, enregistre les événements et demande les offres correctement :

1Open a new browser window#

Ouvrez une nouvelle fenêtre de navigateur pour commencer avec un état propre.

2Open developer tools#

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.

Activez l'option qui conserve les requêtes réseau à travers les chargements de page (Préserver le log dans Chrome, Edge et Safari, ou Conserver les logs dans Firefox).

3Filter network requests#

Depuis le panneau des outils de développement, allez à l'onglet Réseau et filtrez pour rokt-api.com. Si vous utilisez un domaine de premier niveau personnalisé, filtrez pour votre sous-domaine personnalisé à la place.

Pour trouver une requête spécifique, vous pouvez également filtrer par son nom de point de terminaison : /identity, /events, /experiences, ou /offers.

4Run the test journey#

Avec l'enregistrement de l'onglet Réseau, complétez un parcours de test à travers les pages où vous avez intégré le SDK+.

remarque

Ouvrez le panneau des outils de développement avant de naviguer sur votre site pour que le navigateur enregistre toutes les requêtes SDK+.

5Verify the identity request#

Filtrez pour /identity, puis sélectionnez la requête qui correspond à l'action d'identité que vous avez effectuée, comme identify ou login. Confirmez qu'elle a un statut réussi, puis vérifiez l'onglet Charge utile ou Requête pour les identifiants de test que vous vous attendiez à envoyer.

6Verify page-view and commerce events#

Filtrez pour /events, puis sélectionnez la requête générée pendant votre parcours de test. Confirmez qu'elle a un statut réussi. Vérifiez l'onglet Charge utile ou Requête pour vérifier que la requête contient l'événement de vue de page ou de commerce et les attributs que vous vous attendiez à envoyer.

Les requêtes d'événements peuvent contenir plusieurs événements, donc inspectez la charge utile complète de la requête lorsque vous vérifiez une action spécifique.

7Verify the selection request#

Filtrez pour /experiences, puis pour /offers. Selon le routage de votre SDK+, une sélection réussie utilise l'un de ces points de terminaison :

• /v1/experiences
• /v2/sessions/offers

Vous n'avez besoin de voir qu'une de ces requêtes. Sélectionnez la requête avec un statut 200, puis vérifiez l'onglet Charge utile ou Requête pour vérifier les données partagées avec Rokt.

remarque

Lors des tests, vous pourriez également voir une requête /v1/experiences avec un statut 204. Utilisez la requête avec un statut 200 lors de la vérification de la charge utile.

Dépannage

Si votre intégration ne fonctionne pas, vérifiez l'onglet Console dans les outils de développement de votre navigateur pour les erreurs du SDK+ de Rokt. Les problèmes courants incluent :

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 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+.

Erreurs de syntaxe

Assurez-vous de ne manquer aucune virgule dans votre code d'intégration.

Pour vérifier les erreurs de syntaxe :

1Open the Console tab#

Accédez au panneau des outils de développement de votre navigateur et sélectionnez l'onglet Console.

2Find the error#

Si le fichier où vous avez placé le Web SDK+ contient une erreur, elle devrait être enregistrée dans la console. Cliquez sur le fichier pour voir le code et l'erreur signalée.

3Verify commas#

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.

Missing comma (incorrect)

email: ''
mobile_number: '',

Correct

email: '',
mobile_number: '',