Aller au contenu principal

Guide d'Intégration du SDK Flutter

Cette page explique comment implémenter le SDK Flutter pour Rokt Ecommerce afin de fournir des expériences client plus pertinentes lors du passage en caisse. Le SDK vous permet de déclencher et de suivre ces expériences (comme l'affichage d'offres sur les pages de confirmation) en s'activant sur des pages configurées et en transmettant les données utilisateur et transactionnelles à Rokt pour la personnalisation et la mesure.

Votre représentant de compte dédié vous aidera à configurer votre compte pour les plateformes que vous ciblez avec votre application Flutter. Ils vous fourniront à la fois la clé (iOS/Android/Web) et le secret (iOS/Android) nécessaires pour initialiser le SDK ainsi que des ressources supplémentaires pour rendre les expériences les plus pertinentes pour vos clients.

remarque

Ces instructions nécessitent des ressources de développement pour être complétées. Si vous avez besoin d'une assistance supplémentaire, veuillez contacter votre gestionnaire de compte Rokt. Les boutiques Shopify peuvent configurer un emplacement Rokt en quelques secondes en utilisant l'application Rokt Ecommerce — aucun codage nécessaire !

1. Configuration de Flutter​

Ajoutez le SDK Flutter comme dépendance à votre application Flutter :

flutter pub add mparticle_flutter_sdk

Après avoir ajouté la dépendance du SDK Rokt Flutter à votre application, les lignes suivantes (ou similaires) sont ajoutées au fichier pubspec.yaml de votre package :

dependencies:
    mparticle_flutter_sdk: ^1.1.0

Importez le package dans votre code Dart et obtenez une instance de mParticle :

import 'package:mparticle_flutter_sdk/mparticle_flutter_sdk.dart';

MparticleFlutterSdk? mpInstance = await MparticleFlutterSdk.getInstance();

Après avoir installé le plugin Dart, continuez à intégrer le SDK Rokt dans votre application mobile ou site web en suivant les étapes ci-dessous. Assurez-vous d'inclure la clé et le secret fournis par votre gestionnaire de compte là où c'est nécessaire, sinon vous verrez des erreurs dans vos journaux lors du lancement de votre application ou site.

1.1. Ajouter le SDK Rokt à votre application iOS​

En utilisant soit SPM soit CocoaPods, incluez le SDK Rokt dans votre application :

CocoaPods​

Pour intégrer le SDK en utilisant CocoaPods, spécifiez-le dans votre Podfile avec :

ios/Podfile
pod 'mParticle-Apple-SDK', '~> 8.0'
pod 'mParticle-Rokt','~> 8.0'

SPM​

Pour intégrer le SDK en utilisant Swift Package Manager :

  1. Ouvrez votre projet dans Xcode et allez à l'onglet "Package Dependencies".
  2. Cliquez sur le bouton + sous la liste des Packages.
  3. Entrez l'URL du dépôt https://github.com/mParticle/mparticle-apple-sdk dans la boîte de recherche en haut à droite, choisissez mparticle-apple-sdk dans la liste des packages, et changez "Dependency Rule" en "Up to Next Major Version".
  4. Cliquez sur le bouton "Add Package" en bas à droite, et choisissez le "Package Product" appelé mParticle-Apple-SDK. Si vous souhaitez utiliser une version du SDK qui n'inclut pas le support de suivi de localisation, choisissez mParticle-Apple-SDK-NoLocation.
  5. Répétez les étapes 3 et 4 pour l'URL du dépôt Rokt Kit https://github.com/mparticle-integrations/mparticle-apple-integration-rokt.git.
    • Si vous choisissez le package product mParticle-Apple-SDK-NoLocation, vous devrez importer le SDK en utilisant import mParticle_Apple_SDK_NoLocation au lieu de import mParticle_Apple_SDK.

1.2. Initialiser le SDK Rokt​

Pour initialiser le SDK, insérez l'extrait d'initialisation suivant dans votre fichier AppDelegate :

attention
  • Assurez-vous de remplacer your-key et your-secret par la clé et le secret fournis par votre équipe dédiée Rokt.
import mParticle_Apple_SDK

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

Configuration supplémentaire​

Pour plus d'aide, consultez le Guide d'intégration SDK iOS.

2. Suivre les attributs utilisateur​

