Guides de Migration SDK

Cette page explique comment mettre à jour les intégrations existantes de Rokt SDK et SDK+ à travers les transitions de version, les changements de package, et les remplacements d'API listés ci-dessous.

• mParticle Apple SDK 9.0 (iOS)
• React Native SDK+ 3.0
• React Native Legacy SDK 5.0
• Flutter SDK+ 2.0
• Flutter Legacy SDK 5.0
• Guide de Migration Web SDK

mParticle Apple SDK 9.0 (iOS)

Si vous mettez à niveau le mParticle Apple SDK (et le kit Rokt) de 8.x à 9.x dans votre application iOS, plusieurs changements majeurs s'appliquent.

Système de types : types MPRokt → RoktContracts

Le plus grand changement dans la version 9.0 est que tous les types wrapper MPRokt* ont été supprimés. Le SDK expose maintenant directement les types du package RoktContracts. En Swift, un seul import mParticle_Apple_SDK donne accès à tous les types RoktEvent — aucun import supplémentaire n'est nécessaire. En Objective-C, ajoutez @import RoktContracts; en plus de votre import mParticle.

Ancien (8.x)	Nouveau (9.0)
MPRoktEvent	RoktEvent
MPRoktConfig	RoktConfig (utilise le pattern Builder)
MPRoktEmbeddedView	RoktEmbeddedView
MPRoktEventCallback	Supprimé — utilisez la fermeture onEvent
MPColorModeLight / MPColorModeDark	RoktColorModeLight / RoktColorModeDark (ObjC) ou .light / .dark (Swift)
MPRoktEvent.MPRoktPlacementReady	RoktEvent.PlacementReady
MPRoktEvent.MPRoktPlacementClosed	RoktEvent.PlacementClosed
MPRoktEvent.MPRoktEmbeddedSizeChanged	RoktEvent.EmbeddedSizeChanged
MPRoktEvent.MPRoktCartItemInstantPurchase	RoktEvent.CartItemInstantPurchase
Propriété d'événement : placementId	identifier

Callbacks → onEvent

La classe MPRoktEventCallback et le paramètre callbacks: sur selectPlacements ont été supprimés. Utilisez la fermeture onEvent: à la place.

Avant (8.x) :

import mParticle_Apple_SDK

let callbacks = MPRoktEventCallback()
callbacks.onLoad = { /* placement loaded */ }
callbacks.onUnLoad = { /* placement unloaded */ }
callbacks.onShouldShowLoadingIndicator = { /* show spinner */ }
callbacks.onShouldHideLoadingIndicator = { /* hide spinner */ }
callbacks.onEmbeddedSizeChange = { (placement, size) in /* resize */ }

MParticle.sharedInstance().rokt.selectPlacements("RoktExperience",
    attributes: attributes, embeddedViews: embeddedViews,
    config: roktConfig, callbacks: callbacks)

Après (9.x) :

import mParticle_Apple_SDK

MParticle.sharedInstance().rokt.selectPlacements("RoktExperience",
    attributes: attributes, embeddedViews: embeddedViews,
    config: roktConfig) { event in
    switch event {
    case is RoktEvent.ShowLoadingIndicator:
        // Show spinner
    case is RoktEvent.HideLoadingIndicator:
        // Hide spinner
    case is RoktEvent.PlacementReady:
        // Placement loaded
    case is RoktEvent.PlacementClosed:
        // Placement unloaded
    case let sizeEvent as RoktEvent.EmbeddedSizeChanged:
        // Resize: use sizeEvent.identifier and sizeEvent.updatedHeight
    default:
        break
    }
}

Modèle de construction RoktConfig

MPRoktConfig avec des propriétés mutables est remplacé par RoktConfig.Builder:

Avant : let config = MPRoktConfig(); config.colorMode = .light

Après : let config = RoktConfig.Builder().colorMode(.light).build()

Événements globaux

Une nouvelle méthode globalEvents: est disponible pour s'abonner aux événements de tous les emplacements, y compris InitComplete:

MParticle.sharedInstance().rokt.globalEvents { event in
    if let initEvent = event as? RoktEvent.InitComplete {
        print("SDK initialized: \(initEvent.success)")
    }
}

Autres changements majeurs

