Messages in-app

Conditions préalables

Avant de pouvoir utiliser cette fonctionnalité, vous devrez intégrer le SDK Roku de Braze. En outre, les messages in-app ne seront envoyés qu’aux appareils Roku exécutant la version minimale du SDK prise en charge :

Types de messages

Le SDK Roku prend uniquement en charge les messages in-app modaux.

Choisir une méthode d’affichage

Le SDK Roku 2.3.0 et versions ultérieures peut afficher les messages in-app à votre place. Vous pouvez aussi continuer à les afficher avec votre propre interface utilisateur.

Si vous effectuez une mise à niveau et utilisez déjà une interface personnalisée, consultez Mise à niveau vers le SDK Roku 2.3.0. Votre interface personnalisée continue de fonctionner tant que vous n’activez pas l’interface par défaut.

Utilisation de l’interface utilisateur par défaut

Important

L’interface utilisateur par défaut nécessite le sdk Roku 2.3.0 ou une version ultérieure.

Étape 1 : Ajouter les fichiers de l’interface utilisateur par défaut

Ajoutez les fichiers suivants du répertoire sdk_files/components du dépôt du SDK Braze pour Roku au répertoire components de votre application :

• BrazeDefaultInAppMessage.brs
• BrazeDefaultInAppMessage.xml
• BrazeDefaultInAppMessageStyles.brs

Si ces fichiers sont absents, le SDK enregistre le message BrazeDefaultInAppMessage component not found dans les journaux et n’affiche pas le message.

Étape 2 : Activer l’interface utilisateur par défaut

Dans main.brs, définissez automatic_iam_display sur true dans votre configuration Braze :

1
2

config[config_fields.AUTOMATIC_IAM_DISPLAY] = true
globalNode.addFields({brazeConfig: config})

Étape 3 : Initialiser Braze depuis votre Scene

Appelez getBrazeInstance() depuis votre composant Scene, par exemple dans init() :

1
2
3
4

sub init()
    m.BrazeTask = CreateObject("roSGNode", "BrazeTask")
    m.Braze = getBrazeInstance(m.BrazeTask)
end sub

Avertissement

Si vous appelez getBrazeInstance() depuis un autre composant, le SDK ne peut pas rattacher la superposition à la Scene, et le message est perdu.

Vous n’avez pas besoin d’observer BrazeTask.BrazeInAppMessage ni de créer une interface utilisateur pour les messages par défaut.

Fonctionnement de l’interface utilisateur par défaut

Messages pris en charge

L’interface utilisateur par défaut affiche uniquement les messages in-app MODAL. Le SDK ignore les autres types et consigne une erreur.

L’interface utilisateur par défaut utilise les champs suivants et ignore tous les autres.

Affichage et fermeture

Pour chaque message modal, le SDK effectue les opérations suivantes :

1. Il attend display_delay secondes, si ce paramètre est défini.
2. Il ajoute une superposition plein écran BrazeDefaultInAppMessage à votre Scene et lui donne le focus.
3. Il enregistre l’impression.
4. Il efface BrazeTask.BrazeInAppMessage.
5. Lorsque le message se ferme, il supprime la superposition et restaure le focus.

Si dismiss_type est défini sur AUTO_DISMISS, le message se ferme après duration millisecondes et aucun clic n’est enregistré. Sinon, le message reste affiché jusqu’à ce que l’utilisateur le ferme.

Le SDK affiche un seul message à la fois et ne place pas les messages en file d’attente :

• Un message plus récent annule un message qui attend encore la fin de son display_delay.
• Un message plus récent remplace le message à l’écran au moment où il s’affiche, après son propre display_delay.
• Les messages ignorés (qui ne sont pas de type MODAL ou qui n’ont pas de valeur message) n’annulent ni ne remplacent rien.

Télécommande

Focus

Si votre application appelle setFocus pendant que la superposition est affichée (par exemple lors du chargement de contenu, d’un changement d’écran ou de la lecture d’une vidéo), la superposition reprend le focus. Lorsque le message se ferme, le focus revient au dernier nœud sur lequel votre application l’avait placé.

Si votre application ouvre un dialog de Scene pendant que la superposition est affichée, la boîte de dialogue conserve le focus jusqu’à sa fermeture.

Gestion des clics et des deep links

Le SDK n’ouvre jamais d’URI. Pour gérer les valeurs click_action et uri d’un message, implémentez brazeHandleInAppMessageClick(event) dans votre Scene et déclarez-la dans l’<interface> de la Scene. Si elle n’est pas déclarée, le SDK ne l’appelle pas.

1
2
3
4
5
6