Vous pouvez utiliser le SDK Rokt pour collecter des attributs utilisateur séparément des événements. Les attributs utilisateur sont distincts des attributs personnalisés lors du suivi des événements. Le SDK associera tous les attributs utilisateur collectés dans une session donnée aux événements déclenchés dans la même session.

Pour collecter des attributs utilisateur, le code suivant doit être exécuté immédiatement après l'initialisation du SDK Rokt avant d'enregistrer un événement.

import 'package:mparticle_flutter_sdk/mparticle_flutter_sdk.dart';

// Récupérez l'utilisateur actuel. Cela ne réussira que si vous avez identifié l'utilisateur lors de l'initialisation du SDK ou en appelant la méthode identify.
var currentUser = await mpInstance?.getCurrentUser();

// Une fois que vous avez correctement défini l'utilisateur actuel sur `currentUser`, vous pouvez définir des attributs utilisateur avec :
currentUser?.setUserAttribute('custom-attribute-name', 'custom-attribute-value');
// Remarque : tous les attributs utilisateur (y compris les attributs de liste et les balises) doivent avoir des noms distincts.

// Rokt recommande de définir autant que possible les attributs utilisateur suivants :
currentUser?.setUserAttribute(key: 'firstname', value: 'John');
currentUser?.setUserAttribute(key: 'lastname', value: 'Doe');
// Les numéros de téléphone peuvent être formatés soit comme '1234567890', soit comme '+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: 'value', value: '52.25');
currentUser?.setUserAttribute(key: 'predictedltv', value: '136.23');

// Vous pouvez créer un attribut utilisateur pour contenir une liste de valeurs
var attributeList = <String>[];
attributeList.add('documentary');
attributeList.add('comedy');
attributeList.add('romance');
attributeList.add('drama');
currentUser?.setUserAttributeArray(key: 'favorite-genres', value: attributeList);

// Pour supprimer un attribut utilisateur, appelez removeUserAttribute et passez le nom de l'attribut. Tous les attributs utilisateur partagent le même espace de clés.
currentUser?.removeUserAttribute(key: 'attribute-to-remove');

3. Capturer les événements de l'entonnoir​

Le SDK Rokt vous permet de mettre en œuvre le suivi des événements pour collecter des données décrivant le parcours de vos utilisateurs à travers votre application. Vous pouvez ensuite utiliser ces données pour optimiser l'expérience de vos utilisateurs.

Il existe trois types principaux d'événements que vous pouvez enregistrer avec le SDK :

  • Événements de vue d'écran (Screen View Events) : Ce sont des événements que vous pouvez déclencher lorsqu'un écran de votre application est chargé.
  • Événements personnalisés (Custom Events) : Ce sont des événements libres que vous créez pour suivre des informations spécifiques à votre application.
  • Événements commerciaux (Commerce Events) : Ce sont des événements spécifiques au commerce électronique qui peuvent décrire les différentes étapes de l'expérience d'achat, y compris l'ajout d'articles à un panier et la réalisation d'un achat final.

Lors de la première intégration avec le SDK Rokt, commencez par implémenter le suivi des vues d'écran. Pour en savoir plus sur le suivi des événements personnalisés et commerciaux, consultez l'Annexe.

Suivre les vues d'écran​

L'un des types d'événements les plus basiques que vous pouvez suivre est la vue d'écran. Pour enregistrer une vue d'écran, appelez la méthode mpInstance?.logScreenEvent() dès que l'écran se charge, en passant le nom de l'écran sous forme de chaîne de caractères et une carte de hachage optionnelle contenant des attributs descriptifs.

Le nom que vous passez doit être l'un d'un ensemble limité d'écrans, comme 'homepage' ou 'product detail page'.

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

var screenInfo = {
    'rating': '5',
    'property_type': 'hotel'
};

ScreenEvent screenEvent = ScreenEvent(eventName: 'Details')
  ..customAttributes = screenInfo;
mpInstance?.logScreenEvent(screenEvent);

#```## 4. Afficher un Placement

La principale valeur du SDK Rokt est débloquée grâce à la méthode selectPlacements, qui sert un placement (ou mise en page) hyper-pertinent pour vos clients en fonction des attributs que vous fournissez.

