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 en conjonction avec 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érez 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 Received $it") },
        onPlatformEvent = { println("RoktEvent: onPlatformEvent received $it") },
        roktUxConfig = RoktUxConfig.builder()
            .imageHandlingStrategy(NetworkStrategy())
            .build(),
    )
}

Événements UX

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

Au minimum, vous devez gérer lorsque qu'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 callback onClose qui notifiera le RoktUXHelper pour exécuter une logique telle que passer à l'offre suivante.

Kotlin

openUrlEvent.onClose.invoke(openUrlEvent.id)

Java

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

Kotlin

onUxEvent = { event ->
    println("RoktEvent: onUxEvent received $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 l'offre suivante
            }
            OpenLinks.Externally, OpenLinks.Passthrough -> {
                // Ouvrir un 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 l'offre suivante
            }
        }
    }
}

Java

roktUxEvent -> {
    // Gérer l'événement d'ouverture d'URL
    // Voici un exemple de comment ouvrir différents types d'URL
    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 l'offre suivante
        } else {
            // Ouvrir un 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 l'offre suivante
        }
    }
    return null;
}

Tous les événements

Événements UX

Événement	Description	Paramètres
OfferEngagement	Déclenché lorsque l'utilisateur interagit avec l'offre	layoutId: String
PositiveEngagement	Déclenché lorsque l'utilisateur interagit positivement avec l'offre	layoutId: String
LayoutInteractive	Déclenché lorsqu'une mise en page a été rendue et est interactive	layoutId: String
LayoutReady	Déclenché lorsqu'une mise en page est prête à être affichée mais n'a pas encore rendu de contenu	layoutId: String
LayoutClosed	Déclenché lorsqu'une mise en page est fermée par l'utilisateur	layoutId: String
LayoutCompleted	Déclenché lorsque la progression de l'offre atteint la fin et qu'aucune autre offre n'est disponible à afficher	layoutId: String
LayoutFailure	Déclenché lorsqu'une mise en page n'a pas pu être affichée en raison d'une défaillance	layoutId: String (optionnel)
OpenUrl	Déclenché lorsqu'un lien doit être ouvert	url: String, id: String, type: OpenLinks (interne/externe/Passthrough), onClose: (id: String) -> Unit, onError: (id: String, throwable: Throwable)

PlatformEvents

Les événements de plateforme sont une partie essentielle de l'intégration et 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 ->
    // Envoyez ces événements de plateforme à l'API Rokt, y compris le corps de l'événement
}

Java

roktPlatformEvents -> {
    // Envoyez ces événements de plateforme à l'API Rokt, y compris 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 couleur

Le mode 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 utilise le mode couleur du système par défaut

ImageLoader

Dans Rokt UX Helper, coil est utilisé pour charger des images. UX Helper possè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, en fonction de votre bibliothèque de réseau ou de 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 au 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érer 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 ->
        // Envoyer ces événements de plateforme à l'API 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 -> {
        // Envoyer ces événements de plateforme à l'API Rokt
        return null;
    }
);

Événements UX

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

Au minimum, vous devez gérer lorsque qu'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 callback onClose qui notifiera le RoktUXHelper pour exécuter une logique telle que passer à l'offre suivante.

Kotlin

openUrlEvent.onClose.invoke(openUrlEvent.id)

Java

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

Kotlin

onUxEvent = { event ->
    println("RoktEvent: onUxEvent received $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 l'offre suivante
            }
            OpenLinks.Externally, OpenLinks.Passthrough -> {
                // Ouvrir un 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 l'offre suivante
            }
        }
    }
}

Java

roktUxEvent -> {
    // Gérer l'événement d'ouverture d'URL
    // Voici un exemple de comment ouvrir différents types d'URL
    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 l'offre suivante
        } else {
            // Ouvrir un 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 l'offre suivante
        }
    }
    return null;
}

Tous les événements

Événements UX

Événement	Description	Paramètres
OfferEngagement	Déclenché lorsque l'utilisateur interagit avec l'offre	layoutId: String
PositiveEngagement	Déclenché lorsque l'utilisateur interagit positivement avec l'offre	layoutId: String
LayoutInteractive	Déclenché lorsqu'une mise en page a été rendue et est interactive	layoutId: String
LayoutReady	Déclenché lorsqu'une mise en page est prête à être affichée mais n'a pas encore rendu de contenu	layoutId: String
LayoutClosed	Déclenché lorsqu'une mise en page est fermée par l'utilisateur	layoutId: String
LayoutCompleted	Déclenché lorsque la progression de l'offre atteint la fin et qu'aucune autre offre n'est disponible à afficher	layoutId: String
LayoutFailure	Déclenché lorsqu'une mise en page n'a pas pu être affichée en raison d'une défaillance	layoutId: String (optionnel)
OpenUrl	Déclenché lorsqu'un lien doit être ouvert	url: String, id: String, type: OpenLinks (interne/externe/Passthrough), onClose: (id: String) -> Unit, onError: (id: String, throwable: Throwable)

PlatformEvents

Les événements de plateforme sont une partie essentielle de l'intégration et 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 ->
    // Envoyez ces événements de plateforme à l'API Rokt, y compris le corps de l'événement
}

Java

roktPlatformEvents -> {
    // Envoyez ces événements de plateforme à l'API Rokt, y compris 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 couleur

Le mode 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 utilise le mode couleur du système par défaut

ImageLoader

Dans Rokt UX Helper, coil est utilisé pour charger des images. UX Helper possè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, en fonction de votre bibliothèque de réseau ou de 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

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),
    // Ajoutez toutes les polices pertinentes
)

// 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)
    // Ajoutez toutes les polices pertinentes
);

// 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();