<component name="MainScene" extends="Scene">
    <interface>
        <function name="brazeHandleInAppMessageClick" />
    </interface>
    ...
</component>

Le paramètre event présente la structure suivante :

1
2
3
4
5

{
    in_app_message: <message AA>,
    button:         <button AA, or invalid for a body click>,
    button_index:   <0 or 1, or -1 for a body click>
}

Gardez les points suivants à l’esprit :

• Le SDK appelle cette fonction après avoir retiré la superposition et restauré le focus. Vous pouvez donc ouvrir un nouvel écran depuis cette fonction.
• Les boutons dont la valeur click_action est "NONE" appellent également cette fonction. Vérifiez click_action avant d’agir.
• Le SDK ignore la valeur renvoyée.
• Le SDK n’appelle pas cette fonction lorsque l’utilisateur ferme le message avec le bouton de fermeture ×, la touche Retour ou AUTO_DISMISS.
• Le SDK n’appelle pas cette fonction pour les messages que vous affichez avec brazeHandleCustomInAppMessage.

Exemple : Rediriger un deep link

1. Dans le tableau de bord de Braze, définissez le comportement au clic du message ou du bouton sur un deep link dont l’URI est comprise par votre application, par exemple myapp://details/123. Le SDK le transmet avec click_action = "URI", l’URI se trouvant dans uri.
2. Dans brazeHandleInAppMessageClick, analysez l’URI et redirigez vers l’écran correspondant :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

function brazeHandleInAppMessageClick(event as object) as boolean
    target = event.button
    if target = invalid then target = event.in_app_message

    if target.click_action <> "URI" then return false
    if target.uri = invalid then return false

    uri = target.uri.ToStr()
    prefix = "myapp://details/"
    if Left(uri, Len(prefix)) = prefix
        ' ShowDetailsScreen is a function in your app.
        ShowDetailsScreen(Mid(uri, Len(prefix) + 1))
        return true
    end if
    return false
end function

Remarque

La valeur uri peut arriver sous forme de nombre, par exemple si la valeur saisie dans le tableau de bord est numérique. Convertissez-la avec ToStr() avant de l’analyser.

Afficher des messages spécifiques avec une interface utilisateur personnalisée

Pour afficher certains messages avec votre propre interface utilisateur et utiliser l’interface par défaut pour les autres, implémentez brazeHandleCustomInAppMessage(in_app_message) dans votre Scene et déclarez-la dans l’<interface> de la Scene.

Le SDK appelle cette fonction pour chaque message MODAL après le display_delay. Renvoyez true si vous avez affiché le message vous-même. Renvoyez false pour l’afficher avec l’interface utilisateur par défaut.

1
2
3
4

<interface>
    <function name="brazeHandleCustomInAppMessage" />
    <function name="brazeHandleInAppMessageClick" />
</interface>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

function brazeHandleCustomInAppMessage(in_app_message as object) as boolean
    if in_app_message.extras <> invalid and in_app_message.extras.msgtype = "sidebyside"
        ' getDeepestFocusedNode is a helper in the sample app's MainScene.brs.
        m.oldFocus = getDeepestFocusedNode(m.top.focusedChild)
        m.customMsg = CreateObject("roSGNode", "CustomSideBySideInAppMessage")
        m.top.appendChild(m.customMsg)
        m.customMsg.BrazeTask = m.BrazeTask
        m.customMsg.inappmessage = in_app_message
        m.customMsg.setFocus(true)
        m.customMsg.ObserveField("isClosed", "reclaimFocus")
        return true
    end if
    return false
end function

sub reclaimFocus()
    m.top.removeChild(m.customMsg)
    m.customMsg = invalid
    if m.oldFocus <> invalid then m.oldFocus.setFocus(true)
end sub

Pour un exemple complet de composant personnalisé, consultez CustomSideBySideInAppMessage dans l’application d’exemple torchietv du dépôt du SDK Roku de Braze.

Gardez les points suivants à l’esprit :

• Le SDK appelle cette fonction uniquement lorsque automatic_iam_display vaut true et que les fichiers de l’interface utilisateur par défaut sont présents dans votre application.
• Seuls les messages MODAL atteignent cette fonction.
• Votre interface personnalisée doit se charger elle-même d’enregistrer les impressions, les clics et les clics sur les boutons, de supprimer son propre nœud et de restaurer le focus.
• Le SDK efface lui-même BrazeTask.BrazeInAppMessage et applique le display_delay : vous n’avez donc à gérer ni l’un ni l’autre.
• Lorsqu’un message plus récent arrive, le SDK supprime la superposition par défaut avant d’appeler cette fonction. En revanche, il ne peut pas supprimer une mise en page personnalisée que vous avez affichée auparavant : supprimez-la donc dans votre Scene.