• Proxy AppDelegate : Le SDK n'intercepte plus automatiquement les messages UIApplicationDelegate. Vous devez maintenant explicitement transmettre les événements de notification push et d'activité URL/utilisateur au SDK.
• URL et activité utilisateur : Préférez le cycle de vie UIScene et les méthodes handleURLContext: et handleUserActivity: du SDK.
• Routage direct : Les requêtes API utilisent désormais par défaut des points de terminaison régionaux basés sur le préfixe de votre clé API ; assurez-vous que la sécurité de transport des applications autorise *.mparticle.com.
• Migration de base de données : La mise à niveau des versions SDK antérieures à 8.27.0 vers 9.x commence avec une nouvelle base de données locale ; les événements en attente ne sont pas migrés.

Publicités Shoppable : PaymentKit → PaymentExtension

Si vous utilisiez précédemment Rokt_Payment_Kit pour Apple Pay :

Ancien	Nouveau
Package : Rokt_Payment_Kit	Package : RoktPaymentExtension
RoktPaymentKit(applePayMerchantId:)	RoktPaymentExtension(applePayMerchantId:urlScheme:)
Rokt.registerPaymentKit(kit)	Rokt.registerPaymentExtension(ext, config:)
Rokt.execute(...) pour les emplacements shoppable	Rokt.selectShoppableAds(...)
Clé Stripe uniquement dans le kit	SDK Direct : stripeKey dans le dict config. SDK+ : stripePublishableKey dans les paramètres du kit mParticle Rokt

Consultez le guide Intégration iOS des publicités Shoppable pour l'API mise à jour.

RoktStripePaymentExtension → RoktPaymentExtension

Si vous avez intégré contre le package intermédiaire RoktStripePaymentExtension, mettez à jour comme suit :

Ancien	Nouveau
URL du package : https://github.com/ROKT/rokt-stripe-payment-extension-ios	https://github.com/ROKT/rokt-payment-extension-ios (ancienne URL redirige)
Pod : RoktStripePaymentExtension	RoktPaymentExtension '~> 2.0'
import RoktStripePaymentExtension	import RoktPaymentExtension
RoktStripePaymentExtension(...)	RoktPaymentExtension(...)

Changements majeurs RoktPaymentExtension 2.0

• returnURL supprimé — passez un urlScheme nu à la place (par exemple "myapp"). L'extension construit l'URL de retour complète Afterpay / Clearpay en interne. Enregistrez le même schéma sous CFBundleURLTypes dans Info.plist.
• handleURLCallback requis — transmettez les URL de redirection de votre SceneDelegate / AppDelegate à MParticle.sharedInstance().rokt.handleURLCallback(with:) (SDK+) ou Rokt.handleURLCallback(with:) (SDK Direct). Requis pour Afterpay / Clearpay et PayPal intégré sur iOS.

Versions minimales pour les publicités Shoppable (iOS)

Fonctionnalité	SDK+ (RoktSDKPlus)	Direct (Rokt-Widget)
Publicités Shoppable (base)	9.0+	5.0+
Afterpay / Clearpay	9.1+	5.1+
PayPal, transfert de carte (intégré)	9.2+	5.2+

Nécessite également RoktPaymentExtension '~> 2.0' et RoktContracts '~> 2.0' lorsqu'ils sont épinglés directement dans votre Podfile.

Pour les mises à jour de dépendances Rokt mParticle 9.0.x → 9.1.0 (Afterpay, handleURLCallback, renommage de package), voir Migration de 9.0.x à 9.1.0.

Pour le guide de migration officiel complet, voir Migration des versions < 9.0.0.

---

React Native SDK+ 3.0 (react-native-mparticle)

Si vous mettez à jour react-native-mparticle de 2.x à 3.0 dans votre application React Native, les changements suivants s'appliquent.

Nouveau : Support des publicités Shoppable

La version 3.0 introduit MParticle.Rokt.selectShoppableAds() pour afficher les emplacements des publicités Shoppable. Consultez le guide Intégration des publicités Shoppable React Native pour les instructions complètes de configuration.

remarque

Les publicités Shoppable dans React Native sont actuellement prises en charge uniquement sur iOS.

Dépendance Podfile iOS

Si vous utilisez les publicités Shoppable, ajoutez Rokt SDK+ à votre ios/Podfile (inclut RoktPaymentExtension) :

pod 'RoktSDKPlus', '~> 9.2'

Enregistrement de l'extension de paiement

Un nouvel appel registerPaymentExtension est requis dans votre code iOS natif (AppDelegate) avant d'appeler selectShoppableAds. Configurez stripePublishableKey dans vos paramètres mParticle Rokt kit — le kit le transmet automatiquement à Rokt. Dans le code, fournissez uniquement l'ID marchand Apple Pay :

import mParticle_Apple_SDK
import RoktPaymentExtension

if let paymentExt = RoktPaymentExtension(applePayMerchantId: "merchant.com.yourapp.rokt") {
    MParticle.sharedInstance().rokt.registerPaymentExtension(paymentExt)
}

