Last updated 6 mars 2025

Android UX Helper

Rokt UX Helper est un projet open source qui vous aide à rendre de belles expériences client dans un environnement serveur à serveur. Vous pouvez trouver et contribuer au projet sur la page Github.

Ce document décrit le processus d'intégration de Rokt UX Helper dans votre application Android, qui fonctionne aux côtés de l'intégration Server-to-Server (S2S) pour offrir des expériences pertinentes à vos clients lors de leur passage à la caisse.

Système	Version
UX Helper	0.4.0
Version Android / Niveau API	5.0+ (Niveau API 21)
Gestionnaire de paquets	Maven / Gradle
Compose BOM	2024.09.02

Jetpack Compose

Guide d'installation

Dans votre fichier Gradle de module (niveau application) (généralement <project>/<app-module>/build.gradle.kts ou <project>/<app-module>/build.gradle), ajoutez la dépendance Rokt UX Helper.

Kotlin

build.gradle.kts

implementation("com.rokt:roktux:0.1.0")

Groovy

build.gradle

implementation 'com.rokt:roktux:0.1.0'

Initialiser RoktLayout

Ajoutez RoktLayout à votre vue Compose

// Récupérer la réponse d'expérience de votre serveur
val experienceResponse = viewModel.experienceResponse.collectAsState()

experienceResponse.value?.let { experienceResponse ->
    RoktLayout(
        experienceResponse = experienceResponse,
        location = "RoktEmbedded1",
        onUxEvent = { println("RoktEvent: UxEvent Reçu $it") },
        onPlatformEvent = { println("RoktEvent: onPlatformEvent reçu $it") },
        roktUxConfig = RoktUxConfig.builder()
            .imageHandlingStrategy(NetworkStrategy())
            .build(),
    )
}

Événements UX

Utilisez le gestionnaire onUXEvent pour recevoir des commentaires en temps réel sur les interactions des utilisateurs.

Au minimum, vous devez gérer quand un événement RoktUXEvent.OpenUrl est déclenché afin de pouvoir ouvrir le lien en utilisant l'exemple ci-dessous.

info

OpenUrl - onClose

Lors de la gestion d'un événement de type OpenUrl, il est crucial d'appeler le rappel onClose qui notifiera le RoktUXHelper d'exécuter une logique comme passer à l'offre suivante.

Kotlin

openUrlEvent.onClose.invoke(openUrlEvent.id)

Java

openUrlEvent.getOnClose().invoke(openUrlEvent.getId());

Kotlin

onUxEvent = { event ->
    println("RoktEvent: onUxEvent reçu $event")

    if (event is RoktUxEvent.OpenUrl) {
        val openUrlEvent = event as RoktUxEvent.OpenUrl
        when (openUrlEvent.type) {
            OpenLinks.Internally -> {
                // Ouvrir le navigateur AndroidX ou une fonctionnalité similaire pour garder l'utilisateur dans l'application
                val customTabsIntent = CustomTabsIntent.Builder().build()
                customTabsIntent.launchUrl(context, Uri.parse(openUrlEvent.url))

                openUrlEvent.onClose.invoke(openUrlEvent.id) // Cela doit être appelé lorsque l'utilisateur est prêt pour la prochaine offre
            }
            OpenLinks.Externally -> {
                // Ouvrir le navigateur externe permettant à l'utilisateur de quitter l'application
                val intent = Intent(Intent.ACTION_VIEW, Uri.parse(openUrlEvent.url))
                context.startActivity(intent)

                openUrlEvent.onClose.invoke(openUrlEvent.id) // Cela doit être appelé lorsque l'utilisateur est prêt pour la prochaine offre
            }
        }
    }
}

Java

roktUxEvent -> {
    // Gérer l'événement d'ouverture d'URL
    // Voici un exemple de comment ouvrir différents types d'URLs
    if (roktUxEvent instanceof RoktUxEvent.OpenUrl openUrlEvent) {
        if (openUrlEvent.getType() == OpenLinks.Internally) {
            // Ouvrir le navigateur AndroidX ou une fonctionnalité similaire pour garder l'utilisateur dans l'application
            CustomTabsIntent customTabsIntent = new CustomTabsIntent.Builder().build();
            customTabsIntent.launchUrl(context, Uri.parse(openUrlEvent.getUrl()));

            openUrlEvent.getOnClose().invoke(openUrlEvent.getId()); // Cela doit être appelé lorsque l'utilisateur est prêt pour la prochaine offre
        } else {
            // Ouvrir le navigateur externe permettant à l'utilisateur de quitter l'application
            final Intent intent = new Intent(Intent.ACTION_VIEW, Uri.parse(openUrlEvent.getUrl()));
            context.startActivity(intent);

            openUrlEvent.getOnClose().invoke(openUrlEvent.getId());  // Cela doit être appelé lorsque l'utilisateur est prêt pour la prochaine offre
        }
    }
    return null;
}