Utiliser une interface utilisateur personnalisée pour tous les messages

Si vous ne définissez pas automatic_iam_display, votre application gère chaque message in-app. Votre observateur, votre interface utilisateur et votre journalisation fonctionnent comme avant la version 2.3.0 du SDK Roku, pour tous les types de messages.

Étape 1 : Ajouter un observateur

Pour traiter les messages in-app, vous pouvez ajouter un observateur sur BrazeTask.BrazeInAppMessage :

1

m.BrazeTask.observeField("BrazeInAppMessage", "onInAppMessageReceived")

Étape 2 : Accéder aux messages déclenchés

Ensuite, dans votre gestionnaire, vous avez accès au message in-app le plus prioritaire déclenché par vos Campaigns :

1
2
3
4

sub onInAppMessageReceived()
  in_app_message = m.BrazeTask.BrazeInAppMessage
  ...
end sub

Passer au SDK Roku 2.3.0

Le SDK Roku 2.3.0 ajoute l’interface utilisateur par défaut. Elle est désactivée par défaut : la mise à niveau ne modifie donc pas l’affichage de vos messages in-app. Choisissez l’une des options suivantes.

Conserver votre interface utilisateur personnalisée

1. Remplacez vos fichiers SDK existants par ceux du répertoire sdk_files de la version 2.3.0.
2. Ne définissez pas automatic_iam_display.

Votre observateur, votre interface utilisateur et votre journalisation fonctionnent comme avant, pour tous les types de messages. Le SDK n’utilise les fichiers BrazeDefaultInAppMessage que lorsque automatic_iam_display vaut true : vous pouvez donc les copier sans risque avec le reste de sdk_files.

Passer à l’interface utilisateur par défaut

1. Remplacez vos fichiers SDK existants par ceux du répertoire sdk_files de la version 2.3.0, puis ajoutez les fichiers BrazeDefaultInAppMessage.brs, BrazeDefaultInAppMessage.xml et BrazeDefaultInAppMessageStyles.brs à components. Votre ancien composant d’exemple BrazeInAppMessage n’est pas modifié. Vous pouvez le supprimer une fois la transition effectuée.
2. Activez l’interface utilisateur par défaut.
3. Vérifiez que getBrazeInstance() est appelé depuis votre Scene.
4. Supprimez votre gestion actuelle des messages in-app :
   • L’observateur : m.BrazeTask.observeField("BrazeInAppMessage", "onInAppMessageReceived") et son gestionnaire
   • La création et l’ajout de votre nœud de message in-app
   • Les appels à LogInAppMessageImpression, LogInAppMessageClick et LogInAppMessageButtonClick
   • m.BrazeTask.BrazeInAppMessage = invalid
5. Déplacez votre gestion des clics et des deep links vers brazeHandleInAppMessageClick.

Avertissement

Le SDK ajoute son propre observateur sans remplacer le vôtre. Si vous conservez votre observateur et votre journalisation après avoir activé l’interface utilisateur par défaut, les messages peuvent s’afficher deux fois, et les impressions et les clics sont enregistrés en double.

Conserver certaines de vos mises en page personnalisées

Suivez les étapes de la section Passer à l’interface utilisateur par défaut. Déplacez ensuite le code de rendu de votre ancien gestionnaire vers brazeHandleCustomInAppMessage.

Par rapport à votre ancien gestionnaire :

• Conservez votre journalisation des impressions et des clics.
• Continuez à supprimer votre propre nœud et à restaurer le focus.
• Supprimez m.BrazeTask.BrazeInAppMessage = invalid. Le SDK s’en charge.
• Supprimez votre propre gestion de display_delay. Le SDK l’applique.
• Seuls les messages MODAL parviennent à la fonction. Si vous affichez d’autres types de messages, continuez à utiliser une interface utilisateur personnalisée pour tous les messages.

Champs de message

Ces champs sont disponibles sur in_app_message lorsque vous affichez les messages avec une interface utilisateur personnalisée. L’interface utilisateur par défaut les applique automatiquement.

Gestion

Voici les champs dont vous aurez besoin pour gérer vos messages in-app :

Important

Pour les messages in-app contenant des boutons, la valeur click_action du message sera également incluse dans le payload final si l’action de clic est ajoutée avant le texte du bouton.

Style

Vous pouvez également utiliser divers champs de style depuis le tableau de bord :

Vous pouvez aussi implémenter le message in-app et lui appliquer un style directement dans votre application Roku à l’aide d’une palette standard :

Boutons