Guide d'intégration du SDK MAUI+

Platform

WebiOSAndroidFlutterReact NativeMAUICordova

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 MAUI. 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 MAUI App#

Ajoutez les packages SDK+ à votre projet :

Add SDK+ packages

dotnet add package mParticle.MAUI
dotnet add package mParticle.MAUI.Kits.Rokt
dotnet add package mParticle.MAUI.Kits.Rokt.Payments

mParticle.MAUI.Kits.Rokt.Payments inclut déjà le kit Rokt de base de manière transitive.

remarque

Pour Android, vous devez également vous assurer que votre activité étend MauiAppCompatActivity.

2. Initialize the Rokt SDK+#

Insérez le fragment d'initialisation suivant dans le démarrage de votre application. Le SDK+ doit être initialisé avant tout autre appel d'API SDK+. Remplacez your-key et your-secret par la clé et le secret fournis par votre équipe Rokt.

SDK+ initialization

using mParticle.MAUI;

string key = "";
string secret = "";
#if __ANDROID__
  key = "your-key";
  secret = "your-secret";
#elif __IOS__
  key = "your-key";
  secret = "your-secret";
#endif

// Initialize the SDK+
var options = new MParticleOptions()
{
  ApiKey = key,
  ApiSecret = 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 = mParticle.MAUI.Environment.Development;

// Enter your custom subdomain if you are using a first-party domain configuration (optional)
options.NetworkOptions = new NetworkOptions()
{
  CustomBaseUrl = "https://rkt.example.com"
};

// Identify the current user:
var identifyRequest = new IdentityApiRequest();
identifyRequest.UserIdentities = new Dictionary<UserIdentity, string>()
{
#if __ANDROID__
  // Preferred: pass the customer's raw, unhashed email.
  // If you can only provide a SHA-256-hashed email, use UserIdentity.Other instead — do not pass both.
  { UserIdentity.Email, "j.smith@example.com" },
  { UserIdentity.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.Other2, "SHA-256 hashed mobile number" },  // only if raw mobile unavailable
  { UserIdentity.MobileNumber, "+13125551515" },
  { UserIdentity.CustomerId, "cust_10482" }
#elif __IOS__
  // Preferred: pass the customer's raw, unhashed email.
  // If you can only provide a SHA-256-hashed email, use UserIdentity.Other instead — do not pass both.
  { UserIdentity.Email, "j.smith@example.com" },
  { UserIdentity.Other, "SHA-256 hashed email" },  // only if raw email unavailable
  // Customer phone number in E.164 format.
  { UserIdentity.MobileNumber, "+13125551515" },
  // If you can only provide a SHA-256-hashed mobile number, use Other2 instead of MobileNumber — do not pass both.
  { UserIdentity.Other2, "SHA-256 hashed mobile number" },  // only if raw mobile unavailable
  { UserIdentity.CustomerId, "cust_10482" }
#endif
};

// If the user is identified with their email address, set additional user attributes.
options.IdentifyRequest = identifyRequest;

OnUserIdentified onIdentifyComplete = newUser =>
{
  if (newUser != null)
  {
      newUser.SetUserAttribute("example attribute key", "example attribute value");
  }
};
options.IdentityStateListener = onIdentifyComplete;

// Register the Rokt kit with mParticle before initialization
RoktKit.Register();

MParticle.Instance.Initialize(options);

Lors de l'insertion du fragment d'initialisation dans le démarrage de votre application, vous verrez des champs personnalisables pour :

1Entering your Rokt key and secret#

Définissez your-key et your-secret à l'intérieur des blocs spécifiques à la plateforme avec les valeurs de clé et de secret fournies par votre gestionnaire de compte Rokt.

2Setting your data environment#

Définissez options.Environment sur mParticle.MAUI.Environment.Development pendant les tests pour acheminer les données vers l'environnement de développement, et mParticle.MAUI.Environment.Production pour envoyer l'activité client en direct à la production.

3Entering a custom first-party domain#

Suivez les instructions dans Configuration du domaine de première partie, et définissez options.NetworkOptions.CustomBaseUrl sur votre sous-domaine personnalisé avant d'appeler MParticle.Instance.Initialize(options). Omettez options.NetworkOptions pour envoyer le trafic vers les points de terminaison par défaut de Rokt.

4Identifying your user and setting attributes#

Dans identifyRequest.UserIdentities, transmettez l'email brut et non haché de l'utilisateur via UserIdentity.Email. Pour les emails hachés et d'autres identifiants, consultez Identifiants utilisateur pris en charge. Une fois identifié, utilisez le callback IdentityStateListener pour définir des attributs utilisateur supplémentaires — voir Attributs utilisateur pour la liste recommandée.

IdentityStateListener

OnUserIdentified onIdentifyComplete = newUser =>
{
  if (newUser != null)
  {
      newUser.SetUserAttribute("example attribute key", "example attribute value");
  }
};
options.IdentityStateListener = onIdentifyComplete;

remarque

Incluez toujours identifyRequest dans le fragment d'initialisation. Si vous n'avez pas l'email de l'utilisateur lors de l'initialisation, omettez l'entrée UserIdentity.Email — le SDK+ s'initialisera quand même, et vous pourrez identifier l'utilisateur plus tard via 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.

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

Pour identifier l'utilisateur :

1Create an identifyRequest object#

Créez un objet identifyRequest pour contenir les identifiants de l'utilisateur. Vous devez intégrer l'adresse e-mail brute et non hachée de l'utilisateur dans le champ UserIdentity.Email.

2Set additional user attributes via AddSuccessListener#

Pour définir des attributs utilisateur supplémentaires, utilisez le callback AddSuccessListener sur le résultat d'identification. Si le identifyRequest réussit, tous les attributs utilisateur que vous définissez à l'intérieur de l'écouteur sont attribués à l'utilisateur identifié.

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

Passez le identifyRequest à la méthode qui correspond à l'action de l'utilisateur :

• MParticle.Instance.Identity.Login : appelez lorsque l'utilisateur se connecte ou crée un compte.
• MParticle.Instance.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.Instance.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 un utilisateur nommé Jane Smith avec l'e-mail j.smith@example.com, le numéro de mobile +13125551515, et l'ID client cust_10482 :

Identify the user

// 1. Create the identifyRequest object
var identifyRequest = new IdentityApiRequest();
identifyRequest.UserIdentities = new Dictionary<UserIdentity, string>()
{
#if __ANDROID__
  // Preferred: pass the customer's raw, unhashed email.
  // If you can only provide a SHA-256-hashed email, use UserIdentity.Other instead — do not pass both.
  { UserIdentity.Email, "j.smith@example.com" },
  { UserIdentity.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.Other2, "SHA-256 hashed mobile number" },  // only if raw mobile unavailable
  { UserIdentity.MobileNumber, "+13125551515" },
  { UserIdentity.CustomerId, "cust_10482" }
#elif __IOS__
  // Preferred: pass the customer's raw, unhashed email.
  // If you can only provide a SHA-256-hashed email, use UserIdentity.Other instead — do not pass both.
  { UserIdentity.Email, "j.smith@example.com" },
  { UserIdentity.Other, "SHA-256 hashed email" },  // only if raw email unavailable
  // Customer phone number in E.164 format.
  { UserIdentity.MobileNumber, "+13125551515" },
  // If you can only provide a SHA-256-hashed mobile number, use Other2 instead of MobileNumber — do not pass both.
  { UserIdentity.Other2, "SHA-256 hashed mobile number" },  // only if raw mobile unavailable
  { UserIdentity.CustomerId, "cust_10482" }
#endif
};

// 2. User attributes are set using the AddSuccessListener callback
// 3. Call one of the following methods that best matches the user's action:
MParticle.Instance.Identity.Login(identifyRequest)
  .AddSuccessListener(result =>
  {
      result.User.SetUserAttribute("firstname", "Jane");
      result.User.SetUserAttribute("lastname", "Smith");
  }); // Call when the user logs in or creates an account
MParticle.Instance.Identity.Identify(identifyRequest)
  .AddSuccessListener(result =>
  {
      result.User.SetUserAttribute("firstname", "Jane");
      result.User.SetUserAttribute("lastname", "Smith");
  }); // Call when you obtain the user's email mid-session, but not during a login
MParticle.Instance.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

using mParticle.MAUI;

// 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 = MParticle.Instance.Identity.CurrentUser;

// Once you have successfully set the current user, you can set user attributes with:
currentUser.SetUserAttribute("custom-attribute-name", "custom-attribute-value");
// Note: all user attributes (including list attributes and tags) must have distinct names.

// Rokt recommends setting as many of the following user attributes as possible:
currentUser.SetUserAttribute("firstname", "John");
currentUser.SetUserAttribute("lastname", "Doe");
// Phone numbers can be formatted either as '1234567890', or '+1 (234) 567-8901'
currentUser.SetUserAttribute("mobile", "3125551515");
currentUser.SetUserAttribute("age", "33");
currentUser.SetUserAttribute("gender", "M");
currentUser.SetUserAttribute("billingcity", "Brooklyn");
currentUser.SetUserAttribute("billingstate", "NY");
currentUser.SetUserAttribute("billingzipcode", "123456");
currentUser.SetUserAttribute("dob", "yyyymmdd");
currentUser.SetUserAttribute("title", "Mr");
currentUser.SetUserAttribute("language", "en");
currentUser.SetUserAttribute("predictedltv", "136.23");

// You can create a user attribute to contain a list of values
currentUser.SetUserAttribute("favorite-genres", string.Join(", ", new string[] { "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	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 honorifique. Par exemple, Mr, Mrs, Ms. Utilisé pour la personnalisation.
language	string	Code langue ISO 639-1 associé à l'achat. Utilisé pour la pertinence.
billingcity	string	Ville de facturation. Utilisé pour la pertinence.
billingstate	string	État / province / région de facturation. Utilisé pour la pertinence et l'éligibilité.
billingzipcode	string	Code postal complet (la préférence aux États-Unis est ZIP+4). Utilisé pour la résolution d'identité et la pertinence.
billingaddress1	string	Adresse de facturation ligne 1. Utilisé pour la résolution d'identité et la pertinence.
billingaddress2	string	Adresse de facturation ligne 2. Utilisé pour la résolution d'identité.
country	string	Code pays ISO 3166-1 alpha-2 (par exemple US, GB, AU). Utilisé pour l'éligibilité et la pertinence.
birthyear	integer	Année de naissance du client (par exemple 1990). 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é du 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é.
predictedltv	decimal	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.Instance.LogScreen avec le nom de l'écran (par exemple, "homepage", "product_detail_page"). Incluez tous les attributs personnalisés supplémentaires dans le dictionnaire d'informations.

Log a screen view

MParticle.Instance.LogScreen(
  "homepage",
  new Dictionary<string, string>() { { "custom-attribute", "custom-value" } }
);

6. Show a Placement#

Appeler SelectPlacements sur chaque écran de paiement et de confirmation où vous souhaitez que Rokt affiche du contenu. Inclure 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.

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

Pay+

Pour les placements Pay+, inclure paymenttype et paymentServiceProvider dans l'appel SelectPlacements sur chaque écran. paymentServiceProvider communique quelles méthodes de paiement sont disponibles sur l'écran de paiement; paymenttype communique quelle méthode l'utilisateur a utilisée pour payer.

Attributs de placement

Passez ces attributs dans le dictionnaire 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 incluant taxes et expédition. Utilisé pour la pertinence.
amount	string	Sous-total du panier avant taxes et expédition. 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 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+.
paymentServiceProvider	string	Liste des méthodes de paiement acceptées sur la page, séparées par des virgules (par exemple applepay,paypal,cardpayment). Les valeurs doivent être en minuscules sans espaces. Voir Fournisseur de services de paiement pour la liste complète des valeurs acceptées. Utilisé pour l'éligibilité Pay+.
ccbin	string	BIN de carte de crédit (6-8 chiffres). Utilisé pour la pertinence.
billingname	string	Nom de facturation. Utilisé pour la résolution d'identité.
billingaddress1	string	Adresse de facturation. Utilisé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.
shippingname	string	Nom d'expédition. Utilisé pour la pertinence.
shippingaddress1	string	Adresse de livraison. Utilisée pour la pertinence.
shippingcity	string	Ville de livraison. Utilisée pour la pertinence.
shippingstate	string	État ou province de livraison. Utilisé pour la pertinence.
shippingzipcode	string	Code postal de livraison. Utilisé pour la pertinence.
shippingcountry	string	Pays de livraison (ISO 3166-1 alpha-2). Utilisé pour la pertinence.
cartItems	array	Tableau structuré d'objets de ligne de panier. Utilisé pour la pertinence.
adsexperience	string	Passer "shoppable" lors du ciblage délibéré d'une expérience Shoppable Ads.

Placement position

Les placements en superposition s'affichent au-dessus de votre écran de confirmation dans un conteneur géré par Rokt, ne nécessitant aucun changement à la disposition existante de votre application. Pour insérer un placement en superposition, appelez SelectPlacements une fois que l'écran de confirmation est chargé :

Overlay placement

using mParticle.MAUI;

var attributes = new Dictionary<string, string>
{
  // 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"
};

MParticle.Instance.Rokt.SelectPlacements(
  identifier: "RoktExperience",
  attributes: attributes
);

Fonctions optionnelles

Fonction	Objectif
MParticle.Instance.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).

SelectPlacements with RoktConfig

using mParticle.MAUI;

var roktConfig = new RoktConfig()
{
  ColorMode = RoktConfig.RoktColorMode.Light
};

MParticle.Instance.Rokt.SelectPlacements(
  identifier: "RoktExperience",
  attributes: attributes,
  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 placements Rokt sont configurés de manière cohérente.

Events API

Le SDK+ fournit des événements de cycle de vie de placement via l'API MParticle.Instance.Rokt. Utilisez Events pour vous abonner par identifiant de placement et répondre à l'état de chargement, à la disponibilité, à l'interaction, à l'achèvement et aux échecs.

Subscribe to placement events

void HandleRoktEvent(object roktEvent)
{
  switch (roktEvent.GetType().Name)
  {
      case "RoktShowLoadingIndicator":
          Console.WriteLine("Rokt is loading...");
          break;
      case "RoktHideLoadingIndicator":
          Console.WriteLine("Rokt finished loading.");
          break;
      case "RoktPlacementReady":
          Console.WriteLine("Placement is ready.");
          break;
      case "RoktPlacementInteractive":
          Console.WriteLine("Placement is interactive.");
          break;
      case "RoktPositiveEngagement":
      case "RoktFirstPositiveEngagement":
          Console.WriteLine("User positively engaged.");
          break;
      case "RoktPlacementCompleted":
          Console.WriteLine("Placement completed.");
          break;
      case "RoktPlacementFailure":
          Console.WriteLine("Placement failed or no fill.");
          break;
      default:
          Console.WriteLine($"Unhandled event: {roktEvent.GetType().Name}");
          break;
  }
}

MParticle.Instance.Rokt.Events("RoktExperience", roktEvent =>
{
  HandleRoktEvent(roktEvent);
});

É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 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: Dictionary<string, string>
OpenUrl	Déclenché lorsque l'utilisateur appuie sur une URL configurée pour être envoyée à l'application partenaire.	placementId: string, url: string
PlacementClosed	Déclenché lorsqu'un placement est fermé par l'utilisateur.	placementId: string
PlacementCompleted	Déclenché lorsque la progression de l'offre atteint la fin et qu'il n'y a plus d'offres à afficher. Également déclenché lorsque le cache est atteint mais que le placement récupéré ne sera pas affiché car il a été précédemment rejeté.	placementId: string
PlacementFailure	Déclenché lorsqu'un placement n'a pas pu être affiché en raison d'une défaillance ou lorsqu'aucun placement n'est disponible à afficher.	placementId: string (optionnel)
CartItemInstantPurchase	Déclenché lorsque l'achat 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

7. Configure Apple Pay (iOS only)#

Apple Pay est requis pour les publicités Shoppable sur iOS. Si vous n'utilisez pas les publicités Shoppable, passez cette étape.

Avant d'enregistrer l'extension de paiement, créez un identifiant de marchand Apple Pay, configurez votre projet Xcode et générez un certificat de traitement des paiements.

Suivez les étapes dans Apple Pay — iOS setup, puis enregistrez RoktPaymentExtension dans votre code spécifique à la plateforme iOS. Dans un projet MAUI, placez ceci dans votre plateforme iOS AppDelegate.cs (ou dans MauiProgram.cs à l'intérieur d'un bloc #if __IOS__), et appelez-le après MParticle.Instance.Initialize(options) et avant tout appel SelectPlacements ou SelectShoppableAds:

Register RoktPaymentExtension (iOS only)

#if __IOS__
// iOS only: register after MParticle.Instance.Initialize(options),
// before SelectPlacements/SelectShoppableAds.
RoktPaymentExtension.Register("merchant.com.yourapp.rokt");
#endif

attention

RoktPaymentExtension doit être enregistré après MParticle.Instance.Initialize(options) et avant tout appel SelectPlacements ou SelectShoppableAds. Un enregistrement dans le désordre empêchera Apple Pay de fonctionner correctement.

remarque

L'API C# exacte pour l'enregistrement de RoktPaymentExtension peut varier selon la version de liaison MAUI. Si la signature de méthode ci-dessus ne correspond pas à votre package NuGet, vérifiez les notes de version de votre NuGet pour l'appel équivalent, ou contactez le support Rokt pour des conseils spécifiques à la liaison.

8. Appendix#

Annexe A : Configuration de l'application

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

var roktConfig = new RoktConfig()
{
    ColorMode = RoktConfig.RoktColorMode.Light
};

MParticle.Instance.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

var roktConfig = new RoktConfig()
{
    CacheConfig = new CacheConfig()
    {
        CacheDurationInSeconds = 1200,
        CacheAttributes = new Dictionary<string, string>()
        {
            { "email", "j.smith@example.com" },
            { "orderNumber", "123" }
        }
    }
};

MParticle.Instance.Rokt.SelectPlacements(
    identifier: "RoktExperience",
    attributes: attributes,
    config: roktConfig
);

EdgeToEdgeDisplay (Android uniquement)

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

Utilisez le bloc #if __ANDROID__ pour limiter ce paramètre à Android uniquement:

EdgeToEdgeDisplay (Android only)

#if __ANDROID__
var roktConfig = new RoktConfig()
{
    EdgeToEdgeDisplay = true
};

MParticle.Instance.Rokt.SelectPlacements(
    identifier: "RoktExperience",
    attributes: attributes,
    config: roktConfig
);
#endif

Appendice B : Support de l'interface utilisateur déclarative MAUI

Le SDK+ MAUI prend en charge à la fois la disposition basée sur XML (RoktEmbeddedView en XAML) et l'intégration de placement dans le code-behind. Pour les placements intégrés en XAML, enregistrez le RoktEmbeddedViewHandler dans MauiProgram.CreateMauiApp() (voir Placements intégrés) et référencez la vue par son x:Name dans votre code-behind.

Il n'existe pas d'équivalent de Jetpack Compose (RoktLayout) ou SwiftUI (MPRoktLayout) pour MAUI à ce jour. Utilisez le modèle XML + code-behind pour les placements intégrés.

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 d'API, mais fournit des API de rappel pour que vous puissiez le faire selon votre logique métier.

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

Le listener d'échec reçoit un objet errorResponse. Utilisez la propriété HttpCode pour déterminer la cause et décider si vous devez réessayer.

Gestion des erreurs Android

Sur Android, IdentityApi.UNKNOWN_ERROR indique un échec côté client (appareil hors ligne ou délai d'attente côté client) — réessayez la requête. HTTP 429 (IdentityApi.THROTTLE_ERROR) signifie que la requête a été limitée par le taux — réessayez avec un backoff exponentiel. D'autres codes d'erreur HTTP indiquent des problèmes d'implémentation ou de serveur qui doivent être enregistrés et examinés.

IDSync error handling (Android)

#if __ANDROID__
MParticle.Instance.Identity.Identify(identifyRequest)
    .AddFailureListener(errorResponse =>
    {
        if (errorResponse.HttpCode == IdentityApi.UnknownError)
        {
            // Device is likely offline or client-side timeout — retry the request
        }
        else if (errorResponse.HttpCode == 429)
        {
            // Throttled — retry with exponential backoff
        }
        else
        {
            // Log errorResponse.HttpCode and investigate — likely an implementation issue
        }
    })
    .AddSuccessListener(result =>
    {
        // Proceed with the identified user
    });
#endif

Gestion des erreurs iOS

Sur iOS, le listener d'échec de HttpCode correspond aux valeurs MPIdentityErrorResponseCode du SDK+ iOS natif. Les échecs de réseau (clientNoConnection, clientSideTimeout) doivent être réessayés immédiatement. Les erreurs de limitation (HTTP 429, correspondant à retry) doivent être réessayées avec un backoff. requestInProgress signifie qu'un autre appel IDSync est en cours — inspectez votre implémentation si cela se produit fréquemment, puis réessayez. Tous les autres codes indiquent généralement un problème d'implémentation ; inspectez les détails de errorResponse pour diagnostiquer.

IDSync error handling (iOS)

#if __IOS__
MParticle.Instance.Identity.Identify(identifyRequest)
    .AddFailureListener(errorResponse =>
    {
        if (errorResponse.HttpCode == IdentityApi.UnknownError)
        {
            // clientNoConnection or clientSideTimeout — device is offline or timed out, retry the request
        }
        else if (errorResponse.HttpCode == 429)
        {
            // Throttled (MPIdentityErrorResponseCodeRetry) — retry with exponential backoff
        }
        else if (errorResponse.HttpCode == (int)IdentityApi.RequestInProgress)
        {
            // Another IDSync request is already in progress — inspect implementation frequency, then retry
        }
        else
        {
            // Log errorResponse details and investigate — likely an implementation issue
        }
    })
    .AddSuccessListener(result =>
    {
        // Proceed with the identified user
    });
#endif

remarque

Les noms de constantes C# ci-dessus (IdentityApi.UnknownError, IdentityApi.RequestInProgress) reflètent la couche de liaison MAUI. Si votre version de NuGet expose des noms de constantes différents, ils correspondent aux valeurs sous-jacentes iOS MPIdentityErrorResponseCode :

Constante C# MAUI	iOS MPIdentityErrorResponseCode
IdentityApi.UnknownError	clientNoConnection, clientSideTimeout, ou unknown
IdentityApi.RequestInProgress	requestInProgress
HTTP 429	retry (limitation)

Appendice D : Transmission de l'ID de session du web au 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 MAUI 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.

Obtention de l'ID de session à partir du 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

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

Handle deep link and set sessionId

// Extract sessionId from the incoming deep link URI
// and set it on the Rokt SDK+ before calling SelectPlacements
var uri = new Uri(deepLinkUrl);
var query = System.Web.HttpUtility.ParseQueryString(uri.Query);
var sessionId = query["sessionId"];

if (!string.IsNullOrEmpty(sessionId))
{
    MParticle.Instance.Rokt.SetSessionId(sessionId);
}

// Proceed with your confirmation flow

Remarques

• Appelez SetSessionId avant SelectPlacements pour garantir l'utilisation de la session.
• Les chaînes vides sont ignorées et n'actualiseront pas la session.
• Encodez toujours l'ID de session en URL lorsque vous le transmettez en tant que paramètre de requête.

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

#if __ANDROID__
  MParticle.Instance.SetLogLevel(LogLevel.Verbose);
#elif __IOS__
  MParticle.Instance.SetLogLevel(LogLevel.Verbose);
#endif

2Build and run against a development key#

Construisez et exécutez votre application avec options.Environment = mParticle.MAUI.Environment.Development.

3Trigger SelectPlacements#

Déclenchez SelectPlacements sur l'écran où le placement doit se rendre 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 la console de l'appareil pour les erreurs du SDK Rokt. Problèmes courants :

Erreurs d'initialisation

• Confirmez que la clé et le secret à l'intérieur des blocs spécifiques à la plateforme correspondent aux valeurs fournies par votre gestionnaire de compte Rokt.
• Confirmez que MParticle.Instance.Initialize(options) s'exécute avant tout appel à SelectPlacements ou LogEvent.
• Confirmez que RoktKit.Register() est appelé avant MParticle.Instance.Initialize(options).

Erreurs d'identité

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

Placement non rendu

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