In-App-Nachrichten

Voraussetzungen

Bevor Sie dieses Feature nutzen können, müssen Sie das Braze Roku SDK integrieren. Außerdem werden In-App-Nachrichten nur an Roku-Geräte gesendet, auf denen die minimal unterstützte SDK-Version läuft:

Nachrichtentypen

Das Roku SDK unterstützt nur modale In-App-Nachrichten.

Eine Anzeigemethode auswählen

Roku SDK 2.3.0 und höher kann In-App-Nachrichten für Sie anzeigen. Sie können diese aber auch weiterhin mit Ihrer eigenen UI rendern.

Wenn Sie ein Upgrade durchführen und bereits eine angepasste UI verwenden, lesen Sie Upgrade auf Roku SDK 2.3.0. Ihre angepasste UI funktioniert weiterhin, solange Sie die Standard-UI nicht aktivieren.

Die Standard-UI verwenden

Wichtig

Die Standard-UI erfordert Roku SDK 2.3.0 oder höher.

Schritt 1: Dateien der Standard-UI hinzufügen

Fügen Sie die folgenden Dateien aus dem Verzeichnis sdk_files/components des Braze Roku SDK-Repositorys zum Verzeichnis components Ihrer App hinzu:

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

Wenn diese Dateien fehlen, protokolliert das SDK BrazeDefaultInAppMessage component not found und zeigt die Nachricht nicht an.

Schritt 2: Standard-UI aktivieren

Setzen Sie in main.brs in Ihrer Braze-Konfiguration automatic_iam_display auf true:

1
2

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

Schritt 3: Braze aus Ihrer Scene initialisieren

Rufen Sie getBrazeInstance() aus Ihrer Scene-Komponente auf, zum Beispiel in init():

1
2
3
4

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

Warnung

Wenn Sie getBrazeInstance() aus einer anderen Komponente aufrufen, kann das SDK das Overlay nicht an die Scene anhängen, und die Nachricht geht verloren.

Für die Standardnachrichten müssen Sie weder BrazeTask.BrazeInAppMessage beobachten noch eine eigene UI erstellen.

So funktioniert die Standard-UI

Unterstützte Nachrichten

Die Standard-UI zeigt nur MODAL-In-App-Nachrichten an. Das SDK verwirft andere Typen und protokolliert einen Fehler.

Die Standard-UI verwendet die folgenden Felder. Alle anderen werden ignoriert.

Anzeigen und Schließen

Für jede modale Nachricht führt das SDK die folgenden Schritte aus:

1. Es wartet display_delay Sekunden, sofern festgelegt.
2. Es fügt Ihrer Scene ein Vollbild-Overlay BrazeDefaultInAppMessage hinzu und gibt diesem den Fokus.
3. Es protokolliert die Impression.
4. Es leert BrazeTask.BrazeInAppMessage.
5. Wenn die Nachricht geschlossen wird, entfernt es das Overlay und stellt den Fokus wieder her.

Wenn dismiss_type den Wert AUTO_DISMISS hat, wird die Nachricht nach duration Millisekunden geschlossen, und es wird kein Klick protokolliert. Andernfalls bleibt die Nachricht sichtbar, bis Nutzer:innen sie schließen.

Das SDK zeigt jeweils nur eine Nachricht an und reiht keine Nachrichten in eine Warteschlange ein:

• Eine neuere Nachricht bricht eine Nachricht ab, die noch ihre display_delay abwartet.
• Eine neuere Nachricht ersetzt die Nachricht auf dem Bildschirm, sobald sie nach ihrer eigenen display_delay angezeigt wird.
• Verworfene Nachrichten (nicht MODAL oder ohne message-Wert) brechen nichts ab und ersetzen nichts.

Fernbedienung

Fokus

Wenn Ihre App setFocus aufruft, während das Overlay angezeigt wird, etwa wenn Inhalte geladen werden, Bildschirme wechseln oder ein Video abgespielt wird, holt sich das Overlay den Fokus zurück. Wenn die Nachricht geschlossen wird, kehrt der Fokus zum letzten Knoten zurück, den Ihre App fokussiert hat.

Wenn Ihre App einen Scene-dialog öffnet, während das Overlay angezeigt wird, behält der Dialog den Fokus, bis er geschlossen wird.

Umgang mit Klicks und Deeplinks

