Guide d'Intégration du SDK React Native

Platform

WebiOSAndroidFlutterReact NativeMAUICordova

Target

Language

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 React Native. 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.

remarque

Vous écrirez quelques lignes de code natif lorsque vous initialiserez le SDK+ à l'Étape 2. Toutes les autres étapes utilisent JavaScript via le package react-native-mparticle.

1. Add the Rokt SDK+ to Your React Native App#

1Install the React Native package#

Ajoutez le SDK+ React Native comme dépendance à votre application :

Install the React Native package

npm install react-native-mparticle --save

2Import the package into your app#

Importez le package dans le code de votre application React Native et obtenez une instance du SDK :

Import the React Native package

import MParticle from 'react-native-mparticle';

Continuez à configurer le SDK+ sur votre projet natif. Utilisez le bouton Target ci-dessus pour basculer entre iOS et Android.

L'étape d'installation NPM ci-dessus intègre automatiquement le framework React et le framework iOS de base. Le SDK+ Rokt pour iOS est ajouté en tant que dépendance pod dans votre ios/Podfile.

3Add the Rokt SDK pod to your Podfile#

Ajoutez le pod SDK+ Rokt à votre ios/Podfile :

ios/Podfile

pod 'RoktSDKPlus', '~> 9.2'

Parce que le SDK iOS de Rokt contient du code Swift, vous devez soit conserver le lien statique par défaut de React Native avec une exception pre_install, soit passer votre projet aux frameworks. Choisissez le chemin qui correspond à votre projet :

Linkage

4Configure your Podfile#

Ajoutez le bloc pre_install suivant à votre ios/Podfile :

ios/Podfile (pre_install block)

pre_install do |installer|
installer.pod_targets.each do |pod|
  if pod.name == 'RoktSDKPlus' || pod.name == 'mParticle-Apple-SDK' || pod.name == 'mParticle-Rokt' || pod.name == 'Rokt-Widget'
    def pod.build_type
      Pod::BuildType.new(:linkage => :dynamic, :packaging => :framework)
    end
  end
end
end

5Install pods#

Exécutez pod install pour appliquer les modifications :

Install pods

bundle exec pod install

2. Initialize the Rokt SDK+#

Initialisez le SDK+ Rokt sur le côté natif. Le SDK+ doit être initialisé avant tout autre appel d'API SDK+. Utilisez le bouton Target ci-dessus pour basculer entre iOS et Android.

Insérez le snippet d'initialisation dans votre fichier AppDelegate. Remplacez your-key et your-secret par les valeurs fournies par votre gestionnaire de compte Rokt.

attention

Appelez registerPaymentExtension après MParticle.sharedInstance().start(with:) et avant selectShoppableAds. Cela est requis pour les placements de Shoppable Ads sur iOS.

AppDelegate initialization (Swift)

import mParticle_Apple_SDK
import RoktPaymentExtension

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
  // Initialize the SDK
  let options = MParticleOptions(key: "your-key",
  secret: "your-secret")
  // Specify the data environment with environment:
  // Set it to .development if you are still testing your integration.
  // Set it to .production if your integration is ready for production data.
  // The default is .autoDetect which attempts to detect the environment automatically
  options.environment = .development
  MParticle.sharedInstance().start(with: options)

  // Register after MParticle.sharedInstance().start(), before selectShoppableAds
  if let paymentExt = RoktPaymentExtension(
      applePayMerchantId: "merchant.com.yourapp.rokt"
  ) {
      MParticle.sharedInstance().rokt.registerPaymentExtension(paymentExt)
  }
  return true
}

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

1Entering your Rokt key and secret#

Définissez your-key et your-secret dans MParticleOptions(key:secret:) aux valeurs fournies par votre gestionnaire de compte Rokt.

2Setting your data environment#

Définissez options.environment sur .development lors des tests pour diriger les données vers l'environnement de Développement, et .production pour envoyer l'activité client en direct vers la Production.

3Registering the payment extension#

Enregistrez RoktPaymentExtension après MParticle.sharedInstance().start(with:) et avant selectShoppableAds pour activer les paiements Shoppable Ads (y compris Apple Pay). Remplacez merchant.com.yourapp.rokt par votre identifiant marchand Apple Pay. Requis pour tous les placements de Shoppable Ads sur iOS. La clé publiable Stripe est configurée dans vos paramètres mParticle Rokt kit (tableau de bord mParticle) — vous ne passez que l'identifiant marchand Apple Pay dans le code. RoktPaymentExtension est un type Swift ; si votre AppDelegate est en Objective-C, faites cela à partir d'un petit fichier Swift.

