Guide d'Intégration du SDK Cordova

Platform

WebiOSAndroidFlutterReact NativeMAUICordova

Target

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 Cordova. Le SDK+ transmet les données utilisateur et transactionnelles à Rokt sur les écrans configurés afin que Rokt puisse afficher des expériences pertinentes, telles que des offres sur les écrans de confirmation.

Utilisez les sélecteurs Target et Language ci-dessus pour choisir votre plateforme de déploiement et les exemples de code natif que vous souhaitez suivre.

1. Add the Rokt SDK+ to Your Cordova App#

Installez le SDK+ et le plugin Rokt kit :

Install Cordova plugins

cordova plugin add @mparticle/cordova-sdk
cordova plugin add @mparticle/cordova-rokt-kit

2. Initialize the Rokt SDK+#

Insérez l'extrait d'initialisation suivant dans le point d'entrée natif pertinent pour chaque plateforme. Le SDK+ doit être initialisé avant tout autre appel d'API SDK+. Remplacez your-key et your-secret par la clé et le secret fournis par votre équipe Rokt.

Vous pouvez trouver un exemple complet dans l'application exemple.

Lors de l'insertion de l'extrait d'initialisation, vous verrez des champs personnalisables pour :

1Entering your Rokt key and secret#

Définissez your-key et your-secret aux valeurs fournies par votre gestionnaire de compte Rokt. (iOS utilise optionsWithKey:secret:. Android utilise .credentials(...).)

2Setting your data environment#

Réglez l'environnement du SDK+ sur développement pendant les tests pour acheminer les données vers l'environnement de Développement, et sur production pour envoyer l'activité client en direct à Production. (iOS : MPEnvironmentDevelopment / MPEnvironmentProduction. Android : MParticle.Environment.Development / MParticle.Environment.Production.)

3Identifying your user and setting attributes#

Dans identifyRequest, passez l'email brut et non haché de l'utilisateur. Pour les emails hachés et d'autres identifiants, voir Identifiants utilisateur pris en charge. Une fois identifié, définissez des attributs utilisateur supplémentaires via le callback de succès (iOS : onIdentifyComplete. Android : connectez la requête au constructeur d'options via .identify(identifyRequest) et utilisez un écouteur de succès — voir Étape 3 : Identifier l'utilisateur pour le modèle).

remarque

Incluez toujours identifyRequest dans l'extrait d'initialisation. Si vous n'avez pas l'email de l'utilisateur lors de l'initialisation, omettez l'affectation de l'email (iOS) ou l'appel .email(...) (Android) — le SDK+ s'initialisera toujours, et vous pourrez identifier l'utilisateur plus tard via 3. Identifier l'utilisateur. Consultez Gestion des erreurs pour savoir comment gérer les échecs d'identification — sans gestion des erreurs, vous pourriez rencontrer des problèmes de cohérence des données à grande échelle.

AppDelegate initialization (iOS)

#import "AppDelegate.h"
#import "MainViewController.h"
#import "mParticle.h"

@implementation AppDelegate

- (BOOL)application:(UIApplication*)application didFinishLaunchingWithOptions:(NSDictionary*)launchOptions
{
  MParticleOptions *mParticleOptions = [MParticleOptions optionsWithKey:@"your-key"
                                                                 secret:@"your-secret"];
  // Specify the data environment:
  // Set it to MPEnvironmentDevelopment if you are still testing your integration.
  // Set it to MPEnvironmentProduction if your integration is ready for production data.
  // The default is MPEnvironmentAutoDetect which attempts to detect the environment automatically.
  mParticleOptions.environment = MPEnvironmentDevelopment;

  // Identify the current user:
  // If you do not have the user's email address, you can pass in a null value
  MPIdentityApiRequest *request = [MPIdentityApiRequest requestWithEmptyUser];

  // Preferred: pass the customer's raw, unhashed email address in 'email'.
  // If you can only provide a SHA-256-hashed email, set it in 'other' instead of email — do not pass both.
  request.email = @"j.smith@example.com";
  // [request setIdentity:@"sha256 hashed email goes here" identityType:MPIdentityOther]; // only if raw email unavailable

  mParticleOptions.identifyRequest = request;
  mParticleOptions.onIdentifyComplete = ^(MPIdentityApiResult * _Nullable apiResult, NSError * _Nullable error) {
      if (apiResult) {
          // If the user is identified, set additional user attributes
          [apiResult.user setUserAttribute:@"example attribute key" value:@"example attribute value"];
      }
  };

  [[MParticle sharedInstance] startWithOptions:mParticleOptions];

  self.viewController = [[MainViewController alloc] init];
  return [super application:application didFinishLaunchingWithOptions:launchOptions];
}