Tous les événements

### Événements UX

Événement	Description	Params
EngagementOffre	Déclenché lorsque l'utilisateur s'engage avec l'offre	layoutId: String
EngagementPositif	Déclenché lorsque l'utilisateur s'engage positivement avec l'offre	layoutId: String
LayoutInteractif	Déclenché lorsque un layout a été rendu et est interactable	layoutId: String
LayoutPrêt	Déclenché lorsque un layout est prêt à s'afficher mais n'a pas encore rendu de contenu	layoutId: String
LayoutFermé	Déclenché lorsque un layout est fermé par l'utilisateur	layoutId: String
LayoutComplété	Déclenché lorsque la progression de l'offre atteint la fin et qu'il n'y a plus d'offres disponibles à afficher	layoutId: String
LayoutÉchec	Déclenché lorsque un layout n'a pas pu être affiché en raison d'un échec	layoutId: String (optionnel)
OuvrirUrl	Déclenché lorsqu'un lien doit être ouvert	url: String, id: String, type: OpenURLType (interne/externe), onClose: (id: String) -> Unit, onError: (id: String, throwable: Throwable)

ÉvénementsDePlateforme

Les événements de plateforme sont une partie essentielle de l'intégration et ils doivent être envoyés à Rokt via votre backend. Pour faciliter l'intégration, l'objet est de type RoktPlatformEventsWrapper, implémente @Serializable et offre une fonction toJsonString.

Kotlin

onPlatformEvent = { events ->
    // Envoyer ces événements de plateforme à l'API Rokt incluant le corps de l'événement
}

Java

roktPlatformEvents -> {
    // Envoyer ces événements de plateforme à l'API Rokt incluant le corps de l'événement
    return null;
}

Vous pouvez trouver une liste complète des événements ici.

Optionnel : Configurations de l'application

Mode de couleur

Le mode de couleur vous permet de fixer le thème utilisé lors de l'affichage des mises en page Rokt. Par défaut, Rokt correspond au thème système actuel.

Kotlin

val config = RoktUxConfig.builder()
    .colorMode(ColorMode.DARK)
    .build()

Java

final RoktUxConfig build = new RoktUxConfig.builder()
    .colorMode(ColorMode.DARK)
    .build();

Objet RoktUxColorMode

Valeur	Description
LIGHT	L'application est en mode clair
DARK	L'application est en mode sombre
SYSTEM	L'application par défaut au mode couleur système

Chargeur d'images

Dans Rokt UX Helper, Coil est utilisé pour charger des images. UX Helper dispose de plusieurs chargeurs d'images intégrés que vous pouvez utiliser dans votre application. L'approche la plus simple et recommandée à mettre en œuvre est NetworkStrategy, cependant, selon votre bibliothèque de mise en réseau ou vos préférences, vous pouvez créer des stratégies de chargement d'images personnalisées.

Kotlin

val roktUxConfig = RoktUxConfig.builder()
    .imageHandlingStrategy(NetworkStrategy())
    .build()

Java

final roktUxConfig = new RoktUxConfig.builder()
    .imageHandlingStrategy(new NetworkStrategy())
    .build();

Polices

val fontFamily = remember {
        val robotoLight = Font(resId = R.font.roboto_light, weight = FontWeight.W100)
        val robotoItalic = Font(resId = R.font.roboto_italic, weight = FontWeight.W400)
        FontFamily(robotoLight, robotoItalic)
    }

RoktUxConfig.builder()
    .composeFontMap(mapOf("roboto" to fontFamily))
    .build()

XML

Guide d'installation

Dans votre fichier Gradle de module (niveau application) (généralement <project>/<app-module>/build.gradle.kts ou <project>/<app-module>/build.gradle), ajoutez la dépendance Rokt UX Helper.

Kotlin

build.gradle.kts

implementation("com.rokt:roktux:0.1.0")

Groovy

build.gradle

implementation 'com.rokt:roktux:0.1.0'

Initialiser RoktLayout

Pour commencer à utiliser le Rokt UX Helper, vous devez ajouter la mise en page à l'XML pertinent pour votre application. Dans l'exemple, nous utilisons RoktEmbedded1 pour indiquer quelle mise en page est chargée dans cette vue, cela doit correspondre à la configuration de votre page.

<com.rokt.roktux.RoktLayoutView
    android:id="@+id/roktLayoutView"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    app:location="RoktEmbedded1" />

Kotlin

val roktLayoutView: RoktLayoutView = findViewById(R.id.roktLayoutView)
val experienceResponse: String = // Récupérez la réponse d'expérience de votre serveur
val roktUxConfig = RoktUxConfig.builder()
            .build()

