Aller au contenu principal

Guide d'intégration du SDK Android

Cette page explique comment implémenter le SDK Android pour Rokt Ads afin de fournir des expériences client plus pertinentes lors du paiement. 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 les pages configurées et en transmettant les données utilisateur et de transaction à Rokt pour la personnalisation et la mesure.

Votre représentant de compte dédié vous aidera à configurer votre compte pour le SDK Android. Ils vous fourniront à la fois la clé et le secret nécessaires pour initialiser le SDK ainsi que des ressources supplémentaires nécessaires 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.

1. Ajouter des dépendances​

Mettez à jour votre fichier gradle pour inclure les dépendances nécessaires pour le SDK :

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

2. Initialiser le SDK dans votre application​

Le SDK Android peut être configuré en utilisant un objet MParticleOptions et une classe builder dans le onCreate() de la classe Application. Le SDK mParticle Android doit être initialisé avant tout autre appel d'API SDK.

Assurez-vous de remplacer your-key et your-secret dans l'exemple de code ci-dessus par la clé et le secret fournis par votre représentant dédié de compte Rokt.

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

class YourApplicationClass : Application() {
    override fun onCreate() {
        super.onCreate()
        // Identifier l'utilisateur actuel :
        // Si vous n'avez pas l'adresse e-mail de l'utilisateur, vous pouvez passer une valeur nulle
        val identifyRequest = IdentityApiRequest.withEmptyUser()
        // Si vous utilisez une adresse e-mail non hachée, définissez-la dans 'email'.
        .email("j.smith@example.com")
        .build()
        // Si l'utilisateur est identifié avec son adresse e-mail, définissez des attributs utilisateur supplémentaires. 
        val identifyTask = BaseIdentityTask()
            .addSuccessListener { identityApiResult ->
                val user = identityApiResult.user
                user.setUserAttribute("example attribute key", "example attribute value")
            }
        val options: MParticleOptions = MParticleOptions.builder(this)
        .credentials(
            "your-key",   // La clé fournie par votre représentant de compte Rokt
            "your-secret" // Le secret fourni par votre représentant de compte Rokt
        ).environment(MParticle.Environment.Development)  // Spécifiez l'environnement de données avec environment:
        // Réglez-le sur .development si vous testez encore votre intégration.
        // Réglez-le sur .production si votre intégration est prête pour les données de production.
        // La valeur par défaut est .autoDetect qui tente de détecter l'environnement automatiquement
        .build()

        MParticle.start(options)
    }
}
attention

Assurez-vous de remplacer your-key et your-secret dans l'exemple de code ci-dessus par la clé et le secret fournis par votre représentant Rokt dédié.

Identifier l'utilisateur​

Lorsque le SDK est initialisé, il peut identifier l'utilisateur actuel afin que toutes les données collectées lui soient correctement attribuées et pour s'assurer qu'il voit les publicités les plus pertinentes en fonction de son comportement.

Le script d'initialisation du SDK inclut un objet appelé identifyRequest :

val identifyRequest = IdentityApiRequest.withEmptyUser()
.email("j.smith@example.com")
.build()

Dans identifyRequest, passez l'adresse e-mail de l'utilisateur dans le champ email.

Définir des attributs utilisateur supplémentaires​

Le script d'initialisation inclut une fonction de rappel qui vous permet de définir des attributs utilisateur supplémentaires pour l'utilisateur s'il est identifié avec succès avec son adresse e-mail :

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

3. Identifier l'utilisateur​

Chaque fois que l'utilisateur fournit son adresse e-mail après l'initialisation du SDK (par exemple, lorsqu'il se connecte ou effectue un achat), vous devez appeler la méthode identify pour transmettre son e-mail à Rokt. Cela garantit que les données sont correctement attribuées à l'utilisateur actuel.

3.1 Créer un identifyRequest​

Pour identifier l'utilisateur, commencez par créer un objet identifyRequest pour contenir l'adresse e-mail de l'utilisateur.

Si vous fournissez une adresse e-mail non hachée, utilisez :

val identifyRequest = IdentityApiRequest.withEmptyUser()
    .email("j.smith@example.com")
    .build()

3.2 Définir des attributs utilisateur supplémentaires​

Ensuite, vous avez la possibilité de définir des attributs utilisateur supplémentaires lors de l'identification d'un utilisateur en créant une fonction de rappel (callback). Si la identifyRequest réussit, alors les attributs utilisateur que vous définissez avec setUserAttribute sont attribués à l'utilisateur.

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

3.3 Appeler la méthode identify​

Enfin, après avoir créé votre identifyRequest et votre identityCallback, pour définir des attributs supplémentaires, appelez la méthode identify, en passant les objets identifyRequest et identityCallback que vous venez de créer :

MParticle.getInstance()?.Identity()?.identify(identifyRequest)

Par exemple, pour identifier un utilisateur nommé Jane Smith avec l'adresse e-mail j.smith@example.com (et vous n'avez pas besoin de hacher leur adresse e-mail), vous utiliseriez :

val identifyRequest = IdentityApiRequest.withEmptyUser()
    .email("j.smith@example.com")
    .build()

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

