Last updated

Guide d'Intégration du SDK Android

Cette page explique comment implémenter le SDK Android pour Rokt Ecommerce afin de proposer des expériences clients plus pertinentes lors du paiement. Le SDK vous permet de déclencher et de suivre ces expériences (comme afficher des offres sur les pages de confirmation) en activant sur des 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 aide supplémentaire, veuillez contacter votre responsable de compte Rokt. Les boutiques Shopify peuvent configurer un emplacement Rokt en quelques secondes à l'aide de l'application Rokt Ecommerce — aucun codage nécessaire !

1. Ajouter des dépendances

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

build.gradle.kts
build.gradle

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

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

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 Android mParticle doit être initialisé avant tout autre appel à l'API du SDK.

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 de compte Rokt dédié.

Kotlin
Java

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

import com.mparticle.MParticle;
import com.mparticle.MParticleOptions;
public class YourApplicationClass extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        MParticleOptions options = MParticleOptions.builder(this)
        .configuration(kitOptions)
        .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.Production).build(); // 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
        // Identifiez l'utilisateur actuel :
        IdentityApiRequest identifyRequest = IdentityApiRequest.withEmptyUser()
        // Si vous n'avez pas l'adresse e-mail de l'utilisateur, vous pouvez passer une valeur nulle
        .email("j.smith@example.com").build();
        // Si l'utilisateur est identifié avec son adresse e-mail, définissez des attributs utilisateur supplémentaires.
        BaseIdentityTask identifyTask = new BaseIdentityTask()
        .addSuccessListener(new TaskSuccessListener() {
            @Override
            public void onSuccess(IdentityApiResult identityApiResult) {
                MParticleUser user = identityApiResult.getUser();
                user.setUserAttribute("exemple de clé d'attribut", "exemple de valeur d'attribut");
            }
        });
     
        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 de compte 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:

Kotlin
Java

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

IdentityApiRequest 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 supplémentaires pour l'utilisateur

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

Kotlin
Java

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

BaseIdentityTask identifyTask = new BaseIdentityTask()
.addSuccessListener(new TaskSuccessListener() {
    @Override
    public void onSuccess(IdentityApiResult identityApiResult) {
        MParticleUser user = identityApiResult.getUser();
        user.setUserAttribute("example attribute key", "example attribute value");
    }
});

Initialisation avec des Polices

Au lieu de ou en plus de fournir vos polices désirées sur One Platform, vous pouvez choisir d'utiliser les polices déjà intégrées à votre application. Cela présente l'avantage d'éliminer la possibilité que les polices soient téléchargées au moment de l'initialisation, réduisant ainsi l'utilisation du réseau et les risques d'erreurs de téléchargement. Vous pouvez choisir d'utiliser soit les ressources de polices situées dans le répertoire assets de votre application, soit de passer vos propres objets Typeface.

Utilisation des Polices dans Assets