Das SDK öffnet niemals URIs. Um click_action und uri einer Nachricht zu verarbeiten, implementieren Sie brazeHandleInAppMessageClick(event) in Ihrer Scene und deklarieren Sie die Funktion im <interface> der Scene. Ist sie nicht deklariert, ruft das SDK sie nicht auf.

1
2
3
4
5
6

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

Der Parameter event hat die folgende Struktur:

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

Beachten Sie Folgendes:

• Das SDK ruft diese Funktion auf, nachdem es das Overlay entfernt und den Fokus wiederhergestellt hat. Sie können daraus also einen neuen Bildschirm öffnen.
• Auch Buttons mit der click_action "NONE" rufen diese Funktion auf. Prüfen Sie click_action, bevor Sie eine Aktion ausführen.
• Das SDK ignoriert den Rückgabewert.
• Das SDK ruft diese Funktion nicht auf, wenn Nutzer:innen die Nachricht über den ×-Schließen-Button, die Zurück-Taste oder AUTO_DISMISS schließen.
• Das SDK ruft diese Funktion nicht für Nachrichten auf, die Sie mit brazeHandleCustomInAppMessage rendern.

Beispiel: Einen Deeplink weiterleiten

1. Legen Sie im Braze-Dashboard das Klickverhalten der Nachricht oder des Buttons auf einen Deeplink mit einer URI fest, die Ihre App versteht, z. B. myapp://details/123. Das SDK liefert diesen als click_action = "URI", wobei die URI in uri enthalten ist.
2. Parsen Sie in brazeHandleInAppMessageClick die URI und leiten Sie zum passenden Bildschirm weiter:

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

Hinweis

Der Wert uri kann als Zahl ankommen, z. B. wenn der Wert im Dashboard numerisch ist. Konvertieren Sie ihn mit ToStr(), bevor Sie ihn parsen.

Rendern bestimmter Nachrichten mit einer angepassten UI

Um einige Nachrichten mit Ihrer eigenen UI und die übrigen mit der Standard-UI zu rendern, implementieren Sie brazeHandleCustomInAppMessage(in_app_message) in Ihrer Scene und deklarieren Sie die Funktion im <interface> der Scene.

Das SDK ruft diese Funktion für jede MODAL-Nachricht nach display_delay auf. Geben Sie true zurück, wenn Sie die Nachricht gerendert haben. Geben Sie false zurück, um sie mit der Standard-UI anzuzeigen.

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

Eine vollständige angepasste Komponente finden Sie unter CustomSideBySideInAppMessage in der Beispiel-App torchietv im Braze Roku SDK Repository.

Beachten Sie Folgendes:

• Das SDK ruft diese Funktion nur auf, wenn automatic_iam_display auf true gesetzt ist und sich die Dateien der Standard-UI in Ihrer App befinden.
• Nur MODAL-Nachrichten erreichen diese Funktion.
• Ihre angepasste UI ist dafür verantwortlich, Impressionen, Klicks und Button-Klicks zu protokollieren, ihren eigenen Knoten zu entfernen und den Fokus wiederherzustellen.
• Das SDK leert BrazeTask.BrazeInAppMessage und wendet display_delay selbst an. Sie müssen sich also um keines von beidem selbst kümmern.
• Wenn eine neuere Nachricht eintrifft, entfernt das SDK das Standard-Overlay, bevor es diese Funktion aufruft. Ein zuvor von Ihnen gerendertes angepasstes Layout kann es nicht entfernen. Entfernen Sie dieses daher in Ihrer Scene.

Eine angepasste UI für alle Nachrichten verwenden

Wenn Sie automatic_iam_display nicht festlegen, verarbeitet Ihre App jede In-App-Nachricht selbst. Ihr Observer, Ihre UI und Ihr Logging funktionieren für alle Nachrichtentypen genauso wie vor Roku SDK 2.3.0.

Schritt 1: Einen Observer hinzufügen

Um In-App-Nachrichten zu verarbeiten, können Sie einen Observer für BrazeTask.BrazeInAppMessage hinzufügen:

1

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

Schritt 2: Auf getriggerte Nachrichten zugreifen

Anschließend haben Sie in Ihrem Handler Zugriff auf die In-App-Nachricht mit der höchsten Priorität, die Ihre Kampagnen getriggert haben:

1
2
3
4

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

