Guide d'Intégration du SDK Flutter

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 pour Flutter. 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 Cible et Langue 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 (Swift ou Objective-C sur iOS, Kotlin ou Java sur Android) lorsque vous initialiserez le SDK+ à l'Étape 2. Toutes les autres étapes utilisent Dart via le package mparticle_flutter_sdk.

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

Le SDK+ Flutter fonctionne au-dessus du SDK+ natif. Les étapes d'installation côté Dart sont les mêmes pour chaque cible ; l'installation native diffère selon la plateforme cible. Utilisez le pilule Target ci-dessus pour basculer entre iOS, Android et Web.

1Add the mparticle_flutter_sdk package#

Ajoutez le package mparticle_flutter_sdk à votre projet Flutter.

Add the Flutter package

flutter pub add mparticle_flutter_sdk

2Pin mparticle_flutter_sdk to 2.0 or later#

Après avoir exécuté pub add, votre pubspec.yaml devrait verrouiller le package à 2.0 ou plus (nécessaire pour les publicités Shoppable Ads).

pubspec.yaml

dependencies:
  mparticle_flutter_sdk: ^2.0.0

3Add the Rokt SDK+ to your iOS app#

Le SDK+ Rokt nécessite une cible de déploiement minimum de iOS 15.0. Utilisez CocoaPods ou Swift Package Manager — selon ce que votre projet utilise déjà.

Install method

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

ios/Podfile

pod 'RoktSDKPlus', '~> 9.2'

4Get the SDK handle#

Importez le package dans votre code Dart et obtenez une instance du SDK. Ce mpInstance est le gestionnaire du SDK sur lequel repose le reste de ce guide — chaque appel d'API Dart dans les étapes ultérieures (identifier, définir les attributs utilisateur, enregistrer les événements, afficher les emplacements) passe par lui.

Get the SDK handle

import 'package:mparticle_flutter_sdk/mparticle_flutter_sdk.dart';

MparticleFlutterSdk? mpInstance = await MparticleFlutterSdk.getInstance();

2. Initialize the Rokt SDK+#

Le SDK+ Flutter s'initialise via le SDK+ natif sur votre plateforme cible. Insérez l'extrait d'initialisation approprié côté natif, puis le package mparticle_flutter_sdk côté Dart le relaiera.

Lorsque vous insérez le snippet d'initialisation, vous verrez des champs personnalisables pour :

1Entering your Rokt key and secret#

Définissez la clé et le secret Rokt aux valeurs fournies par votre gestionnaire de compte Rokt.

2Setting your data environment#

Définissez l'environnement SDK+ sur développement lors des tests pour acheminer les données vers l'environnement de Développement, et sur production pour envoyer l'activité client en direct à la Production. (iOS : .development / .production. Android : MParticle.Environment.Development / MParticle.Environment.Production.)

3Entering a custom first-party domain#

Suivez les instructions dans Configuration du domaine de première partie, et définissez l'URL de base personnalisée sur votre objet network-options à votre sous-domaine personnalisé. Acheminer le SDK+ Rokt via votre propre domaine réduit le risque que les bloqueurs de publicités et les navigateurs bloquent les publicités ou les données. Omettez complètement les options réseau 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. Une fois identifié, utilisez le callback de succès (iOS : onIdentifyComplete. Android : addSuccessListener) pour définir des attributs utilisateur supplémentaires.

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'affectation (iOS) ou passez null (Android) — le SDK+ s'initialisera quand même, et vous pourrez identifier l'utilisateur plus tard via Étape 3 : Identifier l'utilisateur. Consultez Gestion des erreurs pour savoir comment gérer les échecs d'identité — sans gestion des erreurs, vous pourriez rencontrer des problèmes de cohérence des données à grande échelle.

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

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

  // Enter your custom subdomain if you are using a first-party domain configuration (optional)
  let networkOptions = MPNetworkOptions()
  networkOptions.customBaseURL = URL(string: "https://rkt.example.com")
  options.networkOptions = networkOptions

  // Identify the current user:
  let identifyRequest = MPIdentityApiRequest.withEmptyUser()

  // If you're using an un-hashed email address, set it in 'email'.
  identifyRequest.email = "j.smith@example.com"

  // If you're using a hashed email address, set it in 'other' instead of email
  identifyRequest.setIdentity("sha256 hashed email goes here", identityType: .other)

  // If the user is identified with their email address, set additional user attributes.
  options.identifyRequest = identifyRequest
  options.onIdentifyComplete = {(result: MPIdentityApiResult?, error: Error?) in
      if let user = result?.user {
          user.setUserAttribute("example attribute key", value: "example attribute value")
      }
  }
  MParticle.sharedInstance().start(with: options)

  // Register after MParticle.sharedInstance().start(), before selectShoppableAds
  if let paymentExt = RoktPaymentExtension(
      applePayMerchantId: "merchant.com.yourapp.rokt", // omit if not offering Apple Pay
      urlScheme: "myapp" // omit if not offering Afterpay / Clearpay
  ) {
      MParticle.sharedInstance().rokt.registerPaymentExtension(paymentExt)
  }
  return true
}