remarque

Pour identifier l'utilisateur et définir des attributs utilisateur supplémentaires, voir Étape 3 : Identifier l'utilisateur ci-dessous. Si vous n'avez pas l'email de l'utilisateur lors de l'initialisation, vous pouvez identifier l'utilisateur plus tard — voir Gestion des erreurs pour savoir comment gérer les erreurs d'identité.

3. 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 comme décrit ci-dessous.

Identifiants utilisateur pris en charge

Afficher les identifiants utilisateur pris en charge

Champ	Type	Description
email	chaîne	Transmettez l'adresse e-mail brute et non hachée du client.
mobile	chaîne	Transmettez le numéro de téléphone du client au format E.164.
customerid	chaîne	Transmettez votre identifiant client/compte interne. Envoyez-le sur chaque écran pour les utilisateurs connectés.
other	chaîne	Transmettez un e-mail haché en SHA-256. Utilisez uniquement lorsque l'e-mail brut ne peut pas être fourni — ne transmettez pas à la fois email et other. (Chemin Android uniquement.)
other2	chaîne	Transmettez un numéro de mobile haché en SHA-256. Utilisez uniquement lorsque le numéro de mobile brut ne peut pas être fourni — ne transmettez pas à la fois mobile et other2. (Chemin Android uniquement.)
emailSha256	chaîne	Transmettez un e-mail haché en SHA-256. Utilisez uniquement lorsque l'e-mail brut ne peut pas être fourni — ne transmettez pas à la fois email et emailSha256. (Chemin iOS uniquement.)
mobileSha256	chaîne	Transmettez un numéro de mobile haché en SHA-256. Utilisez uniquement lorsque le numéro de mobile brut ne peut pas être fourni — ne transmettez pas à la fois mobile et mobileSha256. (Chemin iOS uniquement.)

Pour identifier l'utilisateur :

1Create an IdentityRequest object#

Créez un objet IdentityRequest 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.

2Set additional attributes via the identity callback#

Pour définir des attributs utilisateur supplémentaires, utilisez le rappel d'identité. Si le identifyRequest réussit, tous les attributs utilisateur que vous définissez à l'intérieur du rappel sont attribués à l'utilisateur identifié.

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