Vous pouvez utiliser les polices stockées dans le répertoire assets de votre application. Pour cela, vous pouvez passer une map à la méthode init qui associe les noms postscript des polices au chemin d'accès dans le répertoire d'assets (où le répertoire d'assets est le répertoire racine). Les noms postscript devraient correspondre à ceux utilisés dans votre mise en page, veuillez vérifier avec votre gestionnaire de compte si vous n'êtes pas sûr.

Java
Kotlin

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

class YourApplication : Application() {
    override fun onCreate() {
        ...
        val options: MParticleOptions = MParticleOptions.builder(this)
            .credentials(
                "your-key",   // La clé fournie par votre représentant Rokt
                "your-secret" // Le secret fourni par votre représentant Rokt
            ).environment(MParticle.Environment.Development)  // Spécifiez l'environnement des données avec environment:
            .roktOptions(RoktOptions(fontFilePathMap = mapOf("Arial-Bold" to "fonts/arialbold.otf")))
            .build()
        MParticle.start(options)
        ...
    }
}

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

public class YourApplication extends Application {
    @Override
    public void onCreate() {
        ...
        Map<String, String> fontFilePathMap = new HashMap<>();
        fontFilePathMap.put("Arial-Bold", "fonts/arialbold.otf");
        
        MParticleOptions options = MParticleOptions.builder(this)
            .credentials(
                "your-key",   // La clé fournie par votre représentant Rokt
"votre-secret" // Le secret fourni par votre représentant de compte Rokt
            )
            .environment(MParticle.Environment.Development)  // Spécifiez l'environnement des données avec environment:
            .roktOptions(new RoktOptions(fontFilePathMap))
            .build();
        
        MParticle.start(options);
        ...
    }
}

3. Identifier l'utilisateur

Dès que l'utilisateur fournit son adresse e-mail après l'initialisation du SDK (par exemple, lors de la connexion ou d'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 :

Kotlin
Java

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

IdentityApiRequest 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. Si la identifyRequest réussit, alors les attributs utilisateur que vous définissez avec setUserAttribute sont attribués à l'utilisateur.

Kotlin
Java

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

BaseIdentityTask identifyTask = new BaseIdentityTask()
.addSuccessListener(new TaskSuccessListener() {
    @Override
    public void onSuccess(IdentityApiResult identityApiResult) {
        MParticleUser user = identityApiResult.getUser();
        user.setUserAttribute("example attribute key", "example attribute value");
    }
});

3.3 Appelez 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 :

Kotlin
Java

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

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

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

Kotlin
Kotlin

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)

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

BaseIdentityTask identifyTask = new BaseIdentityTask()
.addSuccessListener(new TaskSuccessListener() {
    @Override
    public void onSuccess(IdentityApiResult identityApiResult) {
        MParticleUser user = identityApiResult.getUser();
        user.setUserAttribute("example attribute key", "example attribute value");
    }
});

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

3. Suivre les attributs utilisateur

Vous pouvez utiliser le SDK de 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 au cours d'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.

Kotlin
Java

import com.mparticle.MParticle

// Récupère 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 réussi à définir l'utilisateur actuel comme `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 tags) 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 sous la forme '1234567890', soit '+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 transmettez le nom de l'attribut. Tous les attributs utilisateur partagent le même espace de clé.
currentUser?.removeUserAttribute("attribute-to-remove")

import com.mparticle.MParticle;
import com.mparticle.MParticleUser;

// Récupérer 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.
MParticleUser currentUser = MParticle.getInstance().Identity().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("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
List<String> attributeList = new ArrayList<>();
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");

4. Capturer les événements du tunnel de conversion

Le SDK de Rokt vous permet de mettre en œuvre le suivi des événements pour collecter des données décrivant les 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 d'événements principaux que vous pouvez enregistrer avec le SDK :

Événements de vue d'écran : Ce sont des événements que vous pouvez déclencher lorsqu'un écran de votre application est chargé.
Événements personnalisés : Ce sont des événements libres que vous créez pour suivre des informations spécifiques à votre application.
Événements de commerce : 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 l'achat final.

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

Suivre les vues d'écran

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 transmettant le nom de l'écran sous forme de chaîne et une carte de hachage optionnelle contenant toutes les attributs descriptifs.

Le nom que vous transmettez doit être un des nombreux écrans limités, comme 'homepage' ou 'product detail page'.

Kotlin
Java

import com.mparticle.MParticle

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

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

import com.mparticle.MParticle;

HashMap<String, String> screenInfo = new HashMap<>();
screenInfo.put("rating", "5");
screenInfo.put("property_type", "hotel");
if (MParticle.getInstance() != null) {
    MParticle.getInstance().logScreen("Details", screenInfo);
}

5. Afficher un Placement

La principale valeur du SDK de Rokt est débloquée via la méthode selectPlacements, qui sert un emplacement (ou une 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. Cela devrait être appelé le plus tôt possible, et une fois que tous les attributs requis sont disponibles, pour garantir la meilleure expérience à vos utilisateurs.

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

Placements superposés

Kotlin
Java

val attributes = mapOf(
"email" to "j.smith@example.com",
"firstname" to "Jenny",
"lastname" to "Smith",
"billingzipcode" to "90210",
"confirmationref" to "54321",
)

// Si vous souhaitez utiliser des polices personnalisées pour votre emplacement, créez une carte de polices
val fontTypefaces: MutableMap<String, WeakReference<android.graphics.Typeface>> = HashMap<String, WeakReference<android.graphics.Typeface>>()
fontTypefaces["Arial-Bold"] = WeakReference<android.graphics.Typeface>(yourTypefaceObject)

// Vous pouvez également passer des paramètres optionnels tels que `RoktConfig` qui vous permettront de personnaliser l'interface utilisateur de l'emplacement, principalement pour savoir si l'application est en mode sombre ou clair. Les paramètres optionnels supplémentaires tels que les vues intégrées et les rappels sont indiqués ci-dessous.

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

MParticle.getInstance()?.Rokt()?.selectPlacements(
    identifier = "RoktExperience",
    attributes = attributes,
    fontTypefaces = fontTypefaces,
    config = roktConfig,
    embeddedViews = null, // placeholders optionnels (voir les emplacements intégrés ci-dessous)
    callbacks = null, // rappels optionnels (à définir comme approprié, voir ci-dessous)
)

Map<String, String> attributes = new HashMap<>();
attributes.put("email", "j.smith@example.com");
attributes.put("firstname", "Jenny");
attributes.put("lastname", "Smith");
attributes.put("billingzipcode", "90210");
attributes.put("confirmationref", "54321");
```javascript
// Carte des polices de caractères
Map<String, WeakReference<android.graphics.Typeface>> fontTypefaces = new HashMap<>();
fontTypefaces.put("Arial-Bold", new WeakReference<>(yourTypefaceObject)); // yourTypefaceObject doit être une instance valide de Typeface

RoktConfig roktConfig = new RoktConfig.Builder()
                .colorMode(RoktConfig.ColorMode.LIGHT)
                .build();

// Appeler Rokt selectPlacements
if (MParticle.getInstance() != null && MParticle.getInstance().Rokt() != null) {
    MParticle.getInstance().Rokt().selectPlacements(
        "RoktExperience", // identifiant
        attributes, // attributs
        null, // callbacks optionnels (définir selon le cas, voir ci-dessous)
        null, // placeHolders optionnels (voir Placements intégrés ci-dessous)
        fontTypefaces, // fontTypefaces
        roktConfig //roktConfig
    );
}

remarque

Si vous souhaitez mettre à jour le nom de la vue RoktExperience ou le nom du placeholder RoktEmbedded1 avec une valeur différente, contactez votre responsable de compte Rokt pour vous assurer que les placements Rokt sont configurés de manière cohérente.

Pour une liste complète des attributs pris en charge, voir Data Attributes.

Votre équipe Rokt dédiée configurera vos agencements de placement pour vous afin qu'ils correspondent à votre marque et au guide de style UX.

Fonctions facultatives

Fonction	Objectif
`Rokt.close()`	Utilisé pour fermer automatiquement les placements en superposition.

Placements intégrés

Les placements intégrés partagent toutes les mêmes recommandations et exigences que les placements en superposition mentionnés ci-dessus, mais vous permettent d'intégrer les vues de placement dans votre interface utilisateur. Nous utiliserons également cette section pour fournir des exemples des diverses fonctionnalités avancées permises par Rokt. La classe MpRoktEventCallback, qui est transmise à Rokt via le paramètre callbacks, vous permet de répondre à divers événements qui se produisent lors de la génération et de l'affichage d'un placement.

Si votre application Android nécessite une disposition intégrée, ajoutez le RoktEmbeddedView à votre fichier XML de disposition :

remarque

Ceci s'applique uniquement aux applications qui nécessitent des dispositions intégrées.

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout     
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MainActivity">

    <com.mparticle.rokt.RoktEmbeddedView
        android:id="@+id/roktEmbeddedView"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toTopOf="parent" />

</androidx.constraintlayout.widget.ConstraintLayout>

Nous vous conseillons de définir la hauteur du placement sur wrap_content afin que le placement puisse ajuster sa hauteur dynamiquement.

Kotlin
Java

import com.mparticle.rokt.RoktConfig
import com.mparticle.rokt.RoktEmbeddedView
import com.mparticle.MpRoktEventCallback
import com.mparticle.UnloadReasons

class ConfirmActivity : Activity() {
    val callbacks = object : MpRoktEventCallback {
        override fun onLoad() {
            // Callback optionnel pour lorsque le placement Rokt se charge
        }

        override fun onUnload(reason: UnloadReasons) {
```kotlin
// Rappel optionnel pour lorsque le placement Rokt se décharge
}

override fun onShouldShowLoadingIndicator() {
// Rappel optionnel pour afficher un indicateur de chargement
}

override fun onShouldHideLoadingIndicator() {
// Rappel optionnel pour masquer un indicateur de chargement
}
}

override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
val instance = MParticle.getInstance()
setContentView(R.layout.activity_main)
val attributes = hashMapOf(
Pair("email", "j.smith@example.com"),
Pair("firstname", "Jenny"),
Pair("lastname", "Smith"),
Pair("mobile", "(323) 867-5309"),
Pair("postcode", "90210"),
Pair("country", "US"),
)
val roktWidget = findViewById<RoktEmbeddedView>(R.id.roktEmbeddedView)
val placeHolders = mapOf(Pair("RoktEmbedded1", WeakReference(roktWidget)))
val fontTypefaces: MutableMap<String, WeakReference<android.graphics.Typeface>> = HashMap<String, WeakReference<android.graphics.Typeface>>()
fontTypefaces["Arial-Bold"] = WeakReference<android.graphics.Typeface>(yourTypefaceObject)

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

instance?.Rokt()?.selectPlacements(
identifier = "RoktExperience",
attributes = attributes,
fontTypefaces = fontTypefaces,
callbacks = callbacks,
embeddedViews = placeHolders,
config = roktConfig
)
}
}