Une fois l'intégration Rokt initialisée, vous pouvez appeler la méthode selectPlacements depuis la page où votre mise en page sera rendue. Elle doit être appelée le plus tôt possible, et une fois que tous les attributs requis sont disponibles, pour garantir la meilleure expérience pour vos utilisateurs.

Lors de l'appel de selectPlacements, vous devez fournir au moins les attributs email, firstname, lastname, billingzipcode et confirmationref.

final attributes = {
    "email": "j.smith@example.com",
    "firstname": "Jenny",
    "lastname": "Smith",
    "mobile": "(555)867-5309",
    "postcode": "90210",
    "country": "US"
};

// Si vous souhaitez utiliser des polices personnalisées pour votre placement, créez une map fontTypefaces
final fontTypefaces = {"Arial-Bold": "fonts/Arial-Bold.ttf"};

// Vous pouvez également vouloir passer des paramètres optionnels tels que `RoktConfig` qui vous permettront de personnaliser l'interface utilisateur du placement, principalement pour savoir si l'application est en mode sombre ou clair. Des paramètres optionnels supplémentaires tels que les vues intégrées et les événements sont montrés plus bas.
final roktConfig = RoktConfig(
    colorMode: ColorMode.light
);

mpInstance?.rokt.selectPlacements(
    identifier: "RoktExperience",
    attributes: attributes,
    fontFilePathMap: fontTypefaces,
    roktConfig: roktConfig
);

Fonctions optionnelles​

Emplacements intégrés​

Les emplacements intégrés partagent toutes les mêmes recommandations et exigences que les emplacements en superposition ci-dessus, mais vous permettent d'intégrer les vues d'emplacement dans votre interface utilisateur (UI).

RoktLayout dispose d'un rappel pour notifier lorsque le widget est créé, ce qui pourrait être utilisé.

import 'package:mparticle_flutter_sdk/mparticle_flutter_sdk.dart';

const RoktLayout(
    placeholderName: "RoktEmbedded1",
    onLayoutCreated: () {
        // Layout créé
    }
);

Événements​

Le SDK fournit également les événements sur chaque page sous forme de flux via le MPRoktEvents EventChannel.

final EventChannel roktEventChannel = EventChannel('MPRoktEvents');
roktEventChannel.receiveBroadcastStream().listen((dynamic event) {
    debugPrint("rokt_event: _receiveRoktEvent $event ");
});
ÉvénementDescriptionParamètres
ShowLoadingIndicatorDéclenché avant que le SDK appelle le backend Rokt
HideLoadingIndicatorDéclenché lorsque le SDK reçoit un succès ou un échec du backend Rokt
OfferEngagementDéclenché lorsque l'utilisateur interagit avec l'offreplacementId: String
PositiveEngagementDéclenché lorsque l'utilisateur interagit positivement avec l'offreplacementId: String
FirstPositiveEngagementDéclenché lorsque l'utilisateur interagit positivement avec l'offre pour la première foisplacementId: String, fulfillmentAttributes: FulfillmentAttributes
PlacementInteractiveDéclenché lorsqu'un emplacement a été rendu et est interactifplacementId: String
PlacementReadyDéclenché lorsqu'un emplacement est prêt à être affiché mais n'a pas encore rendu de contenuplacementId: String
PlacementClosedDéclenché lorsque l'utilisateur ferme un emplacementplacementId: String
PlacementCompletedDé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 l'emplacement récupéré ne sera pas affiché car il a été précédemment rejeté		placementId: String
PlacementFailureDéclenché lorsqu'un emplacement n'a pas pu être affiché en raison d'une défaillance ou lorsqu'aucun emplacement n'est disponible à afficherplacementId: String (optionnel)
OpenUrlDéclenché lorsque l'utilisateur appuie sur une URL qui est configurée pour être envoyée à l'application partenaireplacementId: String, url: String

Annexe​

Utilisation des configurations d'application​

Les applications peuvent désormais transmettre les paramètres de configuration depuis leur propre environnement d'application. Cela permet au SDK Rokt d'utiliser les configurations personnalisées de l'application au lieu de se fier uniquement aux paramètres par défaut du système.

Objet ColorMode​
ValeurDescription
lightL'application est en mode clair
darkL'application est en mode sombre
systemL'application utilise le mode couleur système par défaut
Objet CacheConfig​
remarque