Nouveaux événements pour les publicités Shoppable

Les événements suivants sont désormais disponibles via le canal NativeEventEmitter RoktEvents :

Événement	Description
CartItemInstantPurchaseInitiated	Flux d'achat démarré — l'utilisateur a appuyé sur "Acheter"
CartItemInstantPurchase	Achat complété avec succès
CartItemInstantPurchaseFailure	Achat échoué
CartItemDevicePay	Paiement Apple Pay / appareil déclenché
InstantPurchaseDismissal	L'utilisateur a rejeté la superposition d'achat

Aucun changement majeur aux API existantes

MParticle.Rokt.selectPlacements() et toutes les autres API existantes continuent de fonctionner comme auparavant.

---

React Native Legacy SDK 5.0 (@rokt/react-native-sdk)

Si vous effectuez une mise à niveau @rokt/react-native-sdk de 4.x à 5.0, les changements majeurs suivants s'appliquent.

Changement majeur : execute() renommé en selectPlacements()

Ancien (4.x)	Nouveau (5.0)
Rokt.execute(viewName, attributes, placeholders)	Rokt.selectPlacements(identifier, attributes, placeholders)
paramètre viewName	paramètre identifier

Nouveau : selectShoppableAds()

La version 5.0 introduit Rokt.selectShoppableAds() pour afficher les placements de publicités achetables.

remarque

Les publicités achetables dans React Native sont actuellement prises en charge uniquement sur iOS.

Dépendance Podfile iOS

Si vous utilisez des publicités achetables, ajoutez l'extension de paiement à votre ios/Podfile. Associez-la avec Rokt-Widget '~> 5.2' (transitif via @rokt/react-native-sdk) :

pod 'RoktPaymentExtension', '~> 2.0'

Enregistrement de l'extension de paiement

Un nouvel appel registerPaymentExtension est requis dans votre code natif iOS avant d'appeler selectShoppableAds. Pour le chemin direct du SDK, vous devez fournir explicitement votre clé publiable Stripe :

import Rokt_Widget
import RoktPaymentExtension

if let paymentExtension = RoktPaymentExtension(applePayMerchantId: "merchant.com.rokt.sample") {
    Rokt.registerPaymentExtension(paymentExtension, config: ["stripeKey": "pk_test_placeholder"])
}

Nouveaux événements de publicités achetables

Les événements suivants sont désormais disponibles via le canal NativeEventEmitter RoktEvents :

Événement	Description
CartItemInstantPurchaseInitiated	Flux d'achat démarré — l'utilisateur a appuyé sur "Acheter"
CartItemInstantPurchase	Achat complété avec succès
CartItemInstantPurchaseFailure	Achat échoué
CartItemDevicePay	Apple Pay / paiement par appareil déclenché
InstantPurchaseDismissal	L'utilisateur a fermé la superposition d'achat

---

Flutter Legacy SDK 5.0 (rokt_sdk)

Si vous effectuez une mise à niveau rokt_sdk de 4.x à 5.0, les changements majeurs suivants s'appliquent.

Changement majeur : execute() renommé en selectPlacements()

Ancien (4.x)	Nouveau (5.0)
RoktSdk.execute(viewName, attributes, onLoad, ...)	RoktSdk.selectPlacements(viewName: viewName, attributes: attributes)

Supprimé : callbacks et setLoggingEnabled()

Les paramètres de callback suivants sur execute ont été supprimés :

• onLoad
• onUnLoad
• onShouldShowLoadingIndicator
• onShouldHideLoadingIndicator

RoktSdk.setLoggingEnabled() a également été supprimé.

Tous les événements de cycle de vie sont désormais transmis via le EventChannel RoktEvents :

const EventChannel roktEventChannel = EventChannel('RoktEvents');

roktEventChannel.receiveBroadcastStream().listen((dynamic event) {
  switch (event["event"]) {
    case "InitComplete":
      // SDK initialized
      break;
    case "PlacementReady":
      // Replaces onLoad
      break;
    case "PlacementClosed":
      // Replaces onUnLoad
      break;
    case "ShowLoadingIndicator":
      // Replaces onShouldShowLoadingIndicator
      break;
    case "HideLoadingIndicator":
      // Replaces onShouldHideLoadingIndicator
      break;
    default:
      break;
  }
});

Renommage de propriété d'événement : placementId → identifier

Tous les objets d'événement utilisent désormais identifier au lieu de placementId.

Nouveau : selectShoppableAds() (iOS uniquement)

