In-app messages

Prerequisites

Before you can use this feature, you’ll need to integrate the Roku Braze SDK. Additionally, in-app messages will only be sent to Roku devices running the minimum supported SDK version:

Message types

The Roku SDK supports only modal in-app messages.

Choosing a display method

Roku SDK 2.3.0 and later can display in-app messages for you. You can also keep rendering them with your own UI.

If you’re upgrading and already use a custom UI, refer to Upgrading to Roku SDK 2.3.0. Your custom UI keeps working as long as you don’t turn on the default UI.

Using the default UI

important

The default UI requires Roku SDK 2.3.0 or later.

Step 1: Add the default UI files

Add the following files from the sdk_files/components directory of the Braze Roku SDK repository to the components directory of your app:

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

If these files are missing, the SDK logs BrazeDefaultInAppMessage component not found and doesn’t display the message.

Step 2: Turn on the default UI

In main.brs, set automatic_iam_display to true in your Braze configuration:

1
2

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

Step 3: Initialize Braze from your Scene

Call getBrazeInstance() from your Scene component, for example in init():

1
2
3
4

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

warning

If you call getBrazeInstance() from any other component, the SDK can’t attach the overlay to the Scene, and the message is lost.

You don’t need to observe BrazeTask.BrazeInAppMessage or create any UI for the default messages.

How the default UI works

Supported messages

The default UI displays only MODAL in-app messages. The SDK drops other types and logs an error.

The default UI uses the following fields. It ignores any others.

Display and dismissal

For each modal message, the SDK does the following:

1. Waits display_delay seconds, if set.
2. Adds a full-screen BrazeDefaultInAppMessage overlay to your Scene and gives it focus.
3. Logs the impression.
4. Clears BrazeTask.BrazeInAppMessage.
5. When the message closes, removes the overlay and restores focus.

If dismiss_type is AUTO_DISMISS, the message closes after duration milliseconds and no click is logged. Otherwise, the message stays until the user closes it.

The SDK shows one message at a time and doesn’t queue messages:

• A newer message cancels a message that’s still waiting out its display_delay.
• A newer message replaces the message on screen when it’s displayed, after its own display_delay.
• Dropped messages (not MODAL, or without a message value) don’t cancel or replace anything.

Remote control

Focus

If your app calls setFocus while the overlay is displayed, such as when content loads, screens change, or video plays, the overlay takes focus back. When the message closes, focus returns to the last node your app focused.

If your app opens a Scene dialog while the overlay is displayed, the dialog keeps focus until it closes.

Handling clicks and deep links

The SDK never opens URIs. To handle a message’s click_action and uri, implement brazeHandleInAppMessageClick(event) on your Scene and declare it in the Scene’s <interface>. If it isn’t declared, the SDK doesn’t call it.

1
2
3
4
5
6

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

The event parameter has the following structure:

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

Keep the following in mind:

• The SDK calls this function after it removes the overlay and restores focus, so you can open a new screen from it.
• Buttons with a click_action of "NONE" also call this function. Check click_action before you act.
• The SDK ignores the return value.
• The SDK doesn’t call this function when the user closes the message with the × close button, Back, or AUTO_DISMISS.
• The SDK doesn’t call this function for messages you render with brazeHandleCustomInAppMessage.

Example: Route a deep link

1. In the Braze dashboard, set the on-click behavior of the message or button to a deep link with a URI your app understands, such as myapp://details/123. The SDK delivers it as click_action = "URI", with the URI in uri.
2. In brazeHandleInAppMessageClick, parse the URI and route to the matching screen:

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

note

The uri value can arrive as a number, for example if the dashboard value is numeric. Convert it with ToStr() before you parse it.

Rendering specific messages with a custom UI

To render some messages with your own UI and use the default UI for the rest, implement brazeHandleCustomInAppMessage(in_app_message) on your Scene and declare it in the Scene’s <interface>.

The SDK calls this function for each MODAL message after display_delay. Return true if you rendered the message. Return false to display it with the default UI.

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

For a complete custom component, refer to CustomSideBySideInAppMessage in the torchietv sample app in the Braze Roku SDK repository.

Keep the following in mind:

• The SDK calls this function only when automatic_iam_display is true and the default UI files are in your app.
• Only MODAL messages reach this function.
• Your custom UI is responsible for logging impressions, clicks, and button clicks, removing its own node, and restoring focus.
• The SDK clears BrazeTask.BrazeInAppMessage and applies display_delay itself, so don’t handle either yourself.
• When a newer message arrives, the SDK removes the default overlay before it calls this function. It can’t remove a custom layout you rendered earlier, so remove it in your Scene.

Using a custom UI for all messages

If you leave automatic_iam_display unset, your app handles every in-app message. Your observer, UI, and logging work as they did before Roku SDK 2.3.0, for every message type.

Step 1: Add an observer

To process in-app messages, you can add an observer on BrazeTask.BrazeInAppMessage:

1

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

Step 2: Access triggered messages

Then within your handler, you have access to the highest in-app message that your campaigns have triggered:

1
2
3
4

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

Upgrading to Roku SDK 2.3.0

Roku SDK 2.3.0 adds the default UI. It’s off by default, so upgrading doesn’t change how your in-app messages display. Choose one of the following paths.

Keep your custom UI

1. Replace your existing SDK files with the files from the sdk_files directory of the 2.3.0 release.
2. Leave automatic_iam_display unset.

Your observer, UI, and logging work as before, for every message type. The SDK uses the BrazeDefaultInAppMessage files only when automatic_iam_display is true, so it’s safe to copy them with the rest of sdk_files.

Switch to the default UI

1. Replace your existing SDK files with the files from the sdk_files directory of the 2.3.0 release, and add the BrazeDefaultInAppMessage.brs, BrazeDefaultInAppMessage.xml, and BrazeDefaultInAppMessageStyles.brs files to components. Your old sample BrazeInAppMessage component isn’t changed. You can delete it after you switch.
2. Turn on the default UI.
3. Check that getBrazeInstance() is called from your Scene.
4. Remove your existing in-app message handling:
   • The observer: m.BrazeTask.observeField("BrazeInAppMessage", "onInAppMessageReceived") and its handler
   • Creating and appending your in-app message node
   • Calls to LogInAppMessageImpression, LogInAppMessageClick, and LogInAppMessageButtonClick
   • m.BrazeTask.BrazeInAppMessage = invalid
5. Move your click and deep link handling to brazeHandleInAppMessageClick.

warning

The SDK adds its own observer and doesn’t replace yours. If you keep your observer and logging when you turn on the default UI, messages can display twice, and impressions and clicks are logged twice.

Keep some of your custom layouts

Follow the steps in Switch to the default UI. Then move the rendering code from your old handler into brazeHandleCustomInAppMessage.

Compared to your old handler:

• Keep your impression and click logging.
• Keep removing your own node and restoring focus.
• Remove m.BrazeTask.BrazeInAppMessage = invalid. The SDK clears it.
• Remove your own display_delay handling. The SDK applies it.
• Only MODAL messages reach the function. If you render other message types, keep using a custom UI for all messages.

Message fields

These fields are available on in_app_message when you render messages with a custom UI. The default UI applies them for you.

Handling

The following lists the fields you will need to handle your in-app messages:

important

For in-app messages containing buttons, the message click_action will also be included in the final payload if the click action is added prior to adding the button text.

Styling

There are also various styling fields that you could choose to use from the dashboard:

Alternatively, you could implement the in-app message and style it within your Roku application using a standard palette:

Buttons