remarque

Configurez stripePublishableKey dans vos paramètres du kit mParticle Rokt (tableau de bord mParticle). Le kit le transmet à Rokt sous forme de stripeKey lors de l'enregistrement — vous ne le passez pas dans le code. Au moins un de applePayMerchantId ou urlScheme doit être fourni.

5Registering the payment extension#

Enregistrez RoktPaymentExtension après MParticle.sharedInstance().start() et avant selectShoppableAds pour activer les paiements des publicités Shoppable. L'enregistrement est requis pour tous les placements de publicités Shoppable sur iOS — passez applePayMerchantId pour Apple Pay, urlScheme pour Afterpay / Clearpay, ou les deux. Consultez Annexe F : Configurer les paiements des publicités Shoppable.

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

Identifiant	Type	Description
email	string	Transmettez l'adresse e-mail brute et non hachée du client.
mobile_number	string	Transmettez le numéro de téléphone du client au format E.164.
customerId	string	Transmettez votre identifiant client/compte interne. Envoyez-le à chaque écran pour les utilisateurs connectés.
other	string	Transmettez 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.
other2	string	Transmettez 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_number et other2.

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.

2Use the success handler for additional attributes#

Pour définir des attributs utilisateur supplémentaires, utilisez le gestionnaire de succès then lors de l'appel d'identification (web : identityCallback). Si le identityRequest réussit, tous les attributs utilisateur que vous définissez dans le gestionnaire sont attribués à l'utilisateur identifié.

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

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

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

Appeler ces méthodes fait passer l'enregistrement du 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 (Dart)

import 'package:mparticle_flutter_sdk/identity/identity_type.dart';
import 'package:mparticle_flutter_sdk/identity/identity_api_result.dart';
import 'package:mparticle_flutter_sdk/identity/identity_api_error_response.dart';

// 1. Create the identityRequest object
var identityRequest = MparticleFlutterSdk.identityRequest;
// Preferred: pass the customer's raw, unhashed email.
// If you can only provide a SHA-256-hashed email, remove the Email line and use IdentityType.Other instead — do not pass both.
identityRequest.setIdentity(identityType: IdentityType.Email, value: 'j.smith@example.com');
identityRequest.setIdentity(identityType: IdentityType.Other, value: 'SHA-256 hashed email');  // only if raw email unavailable
// If you can only provide a SHA-256-hashed mobile number, use IdentityType.Other2 instead of MobileNumber — do not pass both.
identityRequest.setIdentity(identityType: IdentityType.Other2, value: 'SHA-256 hashed mobile number');  // only if raw mobile unavailable
identityRequest.setIdentity(identityType: IdentityType.MobileNumber, value: '+13125551515');
identityRequest.setIdentity(identityType: IdentityType.CustomerId, value: 'cust_10482');

// 2. Optionally set user attributes in the success handler.
void Function(IdentityApiResult) identityCallback = (IdentityApiResult successResponse) {
  successResponse.user.setUserAttribute('firstname', 'Jane');
  successResponse.user.setUserAttribute('lastname', 'Smith');
};

// 3. Call one of the following methods that best matches the user's action:
mpInstance?.identity.login(identityRequest: identityRequest).then(identityCallback); // Call when the user logs in or creates an account
mpInstance?.identity.identify(identityRequest: identityRequest).then(identityCallback); // Call when you obtain the user's email mid-session, but not during a login
mpInstance?.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 (Dart)