@end

3. Identify the User#

Le script d'initialisation du 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 maintenir 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	Passez l'adresse e-mail brute et non hachée du client.
mobile	string	Passez le numéro de téléphone du client au format E.164.
customerid	string	Passez votre identifiant client/compte interne. Envoyez-le à chaque écran pour les utilisateurs connectés.
other	string	Passez un e-mail haché avec SHA-256. Utilisez uniquement lorsque l'e-mail brut ne peut pas être fourni — ne passez pas à la fois email et other. (Chemin Android uniquement.)
other2	string	Passez un numéro de mobile haché avec SHA-256. Utilisez uniquement lorsque le numéro de mobile brut ne peut pas être fourni — ne passez pas à la fois mobile et other2. (Chemin Android uniquement.)
emailSha256	string	Passez un e-mail haché avec SHA-256. Utilisez uniquement lorsque l'e-mail brut ne peut pas être fourni — ne passez pas à la fois email et emailSha256. (Chemin iOS uniquement.)
mobileSha256	string	Passez un numéro de mobile haché avec SHA-256. Utilisez uniquement lorsque le numéro de mobile brut ne peut pas être fourni — ne passez pas à la fois mobile et mobileSha256. (Chemin iOS uniquement.)

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

• identity.login : appelez lorsque l'utilisateur se connecte ou crée un compte.
• 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).
• 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 :

Identify Jane Smith

// 1. Create the identifyRequest object
var identifyRequest = new mparticle.IdentityRequest();
// Preferred: pass the customer's raw, unhashed email address.
// If you can only provide a SHA-256-hashed email, use setUserIdentity with 'other' instead — do not pass both.
identifyRequest.setEmail('j.smith@example.com');
identifyRequest.setUserIdentity(mparticle.UserIdentityType.Other, 'SHA-256 hashed email'); // only if raw email unavailable
// If you can only provide a SHA-256-hashed mobile number, use 'Other2' instead of 'MobileNumber' — do not pass both.
// (Called 'other2' on Android and 'mobileSha256' on iOS; both use this same field.)
identifyRequest.setUserIdentity(mparticle.UserIdentityType.Other2, 'SHA-256 hashed mobile number'); // only if raw mobile unavailable
identifyRequest.setUserIdentity(mparticle.UserIdentityType.MobileNumber, '+13125551515');
identifyRequest.setCustomerId('cust_10482');

// 2. Optionally set user attributes once the request succeeds.
var identityCallback = {
  onSuccess: function(userID) {
      var user = new mparticle.User(userID);
      user.setUserAttribute('firstname', 'Jane');
      user.setUserAttribute('lastname', 'Smith');
  },
  onError: function(errorResponse) {
      console.error('Identify error: ' + JSON.stringify(errorResponse));
  }
};

// 3. Call one of the following methods that best matches the user's action:
var identity = new mparticle.Identity();
identity.login(identifyRequest, identityCallback.onSuccess); // Call when the user logs in or creates an account
identity.identify(identifyRequest, identityCallback.onSuccess); // Call when you obtain the user's email mid-session, but not during a login
identity.logout({}); // Call when the user logs out

4. Set User Attributes#