La version 5.0 introduit RoktSdk.selectShoppableAds() pour afficher les emplacements des publicités Shoppable.

remarque

Les publicités Shoppable dans Flutter sont actuellement prises en charge uniquement sur iOS.

Dépendance Podfile iOS

Si vous utilisez les publicités Shoppable, ajoutez l'extension de paiement Stripe à votre ios/Podfile :

pod 'RoktPaymentExtension', '~> 2.0'

Enregistrement de l'extension de paiement

Un nouvel appel registerPaymentExtension est requis depuis Dart avant d'appeler selectShoppableAds. L'application hôte doit également définir une fabrique d'extension de paiement dans le code natif iOS (AppDelegate.swift) :

import RoktPaymentExtension
import rokt_sdk

SwiftRoktSdkPlugin.paymentExtensionFactory = { type, config in
    switch type {
    case "stripe":
        guard let merchantId = config["applePayMerchantId"] else { return nil }
        return RoktPaymentExtension(
            applePayMerchantId: merchantId,
            countryCode: config["countryCode"] ?? "US"
        )
    default:
        return nil
    }
}

RoktSdk.registerPaymentExtension(
  extensionType: 'stripe',
  config: {
    'stripeKey': 'YOUR_STRIPE_PUBLISHABLE_KEY',
    'applePayMerchantId': 'merchant.com.yourapp.rokt',
  },
);

Nouveaux événements de publicités Shoppable

Les événements suivants sont désormais disponibles via le RoktEvents EventChannel :

Événement	Description
CartItemInstantPurchaseInitiated	Flux d'achat démarré — l'utilisateur a appuyé sur "Acheter"
CartItemInstantPurchase	Achat terminé avec succès
CartItemInstantPurchaseFailure	Échec de l'achat
CartItemDevicePay	Paiement Apple Pay / appareil déclenché
InstantPurchaseDismissal	L'utilisateur a rejeté la superposition d'achat

Disponibilité de la plateforme

Fonctionnalité	iOS	Android
selectPlacements	5.0.0	5.0.0
selectShoppableAds	5.0.0	Pas encore pris en charge
registerPaymentExtension	5.0.0	Pas encore pris en charge
purchaseFinalized	5.0.0	5.0.0

---

Flutter SDK+ 2.0 (mparticle_flutter_sdk)

Si vous mettez à niveau mparticle_flutter_sdk de 1.x à 2.0 dans votre application Flutter, les changements suivants s'appliquent.

Cible de déploiement iOS élevée à 15.0

Le plugin nécessite désormais iOS 15.0+. Mettez à jour les éléments suivants dans votre application :

• ios/Podfile :

  platform :ios, '15.0'

• ios/Flutter/AppFrameworkInfo.plist — définissez MinimumOSVersion à 15.0.

• Dans Xcode, élevez la cible de déploiement iOS du projet Runner à 15.0.

Après la mise à jour, exécutez :

cd ios
pod deintegrate
pod install
cd ..

Dépendances CocoaPods mises à jour

Le plugin dépend désormais de mParticle Apple SDK 9. Le suffixe de sous-spécification n'est plus valide :

Avant (1.x)	Après (2.0.0)
mParticle-Apple-SDK/mParticle ~> 8.5	mParticle-Apple-SDK ~> 9.0

Si la Podfile de votre application épingle une sous-spécification (par exemple pod 'mParticle-Apple-SDK/mParticle', ...), mettez-la à jour selon la nouvelle forme ci-dessus.

Canal d'événements Rokt — nouveaux types d'événements

Les consommateurs du flux EventChannel('MPRoktEvents') recevront des valeurs supplémentaires event. Les valeurs de chaîne pour les types d'événements déjà existants ne changent pas, donc les auditeurs existants continuent de fonctionner.

Nouveaux types d'événements et leurs clés de charge utile :

event	Clés supplémentaires
CartItemInstantPurchaseInitiated	cartItemId, catalogItemId
CartItemInstantPurchaseFailure	cartItemId, catalogItemId, error
InstantPurchaseDismissal	—
CartItemDevicePay	cartItemId, catalogItemId, paymentProvider

Nouveau : selectShoppableAds (iOS uniquement)

await MparticleFlutterSdk.getInstance().then((mp) => mp?.rokt.selectShoppableAds(
      identifier: 'shoppable-ads-placement',
      attributes: {'email': 'user@example.com'},
    ));

• iOS : proxys vers MParticle.sharedInstance().rokt.selectShoppableAds(...).
• Android : la méthode est exposée pour la parité API mais est une opération nulle (enregistre un avertissement).
• Web : non implémenté — les appels lanceront MissingPluginException.

