Guide d'Intégration SDK+ Android

Platform

WebiOSAndroidFlutterReact NativeMAUICordova

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 pour Android. 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.

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

Le SDK+ Rokt nécessite un niveau d'API Android minimum de 21+ (Android 5.0 Lollipop).

Mettez à jour votre fichier Gradle pour inclure les dépendances nécessaires :

build.gradle.kts dependencies

dependencies {
  implementation("com.mparticle:android-rokt-kit:6.0.0")
  implementation("com.mparticle:android-core:6.0.0")
}

build.gradle dependencies

dependencies {
  implementation "com.mparticle:android-rokt-kit:6.0.0"
  implementation "com.mparticle:android-core:6.0.0"
}

2. Initialize the Rokt SDK+#

Insérez le snippet d'initialisation suivant dans la méthode onCreate() de votre classe Application. Le SDK+ doit être initialisé avant tout autre appel d'API du SDK+. Remplacez your-key et your-secret par la clé et le secret fournis par votre équipe Rokt.

Application.onCreate initialization

import com.mparticle.MParticle
import com.mparticle.MParticleOptions
import com.mparticle.networking.NetworkOptions

class YourApplicationClass : Application() {
  override fun onCreate() {
      super.onCreate()

      // Identify the current user:
      // If you do not have the user's email address, you can pass in a null value
      val identifyRequest = IdentityApiRequest.withEmptyUser()
          // Preferred: pass the customer's raw, unhashed email via .email().
          // If you can only provide a SHA-256-hashed email, remove .email() and use .userIdentity(Other) instead — do not pass both.
          .email("j.smith@example.com")
          .userIdentity(MParticle.IdentityType.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.
          .userIdentity(MParticle.IdentityType.Other2, "SHA-256 hashed mobile number")  // only if raw mobile unavailable
          // Customer phone number in E.164 format.
          .userIdentity(MParticle.IdentityType.MobileNumber, "+13125551515")
          // Partner's internal customer/account identifier (if the user is logged in).
          .customerId("cust_10482")
          .build()

      // If the user is identified with their email address, set additional user attributes.
      val identifyTask = BaseIdentityTask()
          .addSuccessListener { identityApiResult ->
              val user = identityApiResult.user
              user.setUserAttribute("example attribute key", "example attribute value")
          }

      // Enter your custom subdomain if you are using a first-party domain configuration (optional)
      val networkOptions = NetworkOptions.builder()
          .setCustomBaseURL("https://rkt.example.com")
          .build()

      val options: MParticleOptions = MParticleOptions.builder(this)
          .credentials(
              "your-key",   // The key provided by your Rokt account manager
              "your-secret" // The secret provided by your Rokt account manager
          )
          // 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.
          .environment(MParticle.Environment.Development)
          .networkOptions(networkOptions)
          .identify(identifyRequest)
          .identifyTask(identifyTask)
          .build()

      MParticle.start(options)
  }
}

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

1Entering your Rokt key and secret#

Définissez your-key et your-secret à l'intérieur de credentials sur les valeurs de clé et de secret fournies par votre gestionnaire de compte Rokt.

2Setting your data environment#

Définissez environment sur MParticle.Environment.Development lors des tests pour acheminer les données vers l'environnement de développement, et MParticle.Environment.Production pour envoyer l'activité client en direct vers la production.

3Entering a custom first-party domain#

Suivez les instructions dans Configuration du domaine de première partie, et définissez customBaseURL sur NetworkOptions sur votre sous-domaine personnalisé. Acheminer le SDK+ Rokt via votre propre domaine réduit le risque que les bloqueurs de publicité et les navigateurs bloquent les publicités ou les données. Omettez networkOptions pour envoyer le trafic vers les points de terminaison par défaut de Rokt.

4Identifying your user and setting attributes#

Dans identifyRequest, passez l'email brut et non haché de l'utilisateur via .email(). Pour les emails hachés et d'autres identifiants, voir Identifiants utilisateur pris en charge. Une fois identifié, utilisez le listener de succès identifyTask pour définir des attributs utilisateur supplémentaires — voir Attributs utilisateur pour la liste recommandée.

identifyTask success listener

val identifyTask = BaseIdentityTask()
  .addSuccessListener { identityApiResult ->
      val user = identityApiResult.user
      user.setUserAttribute("example attribute key", "example attribute value")
  }

remarque

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

Initialisation avec des polices

Au lieu de ou en plus de fournir des polices sur One Platform, vous pouvez utiliser des polices déjà intégrées à votre application. Cela élimine la possibilité que des polices soient téléchargées lors de l'initialisation, réduisant l'utilisation du réseau et le risque d'erreurs de téléchargement.

Utilisation des actifs de polices

Passez une carte à la méthode du constructeur roktOptions qui mappe les noms PostScript des polices à leur chemin d'accès dans le répertoire assets. Vérifiez avec votre gestionnaire de compte si vous n'êtes pas sûr des noms PostScript utilisés dans votre mise en page.

Font assets

import com.mparticle.MParticle
import com.mparticle.MParticleOptions

class YourApplication : Application() {
  override fun onCreate() {
      super.onCreate()
      val options: MParticleOptions = MParticleOptions.builder(this)
          .credentials("your-key", "your-secret")
          .environment(MParticle.Environment.Development)
          .roktOptions(RoktOptions(fontFilePathMap = mapOf("Arial-Bold" to "fonts/arialbold.otf")))
          .build()
      MParticle.start(options)
  }
}

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 garder l'identité de l'utilisateur synchronisée chaque fois qu'il se connecte, se déconnecte, ou fournit autrement 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	Transmettez l'adresse e-mail brute et non hachée du client via .email("j.smith@example.com").
mobile	string	Transmettez le numéro de téléphone du client au format E.164 via .userIdentity(MParticle.IdentityType.MobileNumber, "+13125551515").
customerid	string	Transmettez votre identifiant client/compte interne via .customerId("cust_10482"). Envoyez à chaque écran pour les utilisateurs connectés.
other	string	Transmettez un e-mail haché en SHA-256 via .userIdentity(MParticle.IdentityType.Other, "hashed email"). Utilisez uniquement lorsque l'e-mail brut ne peut pas être fourni.
other2	string	Transmettez un numéro de mobile haché en SHA-256 via .userIdentity(MParticle.IdentityType.Other2, "hashed mobile").

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#

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

• MParticle.getInstance()?.Identity()?.login : appelez lorsque l'utilisateur se connecte ou crée un compte.
• MParticle.getInstance()?.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.getInstance()?.Identity()?.logout : appelez lorsque l'utilisateur se déconnecte.

Appeler ces méthodes fait évoluer l'enregistrement de l'état actuel de l'utilisateur dans le SDK. 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
val identifyRequest = IdentityApiRequest.withEmptyUser()
  // Preferred: pass the customer's raw, unhashed email via .email().
  // If you can only provide a SHA-256-hashed email, remove .email() and use .userIdentity(Other) instead — do not pass both.
  .email("j.smith@example.com")
  .userIdentity(MParticle.IdentityType.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.
  .userIdentity(MParticle.IdentityType.Other2, "SHA-256 hashed mobile number")  // only if raw mobile unavailable
  .userIdentity(MParticle.IdentityType.MobileNumber, "+13125551515")
  .customerId("cust_10482")
  .build()

// 2. Optionally set user attributes once the request succeeds.
val identityCallback = BaseIdentityTask()
  .addSuccessListener { identityApiResult ->
      val user = identityApiResult.user
      user.setUserAttribute("firstname", "Jane")
      user.setUserAttribute("lastname", "Smith")
  }

// 3. Call one of the following methods that best matches the user's action:
MParticle.getInstance()?.Identity()?.login(identifyRequest, identityCallback) // Call when the user logs in or creates an account
MParticle.getInstance()?.Identity()?.identify(identifyRequest, identityCallback) // Call when you obtain the user's email mid-session, but not during a login
MParticle.getInstance()?.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 fournir des offres pertinentes.

Set User Attributes

import com.mparticle.MParticle

// Retrieve the current user. This will only succeed if you have identified the user during SDK+ initialization or by calling the identify method.
val currentUser = MParticle.getInstance()?.Identity()?.currentUser

// Once you have successfully set the current user to `currentUser`, 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?.setUserAttributeList("favorite-genres", listOf("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 :

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.
birthyear	entier	Année de naissance du client (par exemple, 1990). Champ de date de naissance préféré. Alternatives : dob, age. Utilisé pour l'éligibilité 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 honorifique. 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.
billingaddress1	chaîne	Adresse de rue (par exemple, 123 Main St). Utilisé pour la résolution d'identité et la pertinence.
billingaddress2	chaîne	Appartement/unité (par exemple, Apt 4B). Utilisé pour la résolution d'identité.
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.
country	chaîne	Code pays ISO 3166-1 alpha-2 (par exemple, US, GB, AU). 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	ID de membre du programme de fidélité. Utilisé pour la résolution d'identité.
predictedltv	décimal	Valeur totale de vie prédite, généralement 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	Comment le client a été initialement acquis. Utilisé pour la pertinence.

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

5. Log 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.getInstance()?.logScreen() avec le nom de l'écran (par exemple, "homepage", "product_detail_page"). Incluez tous les attributs personnalisés supplémentaires dans la carte d'informations.

Log a screen view

MParticle.getInstance()?.logScreen(
  "homepage",
  mapOf("custom-attribute" to "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 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	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 exemple 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, taxes et frais de port inclus. Utilisé pour la pertinence.
amount	decimal	Sous-total du panier avant taxes et frais de port. Distinct de totalprice. Utilisé pour la pertinence.
cartItems	array	Tableau structuré d'objets de ligne de panier. Doit être en camelCase. 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 d'achat cumulative du client. 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.
paymenttype	string	Méthode de paiement sélectionnée (credit_card, paypal, apple_pay, etc.). Utilisé pour l'éligibilité Pay+.
paymentServiceProvider	string	Liste de méthodes de paiement acceptées sur l'écran, séparées par des virgules (par exemple, applepay,paypal,cardpayment). Les valeurs doivent être en minuscules et 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.
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.
billingname	string	Nom complet du titulaire de la carte à l'adresse de facturation. Utilisé pour la résolution d'identité.
shippingmethod	string	Méthode d'expédition sélectionnée (standard, express, next_day). Utilisé pour la pertinence.
shippingname	string	Nom complet du destinataire à l'adresse de livraison. 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 ou ZIP de livraison. Utilisé pour la pertinence.
shippingcountry	string	Pays de livraison (ISO 3166-1 alpha-2). Utilisé pour la pertinence.
partnerpaymentreference	string	Identifiant non devinable pour la méthode de paiement enregistrée du client. Utilisé pour le transfert de carte des publicités Shoppable.
last4digits	string	Derniers 4 chiffres de la carte utilisée. Utilisé pour la résolution d'identité.
plcc	string	"yes" ou "no" — si le client possède une carte de crédit à étiquette privée. Utilisé pour la pertinence Pay+.
discountamount	decimal	Remise au niveau de la commande appliquée. Utilisé pour la pertinence Pay+.
prescreen	string	"yes" ou "no" — si le client a été pré-qualifié pour une offre de crédit. Utilisé pour la pertinence Pay+.
adsexperience	string	Passer "shoppable" lors du ciblage d'une expérience de publicités Shoppable.

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

import com.mparticle.MParticle
import com.mparticle.rokt.RoktConfig

val attributes = mapOf(
  // Identity
  "email" to "j.smith@example.com",
  "firstname" to "Jenny",
  "lastname" to "Smith",
  "mobile" to "+13125551515",

  // Transaction
  "confirmationref" to "54321",
  "currency" to "USD",
  "country" to "US",
  "language" to "en",
  "totalprice" to "149.99",
  "couponcode" to "SUMMER20",

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

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

  // Billing address
  "billingaddress1" to "123 Main St",
  "billingcity" to "Brooklyn",
  "billingstate" to "NY",
  "billingzipcode" to "11201",

  // Shipping
  "shippingmethod" to "express",
  "shippingaddress1" to "175 Varick St",
  "shippingcity" to "New York",
  "shippingstate" to "NY",
  "shippingzipcode" to "10014",
  "shippingcountry" to "US"
)

val roktConfig = RoktConfig.Builder().colorMode(RoktConfig.ColorMode.LIGHT).build()

MParticle.getInstance()?.Rokt()?.selectPlacements(
  identifier = "RoktExperience",
  attributes = attributes,
  config = roktConfig
)

Fonctions optionnelles

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

Configuration supplémentaire

Transmettez des paramètres optionnels tels que RoktConfig pour personnaliser l'interface utilisateur de l'emplacement (par exemple, mode sombre/clair, mise en cache). Les polices de caractères peuvent également être fournies sous forme de carte de noms PostScript à des objets Typeface.

selectPlacements with RoktConfig and font typefaces

val fontTypefaces: MutableMap<String, WeakReference<android.graphics.Typeface>> = HashMap()
fontTypefaces["Arial-Bold"] = WeakReference(yourTypefaceObject)

val roktConfig = RoktConfig.Builder().colorMode(RoktConfig.ColorMode.LIGHT).build()

MParticle.getInstance()?.Rokt()?.selectPlacements(
  identifier = "RoktExperience",
  attributes = attributes,
  fontTypefaces = fontTypefaces,
  config = 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 emplacements Rokt sont configurés de manière cohérente.

Events API

Le SDK+ fournit des événements de cycle de vie de placement sous forme de flux via l'API MParticle.getInstance()?.Rokt()?.events. Utilisez Kotlin Flow pour consommer les événements produits par le SDK+.

Subscribe to Placement Events

import com.mparticle.MParticle

// owner: LifecycleOwner
owner.lifecycleScope.launch {
  owner.lifecycle.repeatOnLifecycle(Lifecycle.State.CREATED) {
      MParticle.getInstance()?.Rokt()?.events("RoktExperience")?.collect { roktEvent ->
          // Handle the event
      }
  }
}

É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 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: FulfillmentAttributes
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 placement est fermé par l'utilisateur.	placementId: String
PlacementCompleted	Déclenché lorsque la progression de l'offre atteint la fin et qu'aucune autre offre n'est disponible à 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 de l'article du catalogue est initié par l'utilisateur.	placementId: String, cartItemId: String, catalogItemId: String, currency: String, description: String, linkedProductId: String, totalPrice: Double, quantity: Int, unitPrice: Double

Événements globaux

Utilisez Rokt.globalEvents() pour vous abonner aux événements au niveau du SDK+ qui ne sont pas liés à un placement spécifique.

Subscribe to global events

import com.rokt.roktsdk.RoktEvent

// owner: LifecycleOwner
owner.lifecycleScope.launch {
  Rokt.globalEvents().collect { event ->
      if (event is RoktEvent.InitComplete) {
          // SDK+ initialization is complete
      }
  }
}

7. Appendix#

Annexe A : Configuration de l'application

Les applications peuvent transmettre des paramètres de configuration via RoktConfig afin que le SDK+ Android 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

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

RoktConfig with ColorMode and EdgeToEdgeDisplay

import com.mparticle.MParticle
import com.mparticle.rokt.RoktConfig

val roktConfig = RoktConfig.Builder()
    .colorMode(RoktConfig.ColorMode.LIGHT)
    .edgeToEdgeDisplay(true)
    .build()

MParticle.getInstance()?.Rokt()?.selectPlacements(
    identifier = "RoktExperience",
    attributes = attributes,
    config = roktConfig
)

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

import com.mparticle.rokt.CacheConfig
import com.mparticle.rokt.RoktConfig

// Cache the experience for 1200 seconds, using email and orderNumber as the cache key.
val roktConfig = RoktConfig.Builder()
    .cacheConfig(CacheConfig(
        cacheDurationInSeconds = 1200,
        cacheAttributes = mapOf("email" to "j.smith@example.com", "orderNumber" to "123")
    ))
    .build()

MParticle.getInstance()?.Rokt()?.selectPlacements(
    identifier = "RoktExperience",
    attributes = attributes,
    config = roktConfig
)

Appendice B : Support de Jetpack Compose avec RoktLayout

Pour les écrans implémentés en utilisant Jetpack Compose, le SDK+ fournit le composable RoktLayout pour une intégration moderne et déclarative des placements Rokt. RoktLayout prend en charge les types de placement Overlay, BottomSheet et Embedded sans invoquer manuellement selectPlacements.

Jetpack Compose placement with RoktLayout

import com.mparticle.kits.RoktLayout
import com.mparticle.MpRoktEventCallback
import com.mparticle.UnloadReasons

@Composable
fun MainScreen(modifier: Modifier = Modifier) {
    Column(
        modifier = modifier
            .background(Color.LightGray)
            .padding(8.dp),
    ) {
        val attributes = mapOf(
            "email" to "j.smith@example.com",
            "firstname" to "Jenny",
            "lastname" to "Smith",
            "billingzipcode" to "90210",
            "confirmationref" to "54321"
        )
        val callbacks = object : MpRoktEventCallback {
            override fun onLoad() = println("View loaded")
            override fun onUnload(reason: UnloadReasons) = println("View unloaded due to: $reason")
            override fun onShouldShowLoadingIndicator() = println("Show loading indicator")
            override fun onShouldHideLoadingIndicator() = println("Hide loading indicator")
        }
        val roktConfig = RoktConfig.Builder()
            .colorMode(RoktConfig.ColorMode.DARK)
            .cacheConfig(CacheConfig(
                cacheDurationInSeconds = 1200,
                cacheAttributes = mapOf("email" to "j.smith@example.com")
            ))
            .build()

        RoktLayout(
            sdkTriggered = true,
            identifier = "RoktExperience",
            attributes = attributes,
            location = "RoktEmbedded1",
            modifier = Modifier
                .fillMaxWidth()
                .background(Color.Black),
            mpRoktEventCallback = callbacks,
            config = roktConfig
        )
    }
}

Paramètres

Paramètre	Type	Description
sdkTriggered	Boolean	Contrôle quand le placement doit être déclenché.
identifier	String	L'identifiant de l'expérience Rokt (par exemple, "RoktExperience").
location	String?	Nom de localisation optionnel pour les placements intégrés (par exemple, "RoktEmbedded1").
attributes	Map<String, String>	Carte des attributs à transmettre au placement.
modifier	Modifier	Compose Modifier pour personnaliser la mise en page, le style et le comportement de l'interface utilisateur.
mpRoktEventCallback	MpRoktEventCallback	Callback optionnel pour gérer les événements de placement (chargement, déchargement, état de chargement).
config	RoktConfig?	Configuration optionnelle pour le mode couleur, la mise en cache, etc.

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 callback pour que vous puissiez le faire selon votre logique métier.

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

Le SDK+ renvoie toujours le statut HTTP et le corps de la réponse HTTP sous-jacente. Pour les problèmes côté client (appareil hors couverture, délai d'attente côté client, demandes d'identité invalides), le SDK+ renvoie IdentityApi.UNKNOWN_ERROR avec un message d'erreur informatif.

IDSync error handling

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
        }
    }
    ?.addSuccessListener { identityApiResult ->
        // Proceed with the identified user
    }

IDSync error handling

MParticle.getInstance().Identity().identify(identifyRequest)
    .addFailureListener(new TaskFailureListener() {
        @Override
        public void onFailure(IdentityHttpResponse identityHttpResponse) {
            if (identityHttpResponse.getHttpCode() == IdentityApi.UNKNOWN_ERROR) {
                // Device is likely offline — retry the request
            } else if (identityHttpResponse.getHttpCode() == IdentityApi.THROTTLE_ERROR) {
                // Throttled (429) — retry with backoff
            }
        }
    })
    .addSuccessListener(new TaskSuccessListener() {
        @Override
        public void onSuccess(IdentityApiResult identityApiResult) {
            // Proceed with the identified user
        }
    });

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 Web SDK+ au SDK+ Android. Cela est utile pour les flux hybrides où les utilisateurs effectuent une action dans un WebView (comme une page de paiement) et reviennent à 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 et transmettez-le au SDK+ avant d'appeler selectPlacements.

Handle deep link and set sessionId

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    intent.data?.getQueryParameter("sessionId")?.let { sessionId ->
        MParticle.getInstance()?.Rokt()?.setSessionId(sessionId)
    }

    // Proceed with your confirmation flow
}

Handle deep link and set sessionId

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    Uri data = getIntent().getData();
    if (data != null) {
        String sessionId = data.getQueryParameter("sessionId");
        if (sessionId != null) {
            MParticle.getInstance().Rokt().setSessionId(sessionId);
        }
    }

    // Proceed with your confirmation flow
}

Remarques

• Appelez setSessionId avant selectPlacements pour garantir que la session est utilisée.
• Les chaînes vides sont ignorées et n'actualiseront pas la session.
• Toujours encoder l'ID de session en URL lors de la transmission 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 afin de voir ce qui est envoyé.

Enable verbose SDK+ logging

MParticle.setLogLevel(MParticle.LogLevel.VERBOSE)

2Build and run your app#

Construisez et exécutez votre application avec environment = MParticle.Environment.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.

Dépannage

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

Erreurs d'initialisation

• Confirmez que la clé et le secret credentials correspondent aux valeurs de votre gestionnaire de compte Rokt.
• Assurez-vous que MParticle.start(options) s'exécute dans Application.onCreate() avant tout appel à selectPlacements ou logEvent.

Erreurs d'identité

Si le listener d'échec identifyTask est déclenché, consultez Gestion des erreurs pour les codes d'erreur IdentityApi 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 ne s'affiche pas

• Assurez-vous que le placement identifier (par exemple RoktExperience) correspond à ce que votre gestionnaire de compte Rokt a configuré.
• Pour les placements intégrés, vérifiez 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.

Erreurs de poignée de main SSL lors de l'utilisation d'un proxy

Lors des tests dans votre environnement de développement, vous pourriez rencontrer des erreurs de poignée de main SSL lorsqu'un proxy de débogage HTTP comme Charles ou Proxyman est en cours d'exécution, ou lorsque vous êtes derrière un proxy de réseau d'entreprise. Cela est attendu : le SDK+ épingle son certificat SSL, et un proxy intercepte HTTPS en présentant son propre certificat, ce qui échoue à l'épingle.

Pour permettre au proxy d'inspecter le trafic du SDK+, désactivez l'épinglage dans votre build de développement en ajoutant setPinningDisabledInDevelopment(true) au constructeur NetworkOptions dans votre script d'initialisation du SDK+.

Disable SSL pinning for proxy debugging

val networkOptions = NetworkOptions.builder()
  // Only takes effect in the development environment; production builds stay pinned.
  .setPinningDisabledInDevelopment(true)
  .build()