Transmettez le identifyRequest (et éventuellement le 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 passer 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
const request = new MParticle.IdentityRequest();
// Preferred: pass the customer's raw, unhashed email.
// If you can only provide a SHA-256-hashed email, remove .email and use other instead — do not pass both.
request.email = 'j.smith@example.com';
request.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 mobile — do not pass both.
// (Called 'other2' on Android and 'mobileSha256' on iOS; both use this same field.)
request.other2 = 'SHA-256 hashed mobile number';  // only if raw mobile unavailable
request.mobile = '+13125551515';
request.customerId = 'cust_10482';

// 2. User attributes are set using the identity callback
const identityCallback = (error, userId) => {
  if (error) {
      console.debug(error);
  } else {
      const user = new MParticle.User(userId);
      user.setUserAttribute('firstname', 'Jane');
      user.setUserAttribute('lastname', 'Smith');
  }
};
// 3. Call one of the following methods that best matches the user's action:
MParticle.Identity.login(request, identityCallback); // Call when the user logs in or creates an account
MParticle.Identity.identify(request, 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

4. Set User Attributes#

Définissez les attributs utilisateur progressivement au fur et à 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 proposer des offres pertinentes.

Set user attributes

import MParticle from 'react-native-mparticle';

// Retrieve the current user. This will only succeed if you have identified the user during SDK+ initialization or by calling the identify method.
MParticle.Identity.getCurrentUser((currentUser) => {
  if (currentUser) {
      // Once you have 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.
      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	Sexe 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 (la préférence aux États-Unis 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é du partenaire. Utilisé pour la pertinence et l'éligibilité.
loyaltyid	chaîne	ID de 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 pour 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

import MParticle from 'react-native-mparticle';

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

6. Show a Placement#

Appelez selectPlacements sur chaque écran de paiement et de confirmation où vous souhaitez que Rokt affiche du contenu. Incluez l'un des identifiants de page suivants pour spécifier le type d'écran et s'il s'agit d'un test ou d'une 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.

Appelez selectPlacements dès que l'écran se charge et une fois que tous les attributs pertinents sont disponibles. Passez au minimum email, firstname, lastname, billingzipcode, et confirmationref. Voir Attributs de placement pour la liste complète.

Pay+

Pour les placements Pay+, incluez paymenttype et paymentServiceProvider dans l'appel selectPlacements sur chaque écran. paymentServiceProvider communique les méthodes de paiement disponibles sur l'écran de paiement; paymenttype communique la méthode avec laquelle l'utilisateur a payé.

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	string	Email du client (non haché). Utilisé pour la résolution d'identité.
firstname	string	Prénom du client. Utilisé pour la personnalisation.
lastname	string	Nom de famille du client. Utilisé pour la personnalisation.
mobile	string	Numéro de mobile du client au format E.164. Utilisé pour la résolution d'identité.
confirmationref	string	Numéro de référence de commande / confirmation. Utilisé pour la pertinence et la déduplication.
currency	string	Devise de la transaction (ISO 4217, par ex. USD, GBP, AUD). Utilisé pour la pertinence.
country	string	Code pays ISO 3166-1 alpha-2. Utilisé pour l'éligibilité et la pertinence.
language	string	Langue préférée du client (ISO 639-1). Utilisé pour la pertinence.
totalprice	decimal	Valeur totale du panier incluant taxes et frais de livraison. Utilisé pour la pertinence.
amount	string	Sous-total du panier avant taxes et frais de livraison. Distinct de totalprice. Utilisé pour la pertinence.
couponCode	string	Code promo appliqué à la commande, le cas échéant. Utilisé pour la pertinence.
newcustomer	boolean	Indique si c'est un premier achat. Utilisé pour la pertinence.
customertype	string	guest ou logged_in. Utilisé pour la pertinence.
value	decimal	Valeur cumulative des achats du client (par ex. "2340.00"). 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 ex. vip, at_risk, new, reactivated). Utilisé pour la pertinence.
paymenttype	string	Méthode de paiement sélectionnée (credit_card, paypal, apple_pay, etc.). Utilisé pour l'éligibilité Pay+.
paymentServiceProvider	string	Liste des méthodes de paiement acceptées sur la page, séparées par des virgules (par ex. 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 d'expédition. Utilisé pour la pertinence.
shippingcity	string	Ville d'expédition. Utilisé pour la pertinence.
shippingstate	string	État ou province d'expédition. Utilisé pour la pertinence.
shippingzipcode	string	Code postal d'expédition. Utilisé pour la pertinence.
shippingcountry	string	Pays d'expédition (ISO 3166-1 alpha-2). Utilisé pour la pertinence.
cartItems	array	Tableau structuré d'objets de ligne de panier. Utilisé pour la pertinence.
adsexperience	string	Passez "shoppable" lorsque vous ciblez délibérément 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 mise en page existante de votre application.

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

Overlay placement

import MParticle from 'react-native-mparticle';

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

const roktConfig = MParticle.Rokt.createRoktConfig('light');

MParticle.Rokt.selectPlacements(
  'RoktExperience', // identifier
  attributes,       // attributes map
  {},               // placeholders (empty for overlay)
  roktConfig,       // configuration
);

Fonctions optionnelles

Fonction	Objectif
MParticle.Rokt.close()	Fermeture automatique des placements de superposition.

Configuration supplémentaire

Transmettez des paramètres optionnels tels que RoktConfig pour personnaliser l'interface utilisateur du placement (par exemple, mode sombre/clair, mise en cache).

selectPlacements with RoktConfig

import MParticle from 'react-native-mparticle';

const roktConfig = MParticle.Rokt.createRoktConfig(
  'light',
  MParticle.Rokt.createCacheConfig(1200, { 'email': 'j.smith@example.com', 'orderNumber': '123' }),
);

MParticle.Rokt.selectPlacements(
  'RoktExperience',
  attributes,
  {},
  roktConfig,
);

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 des emplacements via le mécanisme NativeEventEmitter.

Subscribe to placement events

import { NativeEventEmitter } from 'react-native';
import MParticle from 'react-native-mparticle';

const eventManagerEmitter = new NativeEventEmitter(MParticle.RoktEventManager);

eventManagerEmitter.addListener('RoktEvents', data => {
  console.log(`event received ${JSON.stringify(data)}`);
});

Événements standards

Afficher tous les événements standards

Événement	Description	Paramètres
ShowLoadingIndicator	Déclenché avant que le SDK+ n'appelle le backend Rokt.
HideLoadingIndicator	Déclenché lorsque le SDK+ reçoit un succès ou un échec du backend Rokt.
PlacementInteractive	Déclenché lorsqu'un emplacement a été rendu et est interactif.	placementId: String
PlacementReady	Déclenché lorsqu'un emplacement 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
OpenUrl	Déclenché lorsque l'utilisateur appuie sur une URL qui est configurée pour être envoyée à l'application partenaire.	placementId: String, url: String
PlacementClosed	Déclenché lorsqu'un emplacement 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 passer des paramètres de configuration via RoktConfig pour 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

EdgeToEdgeDisplay (Android uniquement)

Ce booléen contrôle si le SDK+ Rokt s'affiche en mode bord à bord sur Android (par défaut true). Réglez sur false si votre application ne prend pas en charge l'affichage bord à bord.

EdgeToEdgeDisplay

import com.mparticle.rokt.RoktConfig

val roktConfig = RoktConfig.Builder()
    .edgeToEdgeDisplay(true)
    .build()

Objet CacheConfig

Paramètre	Description
cacheDuration	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.

RoktConfig with ColorMode and CacheConfig

import MParticle from 'react-native-mparticle';

// Cache the experience for 1200 seconds, using email and orderNumber as the cache key.
const roktConfig = MParticle.Rokt.createRoktConfig(
    'light',
    MParticle.Rokt.createCacheConfig(
        1200,
        { 'email': 'j.smith@example.com', 'orderNumber': '123' }
    ),
);

MParticle.Rokt.selectPlacements(
    'RoktExperience',
    attributes,
    {},
    roktConfig,
);

Annexe B : Composant RoktLayoutView

Pour les placements intégrés, le SDK+ React Native fournit le composant RoktLayoutView pour une approche déclarative de l'intégration des placements Rokt dans la hiérarchie de vues de votre application. RoktLayoutView prend en charge les types de placements intégrés sans avoir besoin de gérer manuellement les poignées de nœuds.

Embedded placement with RoktLayoutView

import React from 'react';
import { findNodeHandle, View } from 'react-native';
import MParticle, { RoktLayoutView } from 'react-native-mparticle';

const MyConfirmationScreen = () => {
    const placeholder1 = React.createRef();

    const handleSelectPlacements = () => {
        const placeholders = {
            RoktEmbedded1: findNodeHandle(placeholder1.current),
        };

        const attributes = {
            'email': 'j.smith@example.com',
            'firstname': 'Jenny',
            'lastname': 'Smith',
            'billingzipcode': '90210',
            'confirmationref': '54321',
        };

        MParticle.Rokt.selectPlacements(
            'RoktExperience',
            attributes,
            placeholders,
        );
    };

    return (
        <View>
            {/* Your confirmation screen content */}
            <RoktLayoutView ref={placeholder1} placeholderName="RoktEmbedded1" />
        </View>
    );
};

Paramètres

Paramètre	Type	Description
ref	Ref	Référence React utilisée pour obtenir la poignée de nœud natif pour la carte de l'espace réservé.
placeholderName	string	L'identifiant de la vue intégrée (par exemple, "RoktEmbedded1"), doit correspondre à la clé dans la carte des espaces réservés passée à 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.

IDSync error handling

import MParticle from 'react-native-mparticle';

const request = new MParticle.IdentityRequest();
request.email = 'j.smith@example.com';

MParticle.Identity.identify(request, (error, userId) => {
    if (error) {
        // Inspect error.code to determine the cause:
        // - Network errors: retry the request
        // - Throttle errors (429): retry with backoff
        console.debug('Identity error:', error);
    } else {
        // Proceed with the identified user
        const user = new MParticle.User(userId);
        user.setUserAttribute('firstname', 'Jane');
    }
});

Codes d'erreur iOS

Sur iOS, l'énumération native MPIdentityErrorResponseCode définit les codes côté client suivants. Inspectez error.code dans le rappel natif onIdentifyComplete pour déterminer la cause :

MPIdentityErrorResponseCode	Description
MPIdentityErrorResponseCodeRequestInProgress	Une requête HTTP IDSync n'a pas été effectuée car une est déjà en cours.
MPIdentityErrorResponseCodeClientSideTimeout	La requête HTTP IDSync a échoué en raison d'un délai d'attente de connexion TCP.
MPIdentityErrorResponseCodeClientNoConnection	La requête HTTP IDSync a échoué en raison d'un manque de couverture réseau.
MPIdentityErrorResponseCodeSSLError	La requête HTTP IDSync a échoué en raison d'un problème de configuration SSL.
MPIdentityErrorResponseCodeOptOut	La requête HTTP IDSync n'a pas été effectuée car le SDK+ est désactivé en raison d'un désabonnement.
MPIdentityErrorResponseCodeUnknown	La requête HTTP IDSync a échoué en raison d'une erreur inconnue.

En plus des codes côté client ci-dessus, error.code peut contenir un code de statut HTTP généré par le serveur :

Valeur	Description
400	L'appel HTTP IDSync a échoué en raison d'un corps de requête invalide. Inspectez les détails de l'erreur pour plus d'informations.
401	L'appel HTTP IDSync a échoué en raison d'une erreur d'authentification. Vérifiez que votre clé API est correcte.
403	L'appel HTTP IDSync a échoué car cette opération n'est pas provisionnée pour votre compte. Contactez votre gestionnaire de compte Rokt pour l'activer.
429	L'appel HTTP IDSync a été limité et doit être réessayé avec un backoff exponentiel. Cela peut indiquer une "touche de raccourci" utilisateur ou une implémentation incorrecte entraînant un volume IDSync plus élevé que prévu.
5xx	L'appel HTTP IDSync a échoué en raison d'un problème côté serveur Rokt. Contactez votre représentant de compte pour plus d'informations.

Codes d'erreur Android

Sur Android, l'API IDSync renvoie toujours le code de statut HTTP et le corps de la réponse HTTP sous-jacente. Pour les échecs côté client (appareil hors ligne, délai d'attente, requête invalide), le SDK+ renvoie IdentityApi.UNKNOWN_ERROR. Pour le throttling (HTTP 429), il renvoie IdentityApi.THROTTLE_ERROR. Gérez les deux dans votre écouteur d'échec :

Android IDSync error handling (Kotlin)

MParticle.getInstance()?.Identity()?.identify(identifyRequest)
    ?.addFailureListener { identityHttpResponse ->
        if (identityHttpResponse?.httpCode == IdentityApi.UNKNOWN_ERROR) {
            // Device is likely offline — retry the request
        } else if (identityHttpResponse?.httpCode == IdentityApi.THROTTLE_ERROR) {
            // Throttled (429) — retry with backoff
        }
    }

Appendice D : Transmission de l'ID de session du web vers le 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 Web SDK+ au React Native SDK+. 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 Web SDK+

Après avoir appelé selectPlacements, l'ID de session est disponible dans 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 dans votre code de plateforme native et transmettez-le au SDK+ avant d'appeler selectPlacements. Gérez cela dans votre AppDelegate natif (iOS) ou Activity (Android) avant que la couche React Native ne se charge :

Set sessionId from deep link (React Native)

import { Linking } from 'react-native';
import MParticle from 'react-native-mparticle';

// Listen for incoming deep links
Linking.addEventListener('url', ({ url }) => {
    const sessionId = new URL(url).searchParams.get('sessionId');
    if (sessionId) {
        void MParticle.Rokt.setSessionId(sessionId);
    }
});

Remarques

• Appelez setSessionId avant selectPlacements pour vous assurer que la session est utilisée.
• Les chaînes vides sont ignorées et ne mettront pas à jour la session.
• Encodez toujours l'ID de session en URL lorsque vous le transmettez 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

// For iOS verbose logging, add to your Swift AppDelegate:
// MParticle.sharedInstance().logLevel = .verbose

// For Android verbose logging, add to your Application class before MParticle.start():
// MParticle.setLogLevel(MParticle.LogLevel.VERBOSE)

2Build and run against a development key#

Construisez et exécutez votre application avec l'environnement défini sur Development.

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.

Troubleshooting

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

Erreurs d'initialisation

• Confirmez que la clé et le secret dans votre initialisation native correspondent aux valeurs de votre gestionnaire de compte Rokt.
• Confirmez que l'appel du SDK+ natif start s'exécute avant tout appel selectPlacements ou de journalisation d'événements.
• Pour les publicités Shoppable sur iOS, confirmez que RoktPaymentExtension est enregistré après start() et avant selectShoppableAds.

Erreurs d'identité

Si le rappel d'identité se déclenche avec 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 affiché

• 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 à placeholderName sur le composant RoktLayoutView.
• Vérifiez que la carte des attributs contient au moins email, firstname, lastname, billingzipcode, et confirmationref.
• Pour les placements interstitiels, confirmez Platform.OS === 'ios' avant d'appeler selectShoppableAds — les placements interstitiels ne sont pas pris en charge sur Android.