CacheConfig est pertinent uniquement pour les intégrations mobiles et peut être ignoré pour le web.

ParamètreDescription
cacheDurationDuré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 et la valeur par défaut (si la valeur n'est pas fournie ou invalide) est de 90 minutes.
cacheAttributesAttributs optionnels à utiliser comme clé de cache. Si null, tous les attributs envoyés dans selectPlacements seront utilisés comme clé de cache.
final roktConfig = RoktConfig(
    cacheConfig: CacheConfig(
        cacheDurationInSeconds: 100,
        cacheAttributes: attributes
    )
);

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

Suivre des événements personnalisés​

Après avoir implémenté les placements et le suivi des vues d'écran en suivant les instructions ci-dessus, vous pouvez vouloir implémenter un suivi d'événements supplémentaire.

Vous pouvez définir et suivre des événements personnalisés en utilisant l'objet MPEvent.Builder et en passant le nom de l'événement, le type d'événement, et une carte d'attributs personnalisés.

Les types d'événements personnalisés pris en charge pour Kotlin et Java sont :

  • Navigation - Suivre les flux de navigation des utilisateurs et les transitions de page au sein de votre application
  • Location - Enregistrer les interactions et mouvements basés sur la localisation de l'utilisateur
  • Search - Capturer les requêtes de recherche et les actions des utilisateurs liées à la recherche
  • Transaction - Consigner les transactions financières et les activités liées aux achats
  • UserContent - Suivre le contenu généré par les utilisateurs comme les avis, commentaires ou publications
  • UserPreference - Enregistrer les paramètres utilisateur, préférences et choix de personnalisation
  • Social - Capturer les interactions sur les réseaux sociaux et les activités de partage
import 'package:mparticle_flutter_sdk/events/event_type.dart';
import 'package:mparticle_flutter_sdk/events/mp_event.dart';

final customAttributes = {
  'category': 'Destination Intro',
  'title': 'Paris',
};

MPEvent event = MPEvent(
    eventName: 'Video Watched',
    eventType: EventType.Navigation)
    ..customAttributes = customAttributes
mpInstance?.logEvent(event);

Suivre les événements commerciaux​

Le suivi d'un événement commercial nécessite trois étapes :

  1. Définir le ou les produits qui sont achetés
  2. Créer un objet pour contenir un résumé de la transaction
  3. Enregistrer l'événement, y compris votre définition de produit et le résumé de la transaction
import 'package:mparticle_flutter_sdk/events/commerce_event.dart';
import 'package:mparticle_flutter_sdk/events/product.dart';
import 'package:mparticle_flutter_sdk/events/product_action_type.dart';
import 'package:mparticle_flutter_sdk/events/transaction_attributes.dart';

// 1. Créer les produits

// Créer une carte optionnelle d'attributs personnalisés pour le produit sous forme de paires clé/valeur de chaînes
final customAttributes = {
  'ocean-view': 'true',
  'balcony': 'false',
};

Product product = Product(
    name: 'Double Room - Econ Rate',
    sku: 'econ-1',
    price: 100.00,
    product.quantity = 4;
);

// Inclure la carte des attributs personnalisés créée ci-dessus
product.attributes = customAttributes;

// 2. Résumer la transaction
final TransactionAttributes attributes =
    TransactionAttributes(
        transactionID: '12345',
        revenue: 430.00,
        tax: 30.00
    );

// 3. Enregistrer l'événement d'achat
CommerceEvent event = CommerceEvent.withProduct(
    productActionType: ProductActionType.Purchase,
    product: product
);
event.transactionAttributes = attributes;

// Des attributs personnalisés optionnels pour l'événement d'achat peuvent être ajoutés sous forme de carte de paires clé/valeur de chaînes
event.customAttributes = {"sale": "true", "phone-booking": "true"};

// Vous pouvez également créer une carte qui est ensuite transmise à la méthode du constructeur customAttributes. Par exemple :
//    val customTransactionAttributes = mutableMapOf<String, String>()
//    customTransactionAttributes["sale"] = "true"
//    customTransactionAttributes["phone-booking"] = "true"
//    .customAttributes(customTransactionAttributes)
mpInstance?.logCommerceEvent(event);
Cet article vous a-t-il été utile ?
Last updated Oct 29, 2025