Upgrade auf Roku SDK 2.3.0

Roku SDK 2.3.0 führt die Standard-UI ein. Sie ist standardmäßig deaktiviert, sodass ein Upgrade nichts an der Darstellung Ihrer In-App-Nachrichten ändert. Wählen Sie einen der folgenden Wege.

Angepasste UI beibehalten

1. Ersetzen Sie Ihre vorhandenen SDK-Dateien durch die Dateien aus dem Verzeichnis sdk_files des Release 2.3.0.
2. Lassen Sie automatic_iam_display ungesetzt.

Ihr Observer, Ihre UI und Ihr Logging funktionieren wie bisher, und zwar für jeden Nachrichtentyp. Das SDK verwendet die BrazeDefaultInAppMessage-Dateien nur, wenn automatic_iam_display auf true gesetzt ist. Sie können sie also bedenkenlos zusammen mit dem Rest von sdk_files kopieren.

Zur Standard-UI wechseln

1. Ersetzen Sie Ihre vorhandenen SDK-Dateien durch die Dateien aus dem Verzeichnis sdk_files des Release 2.3.0 und fügen Sie die Dateien BrazeDefaultInAppMessage.brs, BrazeDefaultInAppMessage.xml und BrazeDefaultInAppMessageStyles.brs zu components hinzu. Ihre alte Beispielkomponente BrazeInAppMessage bleibt unverändert. Sie können sie nach dem Wechsel löschen.
2. Aktivieren Sie die Standard-UI.
3. Prüfen Sie, ob getBrazeInstance() aus Ihrer Scene aufgerufen wird.
4. Entfernen Sie Ihre bisherige Verarbeitung von In-App-Nachrichten:
   • Den Observer: m.BrazeTask.observeField("BrazeInAppMessage", "onInAppMessageReceived") und seinen Handler
   • Das Erstellen und Anhängen Ihres In-App-Nachrichten-Knotens
   • Aufrufe von LogInAppMessageImpression, LogInAppMessageClick und LogInAppMessageButtonClick
   • m.BrazeTask.BrazeInAppMessage = invalid
5. Verschieben Sie Ihre Verarbeitung von Klicks und Deeplinks nach brazeHandleInAppMessageClick.

Warnung

Das SDK fügt einen eigenen Observer hinzu und ersetzt Ihren nicht. Wenn Sie Ihren Observer und Ihr Logging beibehalten, nachdem Sie die Standard-UI aktiviert haben, können Nachrichten doppelt angezeigt und Impressionen sowie Klicks doppelt protokolliert werden.

Einige Ihrer angepassten Layouts beibehalten

Führen Sie die Schritte unter Zur Standard-UI wechseln aus. Verschieben Sie anschließend den Rendering-Code aus Ihrem alten Handler nach brazeHandleCustomInAppMessage.

Im Vergleich zu Ihrem alten Handler:

• Behalten Sie Ihr Logging von Impressionen und Klicks bei.
• Entfernen Sie weiterhin Ihren eigenen Knoten und stellen Sie den Fokus wieder her.
• Entfernen Sie m.BrazeTask.BrazeInAppMessage = invalid. Das SDK setzt den Wert zurück.
• Entfernen Sie Ihre eigene Verarbeitung von display_delay. Das SDK wendet die Verzögerung an.
• Nur MODAL-Nachrichten erreichen die Funktion. Wenn Sie andere Nachrichtentypen rendern, verwenden Sie weiterhin eine angepasste UI für alle Nachrichten.

Nachrichtenfelder

Diese Felder stehen in in_app_message zur Verfügung, wenn Sie Nachrichten mit einer angepassten UI rendern. Die Standard-UI wendet sie automatisch für Sie an.

Handhabung

Im Folgenden finden Sie die Felder, die Sie für die Handhabung Ihrer In-App-Nachrichten benötigen:

Wichtig

Bei In-App-Nachrichten mit Buttons wird die click_action der Nachricht auch in den endgültigen Payload aufgenommen, wenn die Klickaktion vor dem Hinzufügen des Button-Texts hinzugefügt wird.

Styling

Es gibt außerdem verschiedene Styling-Felder, die Sie im Dashboard verwenden können:

Alternativ können Sie die In-App-Nachricht implementieren und sie innerhalb Ihrer Roku-Anwendung mit einer Standardpalette gestalten:

Buttons