import 'package:mparticle_flutter_sdk/mparticle_flutter_sdk.dart';

// Retrieve the current user. This will only succeed if you have identified the user during SDK initialization or by calling the identify method.
var currentUser = await mpInstance?.getCurrentUser();

// Once you have successfully set the current user to `currentUser`, you can set user attributes with:
currentUser?.setUserAttribute(key: 'custom-attribute-name', value: '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(key: 'firstname', value: 'John');
currentUser?.setUserAttribute(key: 'lastname', value: 'Doe');
// Phone numbers can be formatted either as '1234567890', or '+1 (234) 567-8901'
currentUser?.setUserAttribute(key: 'mobile', value: '3125551515');
currentUser?.setUserAttribute(key: 'age', value: '33');
currentUser?.setUserAttribute(key: 'gender', value: 'M');
currentUser?.setUserAttribute(key: 'city', value: 'Brooklyn');
currentUser?.setUserAttribute(key: 'state', value: 'NY');
currentUser?.setUserAttribute(key: 'zip', value: '123456');
currentUser?.setUserAttribute(key: 'dob', value: 'yyyymmdd');
currentUser?.setUserAttribute(key: 'title', value: 'Mr');
currentUser?.setUserAttribute(key: 'language', value: 'en');
currentUser?.setUserAttribute(key: 'lifetime_value', value: '52.25');
currentUser?.setUserAttribute(key: 'predictedltv', value: '136.23');

// You can create a user attribute to contain a list of values
var attributeList = <String>[];
attributeList.add('documentary');
attributeList.add('comedy');
attributeList.add('romance');
attributeList.add('drama');
currentUser?.setUserAttributeArray(key: 'favorite-genres', value: attributeList);

// To remove a user attribute, call removeUserAttribute and pass in the attribute name. All user attributes share the same key space.
currentUser?.removeUserAttribute(key: 'attribute-to-remove');

Attributs utilisateur

Définissez autant que possible des éléments suivants que vous pouvez collecter :

Afficher tous les attributs utilisateur

Attribut	Type	Description
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 téléphone formaté comme 1112345678 ou +1 (222) 345-6789. Utilisé pour la résolution d'identité et la pertinence.
age	integer	Âge du client. Alternative à dob. Utilisé pour l'éligibilité et la pertinence.
dob	string	Date de naissance, yyyymmdd. Alternative à age. Utilisé pour l'éligibilité et la pertinence.
gender	string	Genre du client. Par exemple, M, F, Male, ou Female. Utilisé pour la pertinence.
title	string	Titre de civilité. Par exemple, Mr, Mrs, Ms. Utilisé pour la personnalisation.
language	string	Code de langue ISO 639-1 associé à l'achat. Utilisé pour la pertinence.
city	string	Ville de facturation. Utilisé pour la pertinence.
state	string	État / province / région de facturation. Utilisé pour la pertinence et l'éligibilité.
zip	string	Code postal complet (préférence américaine est ZIP+4). Utilisé pour la résolution d'identité et la pertinence.
country	string	Code de pays ISO 3166-1 alpha-2 (par exemple US, GB, AU). Utilisé pour l'éligibilité et la pertinence.
newcustomer	boolean	Indique si c'est un premier achat. Utilisé pour la pertinence.
customertype	string	Indique si l'utilisateur est authentifié (guest / logged_in). Utilisé pour la pertinence.
loyaltytier	string	Niveau du programme de fidélité partenaire. Utilisé pour la pertinence et l'éligibilité.
loyaltyid	string	ID de membre du programme de fidélité. Utilisé pour la résolution d'identité.
lifetime_value	decimal	Valeur d'achat cumulée du client, sous forme de chaîne (par exemple "52.25"). Utilisé pour la pertinence.
predictedltv	decimal	Valeur totale à vie prédite, généralement à partir d'un modèle ML partenaire. Distinct de lifetime_value. 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.
utmsource	string	Source d'attribution marketing. Utilisé pour la pertinence.
utmmedium	string	Support d'attribution marketing. Utilisé pour la pertinence.
utmcampaign	string	Campagne d'attribution marketing. 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 mpInstance?.logScreenEvent() avec le nom de l'écran (par exemple, 'homepage', 'product_detail_page'). Incluez tous les attributs personnalisés supplémentaires dans la carte customAttributes de l'événement.

Log a screen view (Dart)

import 'package:mparticle_flutter_sdk/events/screen_event.dart';

ScreenEvent screenEvent = ScreenEvent(eventName: 'homepage')
..customAttributes = {'custom-attribute': 'custom-value'};
mpInstance?.logScreenEvent(screenEvent);

6. Show a Placement#

Appelez selectPlacements sur chaque écran de paiement et de confirmation sur lequel 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 page in a staging (or testing) environment.
• prod.rokt.conf: A confirmation page in a production environment.
• stg.rokt.payments: A payments page in a staging (or testing) environment.
• prod.rokt.payments: A payments page in a production environment.

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

Attribut	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 incluant taxes et livraison. Utilisé pour la pertinence.
amount	string	Sous-total du panier avant taxes et livraison. Distinct de totalprice. Utilisé pour la pertinence et les publicités Shoppable.
cartitemcount	integer	Nombre d'articles dans le panier. Utilisé pour la pertinence.
cartItems	array	Tableau structuré d'objets de ligne de panier (Flutter Web uniquement). Voir Articles du panier sous Événements commerciaux. 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.
lifetime_value	decimal	Valeur cumulative des achats du client (par exemple "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 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+ et la priorisation des méthodes de paiement des publicités Shoppable.
paymentServiceProvider	string	Services de paiement proposés sur la page (apple_pay, paypal, card). 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ée 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ée 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ée pour la pertinence.
shippingaddress1	string	Adresse de livraison. Utilisée pour la pertinence et l'exécution des commandes Shoppable Ads.
shippingcity	string	Ville de livraison. Utilisée pour la pertinence et l'exécution des commandes Shoppable Ads.
shippingstate	string	État ou province de livraison. Utilisé pour la pertinence et l'exécution des commandes Shoppable Ads.
shippingzipcode	string	Code postal de livraison. Utilisé pour la pertinence et l'exécution des commandes Shoppable Ads.
shippingcountry	string	Pays de livraison (ISO 3166-1 alpha-2). Utilisé pour la pertinence et l'exécution des commandes Shoppable Ads.
adsexperience	string	Passez "shoppable" lors de la sélection délibérée 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 (Dart)

import 'package:mparticle_flutter_sdk/mparticle_flutter_sdk.dart';

final 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',
  'cartitemcount': '2',
  'couponcode': 'SUMMER20',

  // Customer context
  'newcustomer': 'false',
  'customertype': 'logged_in',
  'lifetime_value': '2340.00',
  'subscriptionstatus': 'active',
  'customersegment': 'vip',

  // Payment (include paymenttype and paymentServiceProvider for Pay+)
  'paymenttype': 'credit_card',
  'paymentServiceProvider': 'card',
  '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',
};

final roktConfig = RoktConfig(
  colorMode: ColorMode.light,
);

mpInstance?.rokt.selectPlacements(
  identifier: 'RoktExperience',
  attributes: attributes,
  roktConfig: roktConfig,
);

Fonctions optionnelles

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

Configuration supplémentaire

Passez des paramètres optionnels tels que RoktConfig pour personnaliser l'interface utilisateur du placement (par exemple, mode sombre/clair, mise en cache). Les chemins de fichiers de polices peuvent également être fournis sous forme de carte des noms PostScript vers les chemins des ressources.

selectPlacements with RoktConfig and font typefaces (Dart)

// If you want to use custom fonts for your placement, create a fontTypefaces map
final fontTypefaces = {'Arial-Bold': 'fonts/Arial-Bold.ttf'};

final roktConfig = RoktConfig(
  colorMode: ColorMode.light,
);

mpInstance?.rokt.selectPlacements(
  identifier: 'RoktExperience',
  attributes: attributes,
  fontFilePathMap: fontTypefaces,
  roktConfig: 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.

Événements API

Sur iOS et Android, le SDK+ fournit des événements de cycle de vie des placements sous forme de flux via le MPRoktEvents EventChannel. Sur le Web, abonnez-vous aux événements directement sur l'objet de sélection retourné par selectPlacements.

Subscribe to placement events (Dart)

final EventChannel roktEventChannel = EventChannel('MPRoktEvents');
roktEventChannel.receiveBroadcastStream().listen((dynamic event) {
  debugPrint('rokt_event: $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.	identifier: String
PlacementReady	Déclenché lorsqu'un placement est prêt à être affiché mais n'a pas encore rendu de contenu.	identifier: String
OfferEngagement	Déclenché lorsque l'utilisateur interagit avec l'offre.	identifier: String
PositiveEngagement	Déclenché lorsque l'utilisateur interagit positivement avec l'offre.	identifier: String
FirstPositiveEngagement	Déclenché lorsque l'utilisateur interagit positivement avec l'offre pour la première fois.	identifier: String, fulfillmentAttributes: FulfillmentAttributes
OpenUrl	Déclenché lorsque l'utilisateur appuie sur une URL configurée pour être envoyée à l'application partenaire.	identifier: String, url: String
PlacementClosed	Déclenché lorsqu'un placement est fermé par l'utilisateur.	identifier: 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é.	identifier: 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.	identifier: String (optionnel)
EmbeddedSizeChanged	Déclenché lorsque la hauteur d'un placement intégré change.	identifier: String, selectedHeight: Double
CartItemInstantPurchase	Déclenché lorsque l'achat d'un article du catalogue est initié par l'utilisateur.	identifier: String, catalogItemId: String, cartItemId: String, totalPrice: String, currency: String
CartItemInstantPurchaseInitiated	Flux d'achat démarré — l'utilisateur a appuyé sur "Acheter" (Shoppable Ads, iOS uniquement).	identifier: String, catalogItemId: String, cartItemId: String
CartItemInstantPurchaseFailure	Échec de l'achat (Shoppable Ads, iOS uniquement).	identifier: String, catalogItemId: String, cartItemId: String, error: String
CartItemDevicePay	Paiement par Apple Pay / appareil déclenché (Shoppable Ads, iOS uniquement).	identifier: String, catalogItemId: String, cartItemId: String, paymentProvider: String
InstantPurchaseDismissal	L'utilisateur a rejeté la superposition d'achat (Shoppable Ads, iOS uniquement).	identifier: String

7. Appendix#

Appendice A : Configuration de l'application

Les applications peuvent passer des paramètres de configuration via RoktConfig 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

RoktConfig with ColorMode

final roktConfig = RoktConfig(
    colorMode: ColorMode.light,
);

mpInstance?.rokt.selectPlacements(
    identifier: 'RoktExperience',
    attributes: attributes,
    roktConfig: roktConfig,
);

EdgeToEdgeDisplay (Android uniquement)

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

Lors de la construction du RoktConfig natif sur Android, appelez edgeToEdgeDisplay(true) sur le RoktConfig.Builder pour activer le mode bord à bord :

RoktConfig with EdgeToEdgeDisplay (Android native)

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

val roktConfig = RoktConfig.Builder()
    .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+ de 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.
final roktConfig = RoktConfig(
    cacheConfig: CacheConfig(
        cacheDurationInSeconds: 1200,
        cacheAttributes: {'email': 'j.smith@example.com', 'orderNumber': '123'},
    ),
);

mpInstance?.rokt.selectPlacements(
    identifier: 'RoktExperience',
    attributes: attributes,
    roktConfig: roktConfig,
);

Appendice B : Support SwiftUI avec MPRoktLayout (iOS uniquement)

Si votre application est principalement écrite en SwiftUI, le composant MPRoktLayout offre une approche plus moderne et déclarative pour intégrer les emplacements Rokt dans votre application iOS.

La classe MPRoktLayout fournit une manière compatible avec SwiftUI d'afficher les emplacements Rokt sans appeler manuellement selectPlacements, prenant en charge à la fois les types d'emplacements en superposition et intégrés.

SwiftUI placement with MPRoktLayout

import SwiftUI
import mParticle_Apple_SDK
import mParticle_Rokt_Swift

struct OrderConfirmationView: View {
    let attributes = [
        "email": "test@gmail.com",
        "firstname": "Jenny",
        "lastname": "Smith",
        "billingzipcode": "07762",
        "confirmationref": "54321"
    ]

    @State private var sdkTriggered = true

    var body: some View {
        VStack(alignment: .leading) {
            // Other UI components
            Text("Order Confirmation")
                .font(.title)

            // Rokt placement using SwiftUI
            MPRoktLayout(
                sdkTriggered: $sdkTriggered,
                identifier: "RoktExperience",
                locationName: "RoktEmbedded1", // For embedded placements
                attributes: attributes,
                config: roktConfig, // Optional RoktConfig
                onEvent: { roktEvent in
                    // Optional: Handle different event types see above
                }
            ).roktLayout
        }
        .frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .topLeading)
    }
}

Paramètre	Type	Description
sdkTriggered	Bool	Contrôle quand l'emplacement doit être déclenché.
identifier	String	L'identifiant de l'emplacement Rokt (par exemple, "RoktExperience").
locationName	String?	Nom de lieu optionnel pour les emplacements intégrés (par exemple, "RoktEmbedded1").
attributes	[String: String]	Dictionnaire d'attributs à transmettre à l'emplacement.
config	RoktConfig?	Objet de configuration optionnel pour le mode couleur, la mise en cache, etc.
onEvent	((RoktEvent) -> Void)?	Callback optionnel pour gérer tous les événements d'emplacement.

Appendice C : Support de Jetpack Compose avec RoktLayout (Android uniquement)

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 supporte 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",
            "mobile" to "(323) 867-5309",
            "postcode" to "90210",
            "country" to "US"
        )
        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 = "Location1",
            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 "Location1").
attributes	Map<String, String>	Carte des attributs à transmettre au placement.
modifier	Modifier	Compose Modifier pour personnaliser la disposition, 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 D : 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.

IDSync error handling

import 'package:mparticle_flutter_sdk/identity/identity_api_result.dart';
import 'package:mparticle_flutter_sdk/identity/identity_api_error_response.dart';

mpInstance?.identity
    .identify(identityRequest: identityRequest)
    .then(
        (IdentityApiResult successResponse) {
            // Proceed with the identified user
        },
        onError: (error) {
            var failureResponse = error as IdentityAPIErrorResponse;
            // Inspect failureResponse.statusCode to determine the error type:
            // - Check for network errors (device offline) and retry the request
            // - Check for throttle errors (429) and retry with backoff
            print('Identity error: $failureResponse');
        }
    );

Codes d'erreur côté client (iOS)

L'énumération MPIdentityErrorResponseCode définit les codes côté client suivants :

MPIdentityErrorResponseCode	Description
MPIdentityErrorResponseCodeRequestInProgress	La requête HTTP IDSync n'a pas été effectuée car une requête HTTP IDSync 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 refus de consentement.
MPIdentityErrorResponseCodeUnknown	La requête HTTP IDSync a échoué en raison d'une erreur inconnue.

Codes d'erreur Android

Le SDK+ Android renvoie IdentityApi.UNKNOWN_ERROR pour les problèmes côté client, y compris la perte de couverture de l'appareil, le délai d'attente côté client, ou les requêtes d'identité invalides. Vérifiez THROTTLE_ERROR (HTTP 429) et réessayez avec un backoff lorsque rencontré.

Codes de statut HTTP

Valeur	Description
400	L'appel HTTP IDSync a échoué en raison d'un corps de requête invalide.
401	L'appel HTTP IDSync a échoué en raison d'une erreur d'authentification. Vérifiez que votre clé API est correcte.
429	L'appel HTTP IDSync a été limité et doit être réessayé.
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.

Appendice E : Transmission de l'ID de session du web vers le natif

Lorsque le parcours 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 Flutter SDK+. Cela est utile pour les flux hybrides où les utilisateurs effectuent une action dans un WebView (comme une page de paiement) et retournent à l'application native pour confirmation.

Récupération 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;

Configuration de l'ID de session sur iOS

Extrait l'ID de session du lien profond et transmettez-le au SDK+ avant d'appeler selectPlacements. Ajoutez ceci à votre AppDelegate.swift :

Handle deep link and set sessionId (iOS)

func handleDeepLink(url: URL) {
    let components = URLComponents(url: url, resolvingAgainstBaseURL: false)
    if let sessionId = components?.queryItems?.first(where: { $0.name == "sessionId" })?.value {
        MParticle.sharedInstance().rokt.setSessionId(sessionId: sessionId)
    }
    // Proceed with your confirmation flow
}

Configuration de l'ID de session sur Android

Extrait l'ID de session du lien profond et transmettez-le au SDK+ avant d'appeler selectPlacements. Ajoutez ceci à votre MainActivity :

Handle deep link and set sessionId (Android)

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

    intent.data?.getQueryParameter("sessionId")?.let { sessionId ->
        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.
• Encodez toujours l'ID de session en URL lorsque vous le passez en tant que paramètre de requête.

Appendice F : Configurer les paiements des publicités Shoppable (iOS uniquement)

Si vous n'utilisez pas les publicités Shoppable, passez cette étape.

Les publicités Shoppable sur iOS nécessitent un RoktPaymentExtension (iOS natif) enregistré et prennent en charge plusieurs méthodes de paiement. L'enregistrement de l'extension est obligatoire pour chaque placement de publicités Shoppable, même si vous n'offrez que des méthodes basées sur la redirection. Les extraits d'enregistrement et de redirection se trouvent dans l'étape Afficher un Placement cible des publicités Shoppable (interstitiel).

Méthode	Configuration iOS
Apple Pay	ID marchand Apple Pay passé en tant que applePayMerchantId sur RoktPaymentExtension. Optionnel.
PayPal	Intégré dans le Rokt SDK+ — aucune configuration d'extension supplémentaire. Nécessite la redirection de l'URL.
Afterpay / Clearpay	Schéma d'URL personnalisé dans Info.plist + correspondance urlScheme sur RoktPaymentExtension + redirection de l'URL.
Transfert de carte	API de partage de paiement partenaire + attributs partnerpaymentreference / last4digits sur selectShoppableAds.

remarque

Apple Pay est optionnel — les publicités Shoppable prennent également en charge PayPal intégré et le transfert de carte sans ID marchand Apple Pay. Au moins un de applePayMerchantId ou urlScheme doit être fourni lors de la création de l'extension. Configurez stripePublishableKey dans vos paramètres du kit mParticle Rokt ; le kit le transfère automatiquement à Rokt.

Pour offrir Apple Pay, créez un ID marchand Apple Pay, configurez votre projet Xcode, et générez un certificat de traitement de paiement en suivant Apple Pay — configuration iOS, puis transmettez l'ID marchand en tant que applePayMerchantId.

8. Test Your Integration#

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

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

// Enable mParticle debug logging at the Dart level
MparticleFlutterSdk.setLogLevel(LogLevel.verbose);

2Build and run against a development environment#

Construisez et exécutez votre application avec l'environnement de développement configuré sur le côté natif :

• iOS : environment = .development (Swift) ou MPEnvironmentDevelopment (Objective-C)
• Android : MParticle.Environment.Development
• Web : isDevelopmentMode: true

3Trigger selectPlacements#

Déclenchez selectPlacements sur l'écran où le placement doit s'afficher et confirmez que le placement se charge.

4Verify events#

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

• iOS : Vérifiez la console Xcode pour la sortie de journal du Rokt SDK+.
• Android : Vérifiez le Logcat d'Android Studio pour la sortie de journal du Rokt SDK+.
• Web : Ouvrez les outils de développement, allez à l'onglet Réseau, filtrez par experiences, et confirmez qu'une requête /experiences avec le statut 200 est envoyée.

Dépannage

Si le placement ne s'affiche pas ou si les événements n'apparaissent pas, vérifiez la console de débogage de votre plateforme pour les erreurs du SDK+ Rokt. Problèmes courants :

Erreurs d'initialisation

• Confirmez que les key et secret (iOS/Android) ou API_KEY (Web) correspondent aux valeurs de votre gestionnaire de compte Rokt.
• Assurez-vous que l'initialisation du SDK+ natif s'exécute avant tout appel selectPlacements ou logEvent depuis votre code Dart.
• Sur Android, assurez-vous que votre activité racine étend FlutterFragmentActivity.
• Pour les publicités Shoppable sur iOS, assurez-vous que RoktPaymentExtension est enregistré après l'initialisation du SDK+ et avant selectShoppableAds.

Erreurs d'identité

Si le gestionnaire onError de l'appel d'identification s'exécute, inspectez le IdentityAPIErrorResponse pour le code d'état et réessayez la requête selon votre logique métier. Sans gestion des erreurs, vous pourriez rencontrer des problèmes de cohérence des données à grande échelle.

Placement non rendu

• 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, assurez-vous 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.