Les événements pour un emplacement de publicités achetables sont livrés sur le MPRoktEvents EventChannel existant.

Consultez le guide Intégration des publicités achetables SDK+ Flutter pour la configuration complète.

Extension de paiement — enregistrement natif uniquement

L'extension de paiement Rokt (RoktPaymentExtension) n'est pas proxy via Dart. Les intégrateurs doivent l'enregistrer directement depuis Swift natif dans l'application hôte (par exemple ios/Runner/AppDelegate.swift), après MParticle.sharedInstance().start(with:). Configurez stripePublishableKey dans vos paramètres mParticle Rokt kit — le kit le transmet automatiquement à Rokt :

import mParticle_Apple_SDK
import RoktPaymentExtension

if let paymentExt = RoktPaymentExtension(applePayMerchantId: "merchant.com.yourapp.rokt") {
    MParticle.sharedInstance().rokt.registerPaymentExtension(paymentExt)
}

---

Guide de migration du SDK Web

Ce guide explique comment migrer des anciennes versions du SDK Web Rokt (version 2.5926.0 ou antérieure) vers la dernière version. Il est pertinent pour les implémentations 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é sur 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 seul script d'initialisation.

Supprimer le script obsolète launcher.js

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 obsolète snippet.js

Si vous avez utilisé le fragment de code du 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 fragment d'initialisation du SDK

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

Pour les instructions d'initialisation et les options de configuration maintenues, voir Initialiser le SDK Rokt+.

Nouveau fragment d'initialisation du SDK Web Rokt

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

Le nouveau fragment introduit plusieurs nouvelles options de configuration :

Clé API Rokt

Auparavant, vous deviez entrer votre ID de compte Rokt dans votre fragment 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 ROKT_DOMAIN dans votre fragment d'initialisation par votre propre sous-domaine :

const ROKT_DOMAIN = "https://your-new-subdomain-goes-here";

Mode développement

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

Désormais, le SDK Rokt inclut une option de configuration appelée isDevelopmentMode. En définissant ceci sur true, le SDK Rokt collectera et transmettra les données en tant que données de "développement" (alias test). Lorsque vous avez terminé de tester votre intégration, changez isDevelopmentMode en false.

Identification de l'utilisateur lors de l'initialisation

Lors de l'initialisation, le SDK soumet un identifyRequest à Rokt en utilisant soit l'adresse e-mail brute de l'utilisateur, soit l'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: {
      // If you're using an un-hashed email address, set it in 'email'.
      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'
  },
}

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: { 
        email_sha256: '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 emplacements publicitaires ou événements enregistrés. Vous pouvez également définir des attributs utilisateur directement lors de l'insertion d'un emplacement.

Pour définir des attributs utilisateur, exécutez ce qui suit après l'initialisation du SDK et l'identification de l'utilisateur :

// To retrieve the current user, call getCurrentUser. This will only succeed if you have identified the user during SDK initialization or by calling the identify method.
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("user-attribute-name", "user-attribute-value");
// Note: all user attributes (including list attributes and tags) must have distinct names.

// Rokt recommends setting as many of the following user attributes as possible:
currentUser.setUserAttribute("firstname", "John"); 
currentUser.setUserAttribute("lastname", "Doe");
// Phone numbers can be formatted either as '1234567890', or '+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"); 

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

Insérer 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 le nouveau 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. Pour des exemples maintenus couvrant chaque position d'emplacement, voir Afficher un Emplacement.

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",

      // Pass cart items as a real array so the fields remain typed.
      cartItems: [
        {
          cartitemid: "SKU-001",
          productsku: "SKU-001",
          productname: "Trail Runner v3",
          itemprice: 129.95,
          quantity: 1
        }
      ]
    }
  });
});

Mettez à jour votre Politique de Sécurité de Contenu (CSP)

Si votre site utilise une Politique de Sécurité de Contenu, vous devez mettre à jour vos directives CSP pour autoriser les nouveaux domaines SDK. Le nouveau SDK charge des ressources depuis apps.rokt-api.com en plus de apps.rokt.com.

Mettez à jour votre CSP pour inclure les directives suivantes :

script-src https://apps.rokt.com https://apps.rokt-api.com https://apps.roktecommerce.com https://sourcemaps-wsdk.roktinternal.com;
frame-src https://apps.rokt.com https://apps.rokt-api.com https://apps.roktecommerce.com;

Pour plus de détails sur les exigences CSP de Rokt, voir Sécurité Web.

Implémenter le suivi des événements

Le nouveau SDK 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.