MParticle.getInstance()?.Identity()?.identify(identifyRequest)

4. 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é dans votre application immédiatement après l'initialisation du SDK Rokt, et avant d'enregistrer un événement.

import com.mparticle.MParticle

// 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.
val currentUser = MParticle.getInstance()?.Identity()?.currentUser

// 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("firstname", "John")
currentUser?.setUserAttribute("lastname", "Doe")
// Les numéros de téléphone peuvent être formatés soit comme '1234567890', soit comme '+1 (234) 567-8901'
currentUser?.setUserAttribute("mobile", "3125551515")
currentUser?.setUserAttribute("age", "33")
currentUser?.setUserAttribute("gender", "M")
currentUser?.setUserAttribute("city", "Brooklyn")
currentUser?.setUserAttribute("state", "NY")
currentUser?.setUserAttribute("zip", "123456")
currentUser?.setUserAttribute("dob", "yyyymmdd")
currentUser?.setUserAttribute("title", "Mr")
currentUser?.setUserAttribute("language", "en")
currentUser?.setUserAttribute("value", "52.25")
currentUser?.setUserAttribute("predictedltv", "136.23")

// Vous pouvez créer un attribut utilisateur pour contenir une liste de valeurs
val attributeList = ArrayList<String>()
attributeList.add("documentary")
attributeList.add("comedy")
attributeList.add("romance")
attributeList.add("drama")
currentUser?.setUserAttributeList("favorite-genres", 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("attribute-to-remove")

5. Capturer 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 MParticle.getInstance().logScreen() dès que l'écran se charge, en passant le nom de l'écran sous forme de chaîne de caractères et une table 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 com.mparticle.MParticle

val screenInfo = HashMap<String, String>()
screenInfo["rating"] = "5"
screenInfo["property_type"] = "hotel"

MParticle.getInstance()?.logScreen("Details", screenInfo)

6. Suivre les conversions​

Pour suivre une conversion, exécutez l'extrait de code suivant sur la page la plus appropriée qui se charge après qu'un client a converti, comme une page de confirmation d'achat ou de remerciement.

Lorsque vous collez l'extrait de code sur votre site, assurez-vous de :

  1. Remplacer les attributs d'utilisateur d'exemple dans les appels setUserAttribute par les valeurs réelles pour votre utilisateur ou client. Rokt recommande de définir au moins les attributs d'utilisateur suivants :
    • firstname
    • lastname
    • zipcode
    • mobile
  2. Remplacer les attributs d'événement de conversion d'exemple par les valeurs réelles de votre événement de conversion.

Lors de l'enregistrement d'un événement de conversion, vous devez inclure autant d'attributs d'utilisateur et d'attributs d'événement que possible pour améliorer la capacité de Rokt à optimiser vos campagnes.

MParticleUser currentUser = MParticle.getInstance().Identity().getCurrentUser();
currentUser.setUserAttribute("firstname", "John");
currentUser.setUserAttribute("lastname", "Doe");
currentUser.setUserAttribute("mobile", "3125551515");
currentUser.setUserAttribute("zip", "98103");

val customAttributes = mapOf(
    "conversiontype" to "signup",   // type de conversion
    "confirmationref" to "54321",   // ID de transaction / ID de commande
    "amount" to "",                 // Montant de la transaction ex. 300.5
    "currency" to "",               // Devise de la transaction ex. USD
    // Vous pouvez suivre vos propres attributs d'événements personnalisés !
    "CUSTOM_EVENT_ATTRIBUTE_NAME" to "CUSTOM_EVENT_ATTRIBUTE_VALUE"
)

val event = MPEvent.Builder("conversion", MParticle.EventType.Transaction)
    .customAttributes(customAttributes)
    .build()

MParticle.getInstance()?.logEvent(event)

Annexe​

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 pages 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 utilisateur 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
val customAttributes = mapOf(
"category" to "Destination Intro",
"title" to "Paris",
)

val event = MPEvent.Builder("Video Watched", EventType.Navigation)
.customAttributes(customAttributes)
.build()

MParticle.getInstance()?.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 com.mparticle.commerce.CommerceEvent
import com.mparticle.commerce.Product
import com.mparticle.commerce.TransactionAttributes

// 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
val customAttributes = mutableMapOf<String, String>()
customAttributes["ocean-view"] = "true"
customAttributes["balcony"] = "false"

val product = Product.Builder("Double Room - Econ Rate", "econ-1", 100.00)
    .quantity(4.0)
    // Inclure la carte des attributs personnalisés créée ci-dessus
    .customAttributes(customAttributes)
    .build()

// 2. Résumer la transaction

val attributes = TransactionAttributes("foo-transaction-id")
    .setRevenue(430.00)
    .setTax(30.00)

// 3. Enregistrer l'événement d'achat

val event = CommerceEvent.Builder(Product.PURCHASE, product)
    .transactionAttributes(attributes)
    // Les 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
    .customAttributes(mapOf("sale" to "true", "phone-booking" to "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)
    .build()

MParticle.getInstance()?.logEvent(event)
Cet article vous a-t-il été utile ?
Last updated Oct 29, 2025