Définissez les attributs utilisateur progressivement à mesure que l'utilisateur navigue dans votre application, pas seulement lors du paiement. Plus vous définissez d'attributs, mieux Rokt peut résoudre le client et fournir des offres pertinentes.

Set user attributes

var identity = new mparticle.Identity();

identity.getCurrentUser(function(userID) {
  var currentUser = new mparticle.User(userID);

  // Once you have successfully set the current user, you can set user attributes with:
  currentUser.setUserAttribute('custom-attribute-name', 'custom-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('billingcity', 'Brooklyn');
  currentUser.setUserAttribute('billingstate', 'NY');
  currentUser.setUserAttribute('billingzipcode', '123456');
  currentUser.setUserAttribute('dob', 'yyyymmdd');
  currentUser.setUserAttribute('title', 'Mr');
  currentUser.setUserAttribute('language', 'en');
  currentUser.setUserAttribute('predictedltv', '136.23');

  // You can create a user attribute to contain a list of values
  currentUser.setUserAttributeArray('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 que possible des éléments suivants que vous pouvez collecter :

Afficher tous les attributs utilisateur

Champ	Type	Description
firstname	chaîne	Prénom du client. Utilisé pour la personnalisation.
lastname	chaîne	Nom de famille du client. Utilisé pour la personnalisation.
mobile	chaîne	Numéro de téléphone formaté comme 1112345678 ou +1 (222) 345-6789. Utilisé pour la résolution d'identité et la pertinence.
age	entier	Âge du client. Alternative à dob. Utilisé pour l'éligibilité et la pertinence.
dob	chaîne	Date de naissance, yyyymmdd. Alternative à age. Utilisé pour l'éligibilité et la pertinence.
gender	chaîne	Genre du client. Par exemple, M, F, Male, ou Female. Utilisé pour la pertinence.
title	chaîne	Titre de civilité. Par exemple, Mr, Mrs, Ms. Utilisé pour la personnalisation.
language	chaîne	Code de langue ISO 639-1 associé à l'achat. Utilisé pour la pertinence.
billingcity	chaîne	Ville de facturation. Utilisé pour la pertinence.
billingstate	chaîne	État / province / région de facturation. Utilisé pour la pertinence et l'éligibilité.
billingzipcode	chaîne	Code postal complet (préférence US est ZIP+4). Utilisé pour la résolution d'identité et la pertinence.
billingaddress1	chaîne	Adresse de facturation ligne 1. Utilisé pour la résolution d'identité et la pertinence.
billingaddress2	chaîne	Adresse de facturation ligne 2. Utilisé pour la résolution d'identité.
country	chaîne	Code de pays ISO 3166-1 alpha-2 (par exemple US, GB, AU). Utilisé pour l'éligibilité et la pertinence.
birthyear	entier	Année de naissance du client (par exemple 1990). Utilisé pour l'éligibilité et la pertinence.
newcustomer	booléen	Indique si c'est un premier achat. Utilisé pour la pertinence.
customertype	chaîne	Indique si l'utilisateur est authentifié (guest / logged_in). Utilisé pour la pertinence.
loyaltytier	chaîne	Niveau du programme de fidélité partenaire. Utilisé pour la pertinence et l'éligibilité.
loyaltyid	chaîne	Identifiant du membre du programme de fidélité. Utilisé pour la résolution d'identité.
predictedltv	décimal	Valeur totale à vie prédite, généralement à partir d'un modèle ML 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	Canal par lequel le client a été acquis. Utilisé pour la pertinence.

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

5. Track Funnel Events#

Suivez les vues d'écran, les événements commerciaux et les événements personnalisés afin que Rokt puisse comprendre où se trouve chaque client dans son parcours.

Event category

Appelez mparticle.logScreenEvent avec le nom de l'écran (par exemple, 'homepage', 'product_detail_page'). Incluez tous les attributs personnalisés supplémentaires dans l'objet info.

Log a screen view

mparticle.logScreenEvent('homepage', { 'custom-attribute': 'custom-value' });

6. Show a Placement#

Appelez mparticle.Rokt.selectPlacements sur chaque écran de paiement et de confirmation où vous souhaitez que Rokt rende du contenu. Incluez l'un des identifiants de page suivants pour spécifier le type d'écran et s'il est destiné aux tests ou à la production :

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

Attributs de placement

Passez ces attributs dans la carte attributes de selectPlacements. Fournissez toujours la valeur la plus récente — les attributs passés ici remplacent tout appel antérieur de setUserAttribute.

Afficher tous les attributs de placement

Champ	Type	Description
email	chaîne	Email du client (non haché). Utilisé pour la résolution d'identité.
firstname	chaîne	Prénom du client. Utilisé pour la personnalisation.
lastname	chaîne	Nom de famille du client. Utilisé pour la personnalisation.
mobile	chaîne	Numéro de mobile du client au format E.164. Utilisé pour la résolution d'identité.
confirmationref	chaîne	Numéro de référence de commande / confirmation. Utilisé pour la pertinence et la déduplication.
currency	chaîne	Devise de la transaction (ISO 4217, par exemple USD, GBP, AUD). Utilisé pour la pertinence.
country	chaîne	Code pays ISO 3166-1 alpha-2. Utilisé pour l'éligibilité et la pertinence.
language	chaîne	Langue préférée du client (ISO 639-1). Utilisé pour la pertinence.
totalprice	décimal	Valeur totale du panier incluant taxes et expédition. Utilisé pour la pertinence.
amount	chaîne	Sous-total du panier avant taxes et expédition. Distinct de totalprice. Utilisé pour la pertinence.
couponCode	chaîne	Code promo appliqué à la commande, le cas échéant. Utilisé pour la pertinence.
newcustomer	booléen	Indique s'il s'agit d'un premier achat. Utilisé pour la pertinence.
customertype	chaîne	guest ou logged_in. Utilisé pour la pertinence.
value	décimal	Valeur d'achat cumulative du client (par exemple "2340.00"). Utilisé pour la pertinence.
subscriptionstatus	chaîne	État de l'abonnement si applicable (active, trial, churned, paused, none). Utilisé pour la pertinence et l'éligibilité.
customersegment	chaîne	Segmentation interne du partenaire (par exemple vip, at_risk, new, reactivated). Utilisé pour la pertinence.
paymenttype	chaîne	Méthode de paiement sélectionnée (credit_card, paypal, apple_pay, etc.). Utilisé pour l'éligibilité Pay+.
paymentServiceProvider	chaîne	Liste des méthodes de paiement acceptées sur la page, séparées par des virgules (par exemple applepay,paypal,cardpayment). Les valeurs doivent être en minuscules sans espaces. Voir Fournisseur de services de paiement pour la liste complète des valeurs acceptées. Utilisé pour l'éligibilité Pay+.
ccbin	string	BIN de carte de crédit (6-8 chiffres). Utilisé pour la pertinence.
billingname	string	Nom de facturation. Utilisé pour la résolution d'identité.
billingaddress1	string	Adresse de facturation. Utilisé pour la résolution d'identité et la pertinence.
billingaddress2	string	Appartement / unité de facturation. Utilisé pour la résolution d'identité.
billingcity	string	Ville de facturation. Utilisé pour la pertinence.
billingstate	string	État ou province de facturation. Utilisé pour la pertinence.
billingzipcode	string	Code postal de facturation. Utilisé pour la résolution d'identité et la pertinence.
shippingmethod	string	Méthode d'expédition sélectionnée (standard, express, next_day). Utilisé pour la pertinence.
shippingname	string	Nom d'expédition. Utilisé pour la pertinence.
shippingaddress1	string	Adresse de livraison. Utilisé pour la pertinence.
shippingcity	string	Ville de livraison. Utilisé pour la pertinence.
shippingstate	string	État ou province de livraison. Utilisé pour la pertinence.
shippingzipcode	string	Code postal de livraison. Utilisé pour la pertinence.
shippingcountry	string	Pays de livraison (ISO 3166-1 alpha-2). Utilisé pour la pertinence.
cartItems	string	Tableau JSON sérialisé des articles du panier. Utilisé pour la pertinence.
adsexperience	string	Passez "shoppable" lors du ciblage délibéré d'une expérience Shoppable Ads.

Placement position

Les placements en superposition s'affichent au-dessus de votre écran de confirmation dans un conteneur géré par Rokt, ne nécessitant aucun changement à la disposition existante de votre application.

Pour insérer un placement en superposition, appelez selectPlacements une fois que l'écran de confirmation est chargé :

Overlay placement

var attributes = {
  // Identity
  'email': 'j.smith@example.com',
  'firstname': 'Jenny',
  'lastname': 'Smith',
  'mobile': '+13125551515',

  // Transaction
  'confirmationref': '54321',
  '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 and paymentServiceProvider for Pay+)
  'paymenttype': 'credit_card',
  'paymentServiceProvider': 'cardpayment',
  'ccbin': '411112',

  // Billing address
  'billingaddress1': '123 Main St',
  'billingcity': 'Brooklyn',
  'billingstate': 'NY',
  'billingzipcode': '11201',

  // Shipping
  'shippingmethod': 'express',
  'shippingaddress1': '175 Varick St',
  'shippingcity': 'New York',
  'shippingstate': 'NY',
  'shippingzipcode': '10014',
  'shippingcountry': 'US'
};

var config = {
  colorMode: mparticle.Rokt.ColorMode.LIGHT
};

mparticle.Rokt.selectPlacements(
  'RoktExperience',
  attributes,
  config
);

Fonctions optionnelles

Fonction	Objectif
mparticle.Rokt.close()	Fermeture automatique des placements en superposition.

Configuration supplémentaire

Passez des paramètres optionnels tels qu'un objet config pour personnaliser l'interface utilisateur du placement (par exemple, mode sombre/clair, mise en cache).

selectPlacements with config

var config = {
  colorMode: mparticle.Rokt.ColorMode.LIGHT,
  cacheConfig: {
      cacheDurationInSeconds: 1200,
      cacheAttributes: {
          'email': 'j.smith@example.com',
          'orderNumber': '123'
      }
  }
};

mparticle.Rokt.selectPlacements(
  'RoktExperience',
  attributes,
  config
);

remarque

Si vous souhaitez mettre à jour l'identifiant RoktExperience ou l'identifiant intégré RoktEmbedded1 avec une valeur différente, contactez votre gestionnaire de compte Rokt pour vous assurer que les placements Rokt sont configurés de manière cohérente.

Events API

Le SDK+ fournit des événements de cycle de vie de placement auxquels vous pouvez vous abonner. Utilisez le rappel onEvent dans votre appel selectPlacements pour répondre à l'état de chargement, à l'engagement et aux échecs.

Subscribe to placement events

mparticle.Rokt.selectPlacements(
  'RoktExperience',
  attributes,
  config,
  null,
  function(event) {
      // Handle placement events
      if (event && event.eventType) {
          console.log('Rokt event: ' + event.eventType);
      }
  }
);

Événements standard

Afficher tous les événements standard

Événement	Description	Paramètres
ShowLoadingIndicator	Déclenché avant que le SDK+ n'appelle le backend de Rokt.
HideLoadingIndicator	Déclenché lorsque le SDK+ reçoit un succès ou un échec du backend de Rokt.
PlacementInteractive	Déclenché lorsqu'un placement a été rendu et est interactif.	placementId: String
PlacementReady	Déclenché lorsqu'un placement est prêt à être affiché mais n'a pas encore rendu de contenu.	placementId: String
OfferEngagement	Déclenché lorsque l'utilisateur interagit avec l'offre.	placementId: String
PositiveEngagement	Déclenché lorsque l'utilisateur interagit positivement avec l'offre.	placementId: String
FirstPositiveEngagement	Déclenché lorsque l'utilisateur interagit positivement avec l'offre pour la première fois.	placementId: String, fulfillmentAttributes: Object
OpenUrl	Déclenché lorsque l'utilisateur appuie sur une URL configurée pour être envoyée à l'application partenaire.	placementId: String, url: String
PlacementClosed	Déclenché lorsqu'un placement est fermé par l'utilisateur.	placementId: String
PlacementCompleted	Déclenché lorsque la progression de l'offre atteint la fin et qu'il n'y a plus d'offres à afficher. Également déclenché lorsque le cache est atteint mais que le placement récupéré ne sera pas affiché car il a été précédemment rejeté.	placementId: String
PlacementFailure	Déclenché lorsqu'un placement n'a pas pu être affiché en raison d'une défaillance ou lorsqu'aucun placement n'est disponible à afficher.	placementId: String (optionnel)
CartItemInstantPurchase	Déclenché lorsque l'achat d'un article du catalogue est initié par l'utilisateur (iOS uniquement).	placementId: String, cartItemId: String, catalogItemId: String, currency: String, description: String, linkedProductId: String, totalPrice: Number, quantity: Number, unitPrice: Number

7. Appendix#

Annexe A : Configuration de l'application

Les applications peuvent transmettre des paramètres de configuration via l'objet config afin que le SDK+ utilise la configuration personnalisée de votre application au lieu des paramètres par défaut du système.

Objet ColorMode

Valeur	Description
LIGHT	L'application est en mode clair
DARK	L'application est en mode sombre
SYSTEM	L'application utilise le mode couleur du système par défaut

selectPlacements with ColorMode

var config = {
    colorMode: mparticle.Rokt.ColorMode.LIGHT
};

mparticle.Rokt.selectPlacements(
    'RoktExperience',
    attributes,
    config
);

Objet CacheConfig

Paramètre	Description
cacheDurationInSeconds	Durée optionnelle en secondes pendant laquelle le SDK+ Rokt doit mettre en cache l'expérience. La valeur maximale autorisée est de 90 minutes ; la valeur par défaut est de 90 minutes si non fournie ou invalide.
cacheAttributes	Attributs optionnels à utiliser comme clé de cache. Si null, tous les attributs envoyés dans selectPlacements seront utilisés comme clé de cache.

Cache for 1200 seconds

// Cache the experience for 1200 seconds, using email and orderNumber as the cache key.
var config = {
    cacheConfig: {
        cacheDurationInSeconds: 1200,
        cacheAttributes: {
            'email': 'j.smith@example.com',
            'orderNumber': '123'
        }
    }
};

mparticle.Rokt.selectPlacements(
    'RoktExperience',
    attributes,
    config
);

EdgeToEdgeDisplay (Android uniquement)

Contrôle si la superposition Rokt respecte le mode d'affichage bord à bord d'Android. Cette configuration s'applique uniquement au chemin Android ; iOS n'utilise pas ce drapeau.

Valeur	Description
true (par défaut)	L'application prend en charge le mode d'affichage bord à bord
false	L'application ne prend pas en charge le mode d'affichage bord à bord

Le SDK+ Cordova n'expose pas actuellement EdgeToEdgeDisplay comme option de configuration JavaScript. Si votre application Android choisit de ne pas utiliser l'affichage bord à bord et que la superposition s'affiche incorrectement, configurez-la dans votre code Android natif :

EdgeToEdgeDisplay (native Android — RoktConfig)

import com.mparticle.rokt.RoktConfig

val roktConfig = RoktConfig.Builder()
    .edgeToEdgeDisplay(false) // set to false if your app does not use edge-to-edge
    .build()

Transmettez roktConfig à selectPlacements dans votre couche Android native, ou soulevez cette question avec votre gestionnaire de compte Rokt si vous avez besoin d'un support au niveau Cordova.

Annexe B : Composants UI natifs

Le SDK+ Cordova utilise des composants UI Rokt natifs rendus par les SDK+ iOS et Android sous-jacents. Il n'y a pas de composant UI déclaratif spécifique à Cordova (équivalent à Jetpack Compose ou SwiftUI). L'UI du placement est entièrement gérée par la couche native et affichée via l'API selectPlacements.

Appendice C : Gestion des erreurs

L'API IDSync est conçue pour être centrale dans l'état de votre application et est conçue pour être rapide et hautement disponible. De la même manière que votre application peut empêcher les utilisateurs de se connecter, de se déconnecter ou de modifier leur état sans connexion Internet — traitez ces API comme des opérations de contrôle pour maintenir un état utilisateur cohérent. Le SDK+ ne réessaiera pas automatiquement les appels API, mais fournit des API de rappel pour que vous puissiez le faire selon votre logique métier.

Si vous n'implémentez pas de gestion des erreurs, vous pourriez rencontrer des problèmes de cohérence des données à grande échelle.

Le modèle de rappel du SDK+ Cordova mparticle.Identity.identify() fait remonter les erreurs via le gestionnaire onError. Inspectez l'objet errorResponse pour déterminer l'action appropriée :

IDSync error handling

var identifyTask = {
    onSuccess: function(userID) {
        // IDSync succeeded — proceed with the identified user
        console.log('Identify success, userID: ' + userID);
    },
    onError: function(errorResponse) {
        if (errorResponse && errorResponse.httpCode !== undefined) {
            if (errorResponse.httpCode === -1) {
                // Device is likely offline (maps to UNKNOWN_ERROR on Android,
                // MPIdentityErrorResponseCodeClientNoConnection on iOS) — retry the request
            } else if (errorResponse.httpCode === 429) {
                // Throttled — retry with exponential backoff
            } else if (errorResponse.httpCode >= 500) {
                // Server-side error — contact your account representative
            } else {
                // Inspect errorResponse for implementation issues (e.g. 400 invalid request, 401 auth error)
                console.error('Identity error: ' + JSON.stringify(errorResponse));
            }
        }
    }
};

var identity = new mparticle.Identity();
identity.identify(identifyRequest, identifyTask.onSuccess);

Codes d'erreur iOS

Sur iOS, le SDK+ natif mappe les échecs à des valeurs MPIdentityErrorResponseCode. Le pont Cordova les fait remonter comme httpCode dans la réponse d'erreur JavaScript. Codes clés à gérer :

Code	Signification	Action
MPIdentityErrorResponseCodeClientNoConnection	Appareil hors ligne ou pas de réseau	Réessayez la requête
MPIdentityErrorResponseCodeClientSideTimeout	Connexion TCP expirée	Réessayez la requête
MPIdentityErrorResponseCodeRequestInProgress	Une autre requête IDSync est déjà en cours	Inspectez l'implémentation ; réessayez si peu fréquent
MPIdentityErrorResponseCodeRetry	Signal de réessai au niveau du SDK+	Réessayez la requête
429 (HTTP)	Limité par les serveurs Rokt	Réessayez avec une attente exponentielle
400 (HTTP)	Corps de requête invalide	Inspectez errorResponse — généralement un problème d'implémentation
401 (HTTP)	Erreur d'authentification	Vérifiez votre clé API

Codes d'erreur Android

Sur Android, le SDK+ natif renvoie IdentityApi.UNKNOWN_ERROR pour les échecs côté client (appareil hors ligne, délai d'attente côté client, requêtes invalides). Une réponse 429 se mappe à IdentityApi.THROTTLE_ERROR. Les deux signalent la stratégie de réessai appropriée :

• UNKNOWN_ERROR (appareil hors ligne ou problème côté client) : réessayez la requête une fois la connectivité rétablie.
• THROTTLE_ERROR / 429 : réessayez avec une attente exponentielle. Cela peut indiquer une "touche de raccourci" utilisateur ou un volume IDSync plus élevé que prévu — inspectez votre implémentation si cela se produit fréquemment.

Appendice D : Transmission de l'ID de session du web au natif

Lorsque le parcours d'un utilisateur s'étend à la fois sur les plateformes web et natives, vous pouvez maintenir une session Rokt cohérente en transmettant l'ID de session du SDK+ Web au SDK+ Cordova. Cela est utile pour les flux hybrides où les utilisateurs effectuent une action dans une WebView (comme une page de paiement) et retournent à l'application native pour confirmation.

Obtention de l'ID de session depuis le SDK+ Web

Après avoir appelé selectPlacements, l'ID de session est disponible sur le contexte de sélection :

Retrieve sessionId from the selection context

const selection = await launcher.selectPlacements({
    identifier: "checkout",
    attributes: {
        email: "user@example.com",
        // ... other attributes
    }
});

const sessionId = await selection.context.sessionId;

remarque

The session ID is a unique GUID assigned to the current user journey. It is useful for debugging and for correlating a user's activity across your web and native surfaces.

Transmission à l'application native via un lien profond

Transmettez l'ID de session à votre application native en utilisant un lien profond :

Deep-link to native app

const deepLink = `myapp://confirmation?sessionId=${encodeURIComponent(sessionId)}`;
window.location.href = deepLink;

Définition de l'ID de session

Extrayez l'ID de session du lien profond et transmettez-le au SDK+ avant d'appeler selectPlacements.

Set sessionId in Cordova

// Extract the sessionId from your deep link handler and set it before selectPlacements
var sessionId = getSessionIdFromDeepLink(); // Your deep link parsing logic

if (sessionId) {
    mparticle.Rokt.setSessionId(sessionId);
}

// Then proceed with selectPlacements
mparticle.Rokt.selectPlacements('RoktExperience', attributes, config);

Remarques

• Appelez setSessionId avant selectPlacements pour vous assurer que la session est utilisée.
• Les chaînes vides sont ignorées et n'actualiseront pas la session.
• Encodez toujours l'ID de session en URL lorsque vous le passez en tant que paramètre de requête.

8. Test Your Integration#

Pour confirmer que le SDK+ s'initialise et que les événements sont correctement enregistrés :

1Enable verbose SDK+ logging#

Activez la journalisation détaillée du SDK+ avant l'initialisation pour voir ce qui est envoyé.

Enable verbose SDK+ logging (iOS)

[MParticle sharedInstance].logLevel = MPILogLevelVerbose;

2Build and run your app#

Construisez et exécutez votre application avec une clé de développement avec l'environnement défini sur Développement sur les deux plateformes.

3Trigger selectPlacements#

Déclenchez selectPlacements sur l'écran où le placement doit être rendu et confirmez que le placement se charge.

4Verify events#

Vérifiez que les événements sont enregistrés et que l'appel identifyRequest réussit.

Dépannage

Si le placement ne s'affiche pas ou si les événements n'apparaissent pas, vérifiez les journaux de l'appareil natif (console Xcode pour iOS, Android Logcat pour Android) pour les erreurs du SDK Rokt. Problèmes courants :

Erreurs d'initialisation

• Confirmez que la clé et le secret correspondent aux valeurs de votre gestionnaire de compte Rokt à la fois sur iOS (your-key / your-secret dans optionsWithKey:secret:) et Android (.credentials("your-key", "your-secret")).
• Confirmez que MParticle.start (Android) et [[MParticle sharedInstance] startWithOptions:options] (iOS) s'exécutent avant tout appel selectPlacements ou logEvent.

Erreurs d'identité

Si le rappel d'identification déclenche une erreur, consultez Gestion des erreurs pour les codes d'erreur et les conseils de nouvelle tentative. Sans gestion des erreurs, vous pourriez rencontrer des problèmes de cohérence des données à grande échelle.

Placement non rendu

• Confirmez que le placement identifier (par exemple, RoktExperience) correspond à ce que votre gestionnaire de compte Rokt a configuré.
• Pour les placements intégrés, confirmez que l'identifiant de la vue intégrée (par exemple, RoktEmbedded1) correspond à la configuration de la mise en page.
• Vérifiez que la carte des attributs contient au moins email, firstname, lastname, billingzipcode, et confirmationref.