roktLayoutView.loadLayout(
    experienceResponse = experienceResponse,
    roktUxConfig,
    onUxEvent = { event ->
        // Gérer les événements UX ici
    },
    onPlatformEvent = { platformEvent ->
        // Envoyez ces événements de plateforme à l'API de Rokt
    },
)

Java

final RoktLayoutView roktLayoutView = findViewById(R.id.roktLayoutView);
final String experienceResponse = "";
final RoktUxConfig roktUxConfig = RoktUxConfig.builder()
            .build()

roktLayoutView.loadLayout(
    experienceResponse,
    roktUxConfig,
    roktUxEvent -> {
        // Gérer les événements UX ici
        return null;
    },
    roktPlatformEvent -> {
        // Envoyez ces événements de plateforme à l'API de Rokt
        return null;
    }
);

Événements UX

Utilisez le gestionnaire onUXEvent pour recevoir des commentaires en temps réel sur les interactions des utilisateurs.

Au minimum, vous devez gérer quand un événement RoktUXEvent.OpenUrl est déclenché afin de pouvoir ouvrir le lien en utilisant l'exemple ci-dessous.

info

OpenUrl - onClose

Lors de la gestion d'un événement de type OpenUrl, il est crucial d'appeler le rappel onClose qui notifiera le RoktUXHelper d'exécuter une logique comme passer à l'offre suivante.

Kotlin

openUrlEvent.onClose.invoke(openUrlEvent.id)

Java

openUrlEvent.getOnClose().invoke(openUrlEvent.getId());

Kotlin

onUxEvent = { event ->
    println("RoktEvent: onUxEvent reçu $event")

    if (event is RoktUxEvent.OpenUrl) {
        val openUrlEvent = event as RoktUxEvent.OpenUrl
        when (openUrlEvent.type) {
            OpenLinks.Internally -> {
                // Ouvrir le navigateur AndroidX ou une fonctionnalité similaire pour garder l'utilisateur dans l'application
                val customTabsIntent = CustomTabsIntent.Builder().build()
                customTabsIntent.launchUrl(context, Uri.parse(openUrlEvent.url))

                openUrlEvent.onClose.invoke(openUrlEvent.id) // Cela doit être appelé lorsque l'utilisateur est prêt pour la prochaine offre
            }
            OpenLinks.Externally -> {
                // Ouvrir le navigateur externe permettant à l'utilisateur de quitter l'application
                val intent = Intent(Intent.ACTION_VIEW, Uri.parse(openUrlEvent.url))
                context.startActivity(intent)

                openUrlEvent.onClose.invoke(openUrlEvent.id) // Cela doit être appelé lorsque l'utilisateur est prêt pour la prochaine offre
            }
        }
    }
}

Java

roktUxEvent -> {
    // Gérer l'événement d'ouverture d'URL
    // Voici un exemple de comment ouvrir différents types d'URLs
    if (roktUxEvent instanceof RoktUxEvent.OpenUrl openUrlEvent) {
        if (openUrlEvent.getType() == OpenLinks.Internally) {
            // Ouvrir le navigateur AndroidX ou une fonctionnalité similaire pour garder l'utilisateur dans l'application
            CustomTabsIntent customTabsIntent = new CustomTabsIntent.Builder().build();
            customTabsIntent.launchUrl(context, Uri.parse(openUrlEvent.getUrl()));

            openUrlEvent.getOnClose().invoke(openUrlEvent.getId()); // Cela doit être appelé lorsque l'utilisateur est prêt pour la prochaine offre
        } else {
            // Ouvrir le navigateur externe permettant à l'utilisateur de quitter l'application
            final Intent intent = new Intent(Intent.ACTION_VIEW, Uri.parse(openUrlEvent.getUrl()));
            context.startActivity(intent);

            openUrlEvent.getOnClose().invoke(openUrlEvent.getId());  // Cela doit être appelé lorsque l'utilisateur est prêt pour la prochaine offre
        }
    }
    return null;
}

Tous les événements

### Événements UX

Événement	Description	Params
EngagementOffre	Déclenché lorsque l'utilisateur s'engage avec l'offre	layoutId: String
EngagementPositif	Déclenché lorsque l'utilisateur s'engage positivement avec l'offre	layoutId: String
LayoutInteractif	Déclenché lorsque un layout a été rendu et est interactable	layoutId: String
LayoutPrêt	Déclenché lorsque un layout est prêt à s'afficher mais n'a pas encore rendu de contenu	layoutId: String
LayoutFermé	Déclenché lorsque un layout est fermé par l'utilisateur	layoutId: String
LayoutComplété	Déclenché lorsque la progression de l'offre atteint la fin et qu'il n'y a plus d'offres disponibles à afficher	layoutId: String
LayoutÉchec	Déclenché lorsque un layout n'a pas pu être affiché en raison d'un échec	layoutId: String (optionnel)
OuvrirUrl	Déclenché lorsqu'un lien doit être ouvert	url: String, id: String, type: OpenURLType (interne/externe), onClose: (id: String) -> Unit, onError: (id: String, throwable: Throwable)