import com.mparticle.kits.RoktKit;
import com.mparticle.rokt.RoktConfig;
import com.mparticle.MpRoktEventCallback;
import com.mparticle.UnloadReasons;

public class ConfirmActivity extends Activity {
private MpRoktEventCallback callbacks = new MpRoktEventCallback() {
@Override
public void onLoad() {
// Rappel optionnel pour lorsque le placement Rokt se charge
}

@Override
public void onUnload(UnloadReasons reason) {
// Rappel optionnel pour lorsque le placement Rokt se décharge
}

@Override
public void onShouldShowLoadingIndicator() {
// Rappel optionnel pour afficher un indicateur de chargement
```        }

        @Override
        public void onShouldHideLoadingIndicator() {
            // Rappel optionnel pour masquer un indicateur de chargement
        }
    };

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        MParticle instance = MParticle.getInstance();
        setContentView(R.layout.activity_main);

        Map<String, String> attributes = new HashMap<>();
        attributes.put("email", "j.smith@example.com");
        attributes.put("firstname", "Jenny");
        attributes.put("lastname", "Smith");
        attributes.put("mobile", "(323) 867-5309");
        attributes.put("postcode", "90210");
        attributes.put("country", "US");

        RoktEmbeddedView roktWidget = findViewById(R.id.roktEmbeddedView);
        Map<String, WeakReference<RoktEmbeddedView>> placeHolders = new HashMap<>();
        placeHolders.put("RoktEmbedded1", new WeakReference<>(roktWidget));

        Map<String, WeakReference<android.graphics.Typeface>> fontTypefaces = new HashMap<>();
        fontTypefaces.put("Arial-Bold", new WeakReference<>(yourTypefaceObject));

        RoktConfig roktConfig = new RoktConfig.Builder()
            .colorMode(RoktConfig.ColorMode.LIGHT)
            .build();

        if (instance != null && instance.Rokt() != null) {
            instance.Rokt().selectPlacements(
                "RoktExperience",
                attributes,
                callbacks,
                placeHolders,
                fontTypefaces,
                roktConfig
            );
        }
    }
}

API des événements globaux

Le SDK fournit le statut sous forme de flux via l'API Rokt.globalEvents. Les utilisateurs du SDK peuvent tirer parti du mécanisme Kotlin Flow pour consommer le statut.

import com.rokt.roktsdk.RoktEvent

// propriétaire : LifecycleOwner
owner.lifecycleScope.launch {
    Rokt.globalEvents().collect { event ->
        if (event is RoktEvent.InitComplete)
            Log.d("Rokt", "reçu initialisation complète $event")
    }
}

Événements

Le SDK fournit également les événements sur chaque page sous forme de flux via l'API MParticle.getInstance()?.Rokt()?.events. Les utilisateurs du SDK peuvent tirer parti du mécanisme Kotlin Flow pour consommer les événements produits par le SDK.

import com.mparticle.MParticle

// propriétaire : LifecycleOwner
owner.lifecycleScope.launch {
    owner.lifecycle.repeatOnLifecycle(Lifecycle.State.CREATED) {
        MParticle.getInstance()?.Rokt()?.events("RoktExperience").collect { roktEvent ->
            Log.d("RoktEvent", "Événement reçu $roktEvent")
        }
    }
}

É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
OfferEngagement	Déclenché lorsque l'utilisateur s'engage avec l'offre	placementId: String
PositiveEngagement	Déclenché lorsque l'utilisateur s'engage positivement avec l'offre	placementId: String
FirstPositiveEngagement	Déclenché lorsque l'utilisateur s'engage positivement avec l'offre pour la première fois	placementId: String, fulfillmentAttributes: FulfillmentAttributes
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
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 lorsque aucun placement n'est disponible à afficher	placementId: String (optionnel)
OpenUrl	Déclenché lorsque l'utilisateur appuie sur une URL configurée pour être envoyée à l'application partenaire	placementId: String, url: String
CartItemInstantPurchase	Déclenché lorsque l'achat d'un 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

Annexe

Débogage

Utilisez l'API Rokt.setLoggingEnabled(enable = true) pour activer les journaux de débogage du SDK Rokt.

Utilisation des configurations d'application

Les applications peuvent maintenant 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 défauts 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 système par défaut

EdgeToEdgeDisplay Boolean

Value	Description
true(default)	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

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

// si l'application prend en charge uniquement le mode clair et que l'affichage bord à bord est activé.
val roktConfig = RoktConfig.Builder()
    .edgeToEdgeDisplay(true)
    .build()

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

CacheConfig object

Parameter	Description
cacheDuration	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 et la valeur par défaut (si la valeur n'est pas fournie ou invalide) est de 90 minutes.
cacheAttributes	Attributs optionnels à utiliser comme clé de cache. Si null, tous les attributs envoyés dans `selectPlacements` seront utilisés comme clé de cache.

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

// pour mettre en cache l'expérience pendant 1200 secondes, en utilisant les attributs email et orderNumber comme clé de cache.
val roktConfig = RoktConfig.Builder()
    .cacheConfig(CacheConfig(
        cacheDurationInSeconds = 1200,
        cacheAttributes = mapOf("email" to "j.smith@example.com", "orderNumber" to "123")
    ))
    .build()

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

Suivre des événements personnalisés

Après avoir implémenté le suivi des emplacements et des vues d'écran en suivant les instructions ci-dessus, vous voudrez peut-être mettre en œuvre un suivi d'événements supplémentaires.

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, ainsi qu'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 des utilisateurs
Search - Capturer les requêtes de recherche et les actions utilisateur liées à la recherche
Transaction - Enregistrer les transactions financières et les activités liées aux achats
UserContent - Suivre le contenu généré par l'utilisateur tel que des critiques, 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

Kotlin
Java

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)

Map<String, String> customAttributes = new HashMap<>();
customAttributes.put("category", "Destination Intro");
customAttributes.put("title", "Paris");

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

if (MParticle.getInstance() != null) {
    MParticle.getInstance().logEvent(event);
}

Suivre les événements de commerce

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

Définir le ou les produits qui sont achetés
Créer un objet pour contenir un résumé de la transaction
Enregistrer l'événement, y compris votre définition de produit et le résumé de la transaction

Kotlin
Java

import com.mparticle.commerce.CommerceEvent
import com.mparticle.commerce.Product
import com.mparticle.commerce.TransactionAttributes

// 1. Créer les produits

// Créer une carte facultative d'attributs personnalisés pour le produit en tant que paires clé/valeur de chaînes
val customAttributes = mutableMapOf<String, String>()
customAttributes["ocean-view"] = "true"
customAttributes["balcony"] = "false"

val product = Product.Builder("Chambre Double - Tarif Éco", "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 facultatifs pour l'événement d'achat peuvent être ajoutés en tant que carte de paires clé/valeur
    .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)

import com.mparticle.commerce.CommerceEvent;
import com.mparticle.commerce.Product;
import com.mparticle.commerce.TransactionAttributes;

// 1. Créer les produits

// Créer une carte facultative d'attributs personnalisés pour le produit en tant que paires clé/valeur de chaînes
Map<String, String> productAttributes = new HashMap<>();
productAttributes.put("ocean-view", "true");
productAttributes.put("balcony", "false");

Product product = new Product.Builder("Chambre Double - Tarif Éco", "econ-1", 100.00)
.quantity(4.0)
.customAttributes(productAttributes)
.build();

// 2. Résumer la transaction

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

Map<String, String> customTransactionAttributes = new HashMap<>();
    customTransactionAttributes.put("sale", "true");
    customTransactionAttributes.put("phone-booking", "true");

    CommerceEvent event = new CommerceEvent.Builder(Product.PURCHASE, product)
    .transactionAttributes(attributes)
    .customAttributes(customTransactionAttributes)
    .build();

if (MParticle.getInstance() != null) {
    MParticle.getInstance().logEvent(event);
}

1. Ajouter des dépendances​

2. Initialiser le SDK dans votre application​

Identifier l'utilisateur​

Définir des attributs supplémentaires pour l'utilisateur​

Initialisation avec des Polices​

Utilisation des Polices dans Assets​

3. Identifier l'utilisateur​

3.1 Créer un identifyRequest​

3.2 Définir des attributs utilisateur supplémentaires​

3.3 Appelez la méthode identify​

3. Suivre les attributs utilisateur​

4. Capturer les événements du tunnel de conversion​

Suivre les vues d'écran​

5. Afficher un Placement​

Placements superposés​

Fonctions facultatives​

Placements intégrés​

API des événements globaux​

Événements​

Annexe​

Débogage​

Utilisation des configurations d'application​

Objet ColorMode​

EdgeToEdgeDisplay Boolean​

CacheConfig object​

Suivre des événements personnalisés​

Suivre les événements de commerce​

1. Ajouter des dépendances

2. Initialiser le SDK dans votre application

Identifier l'utilisateur

Définir des attributs supplémentaires pour l'utilisateur

Initialisation avec des Polices

Utilisation des Polices dans Assets

3. Identifier l'utilisateur

3.1 Créer un `identifyRequest`

3.2 Définir des attributs utilisateur supplémentaires

3.3 Appelez la méthode identify

3. Suivre les attributs utilisateur

4. Capturer les événements du tunnel de conversion

Suivre les vues d'écran

5. Afficher un Placement

Placements superposés

Fonctions facultatives

Placements intégrés

API des événements globaux

Événements

Annexe

Débogage

Utilisation des configurations d'application

Objet ColorMode

EdgeToEdgeDisplay Boolean

CacheConfig object

Suivre des événements personnalisés

Suivre les événements de commerce