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 avec l'intégration serveur à serveur (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

// Retrieve the experience response from your server
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 l'é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 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 -> {
                // Open AndroidX browser or similar functionality to keep the user in app
                val customTabsIntent = CustomTabsIntent.Builder().build()
                customTabsIntent.launchUrl(context, Uri.parse(openUrlEvent.url))

                openUrlEvent.onClose.invoke(openUrlEvent.id) // This must be called when the user is ready for the next offer
            }
            OpenLinks.Externally, OpenLinks.Passthrough -> {
                // Open external browser allowing user to leave the app
                val intent = Intent(Intent.ACTION_VIEW, Uri.parse(openUrlEvent.url))
                context.startActivity(intent)

                openUrlEvent.onClose.invoke(openUrlEvent.id) // This must be called when the user is ready for the next offer
            }
        }
    }
}

Java

roktUxEvent -> {
    // Handle open URL event
    // Here is a sample how to open different types of URLs
    if (roktUxEvent instanceof RoktUxEvent.OpenUrl openUrlEvent) {
        if (openUrlEvent.getType() == OpenLinks.Internally) {
            // Open AndroidX browser or similar functionality to keep the user in app
            CustomTabsIntent customTabsIntent = new CustomTabsIntent.Builder().build();
            customTabsIntent.launchUrl(context, Uri.parse(openUrlEvent.getUrl()));

            openUrlEvent.getOnClose().invoke(openUrlEvent.getId()); // This must be called when the user is ready for the next offer
        } else {
            // Open external browser allowing user to leave the app
            final Intent intent = new Intent(Intent.ACTION_VIEW, Uri.parse(openUrlEvent.getUrl()));
            context.startActivity(intent);

            openUrlEvent.getOnClose().invoke(openUrlEvent.getId());  // This must be called when the user is ready for the next offer
        }
    }
    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 le 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 (internally/externally/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 ->
    // Send these platform events to Rokt API including the event body
}

Java

roktPlatformEvents -> {
    // Send these platform events to Rokt API including the event body
    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 définir 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 système

ImageLoader

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 pour l'implémentation est NetworkStrategy, cependant, selon votre bibliothèque de 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 au fichier 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 = // Retrieve the experience response from your server
val roktUxConfig = RoktUxConfig.builder()
            .build()

roktLayoutView.loadLayout(
    experienceResponse = experienceResponse,
    roktUxConfig,
    onUxEvent = { event ->
        // Handle UX events here
    },
    onPlatformEvent = { platformEvent ->
        // Send these platform events to Rokt API
    },
)

Java

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

roktLayoutView.loadLayout(
    experienceResponse,
    roktUxConfig,
    roktUxEvent -> {
        // Handle UX events here
        return null;
    },
    roktPlatformEvent -> {
        // Send these platform events to Rokt API
        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 l'é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 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 -> {
                // Open AndroidX browser or similar functionality to keep the user in app
                val customTabsIntent = CustomTabsIntent.Builder().build()
                customTabsIntent.launchUrl(context, Uri.parse(openUrlEvent.url))

                openUrlEvent.onClose.invoke(openUrlEvent.id) // This must be called when the user is ready for the next offer
            }
            OpenLinks.Externally, OpenLinks.Passthrough -> {
                // Open external browser allowing user to leave the app
                val intent = Intent(Intent.ACTION_VIEW, Uri.parse(openUrlEvent.url))
                context.startActivity(intent)

                openUrlEvent.onClose.invoke(openUrlEvent.id) // This must be called when the user is ready for the next offer
            }
        }
    }
}

Java

roktUxEvent -> {
    // Handle open URL event
    // Here is a sample how to open different types of URLs
    if (roktUxEvent instanceof RoktUxEvent.OpenUrl openUrlEvent) {
        if (openUrlEvent.getType() == OpenLinks.Internally) {
            // Open AndroidX browser or similar functionality to keep the user in app
            CustomTabsIntent customTabsIntent = new CustomTabsIntent.Builder().build();
            customTabsIntent.launchUrl(context, Uri.parse(openUrlEvent.getUrl()));

            openUrlEvent.getOnClose().invoke(openUrlEvent.getId()); // This must be called when the user is ready for the next offer
        } else {
            // Open external browser allowing user to leave the app
            final Intent intent = new Intent(Intent.ACTION_VIEW, Uri.parse(openUrlEvent.getUrl()));
            context.startActivity(intent);

            openUrlEvent.getOnClose().invoke(openUrlEvent.getId());  // This must be called when the user is ready for the next offer
        }
    }
    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 le 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 (internally/externally/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 ->
    // Send these platform events to Rokt API including the event body
}

Java

roktPlatformEvents -> {
    // Send these platform events to Rokt API including the event body
    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 définir 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 système

ImageLoader

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 pour l'implémentation est NetworkStrategy, cependant, selon votre bibliothèque de 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

Tout d'abord, vous devez ajouter vos fichiers de polices, par exemple roboto_light.ttf, à votre dossier de ressources Android, puis configurer le UX Helper pour les utiliser avec RoktUxConfig. L'exemple ci-dessous concerne les polices configurées dans les ressources, cependant, nous prenons également en charge 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),
    // Add any relevant fonts
)

// If you have multiple fonts create them here and add them to the 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)
    // Add any relevant fonts
);

// If you have multiple fonts create them here and add them to the fontFamilyMap

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

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