ÉvénementsDePlateforme

Les événements de plateforme sont une partie essentielle de l'intégration et ils doivent être envoyés à Rokt via votre backend. Pour faciliter l'intégration, l'objet est de type RoktPlatformEventsWrapper, implémente @Serializable et offre une fonction toJsonString.

Kotlin

onPlatformEvent = { events ->
    // Envoyer ces événements de plateforme à l'API Rokt incluant le corps de l'événement
}

Java

roktPlatformEvents -> {
    // Envoyer ces événements de plateforme à l'API Rokt incluant le corps de l'événement
    return null;
}

Vous pouvez trouver une liste complète des événements ici.

Optionnel : Configurations de l'application

Mode de couleur

Le mode de couleur vous permet de fixer le thème utilisé lors de l'affichage des mises en page Rokt. Par défaut, Rokt correspond au thème système actuel.

Kotlin

val config = RoktUxConfig.builder()
    .colorMode(ColorMode.DARK)
    .build()

Java

final RoktUxConfig build = new RoktUxConfig.builder()
    .colorMode(ColorMode.DARK)
    .build();

Objet RoktUxColorMode

Valeur	Description
LIGHT	L'application est en mode clair
DARK	L'application est en mode sombre
SYSTEM	L'application par défaut au mode couleur système

Chargeur d'images

Dans Rokt UX Helper, Coil est utilisé pour charger des images. UX Helper dispose de plusieurs chargeurs d'images intégrés que vous pouvez utiliser dans votre application. L'approche la plus simple et recommandée à mettre en œuvre est NetworkStrategy, cependant, selon votre bibliothèque de mise en réseau ou vos préférences, vous pouvez créer des stratégies de chargement d'images personnalisées.

Kotlin

val roktUxConfig = RoktUxConfig.builder()
    .imageHandlingStrategy(NetworkStrategy())
    .build()

Java

final roktUxConfig = new RoktUxConfig.builder()
    .imageHandlingStrategy(new NetworkStrategy())
    .build();

Polices de caractères

Tout d'abord, vous devez ajouter vos fichiers de police, par exemple roboto_light.ttf, dans votre dossier de ressources Android, puis configurer UX Helper pour les utiliser avec RoktUxConfig. L'exemple ci-dessous concerne les polices configurées dans les ressources, cependant, nous supportons également les polices dans les assets avec AssetFontItem.

Kotlin

val robotoFonts: List<ResourceFontItem> = listOf(
    ResourceFontItem(R.font.roboto_light, FontItemWeight.W100, FontItemStyle.Normal),
    ResourceFontItem(R.font.roboto_light, FontItemWeight.W300, FontItemStyle.Normal),
    ResourceFontItem(R.font.roboto_italic, FontItemWeight.W400, FontItemStyle.Italic),
    ResourceFontItem(R.font.roboto_bold, FontItemWeight.W700, FontItemStyle.Normal),
    ResourceFontItem(R.font.roboto_black, FontItemWeight.W900, FontItemStyle.Normal),
    // Ajouter toute police pertinente
)

// Si vous avez plusieurs polices, créez-les ici et ajoutez-les à fontFamilyMap

val config = RoktUxConfig.builder()
    .xmlFontFamilyMap(mapOf("roboto" to robotoFonts))
    .build()

Java

final List<ResourceFontItem> fontItems = Arrays.asList(
    new ResourceFontItem(R.font.roboto_light, FontItemWeight.W100, FontItemStyle.Normal),
    new ResourceFontItem(R.font.roboto_light, FontItemWeight.W300, FontItemStyle.Normal),
    new ResourceFontItem(R.font.roboto_italic, FontItemWeight.W400, FontItemStyle.Italic),
    new ResourceFontItem(R.font.roboto_bold, FontItemWeight.W700, FontItemStyle.Normal),
    new ResourceFontItem(R.font.roboto_black, FontItemWeight.W900, FontItemStyle.Normal)
    // Ajouter toute police pertinente
);

// Si vous avez plusieurs polices, créez-les ici et ajoutez-les à fontFamilyMap

final Map<String, List<ResourceFontItem>> fontFamilyMap = new HashMap<>();
fontFamilyMap.put("roboto", fontItems);

final RoktUxConfig config = new RoktUxConfig.builder()
    .xmlFontFamilyMap(fontFamilyMap)
    .build();