Mensajes dentro de la aplicación

Requisitos previos

Antes de poder utilizar esta característica, tendrás que integrar el SDK de Roku de Braze. Además, los mensajes dentro de la aplicación solo se enviarán a dispositivos Roku que ejecuten la versión mínima compatible del SDK:

Tipos de mensajes

El SDK de Roku solo admite mensajes dentro de la aplicación modales.

Elegir un método de visualización

El SDK de Roku 2.3.0 y versiones posteriores pueden mostrar los mensajes dentro de la aplicación por ti. También puedes seguir renderizándolos con tu propia interfaz de usuario.

Si estás actualizando y ya usas una interfaz de usuario personalizada, consulta Actualizar al SDK de Roku 2.3.0. Tu interfaz de usuario personalizada seguirá funcionando siempre que no actives la interfaz de usuario predeterminada.

Uso de la interfaz de usuario predeterminada

Importante

La interfaz de usuario predeterminada requiere el SDK de Roku 2.3.0 o posterior.

Paso 1: Añade los archivos de la interfaz de usuario predeterminada

Añade los siguientes archivos del directorio sdk_files/components del repositorio del SDK de Roku de Braze al directorio components de tu aplicación:

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

Si faltan estos archivos, el SDK registra BrazeDefaultInAppMessage component not found y no muestra el mensaje.

Paso 2: Activa la interfaz de usuario predeterminada

En main.brs, establece automatic_iam_display en true en tu configuración de Braze:

1
2

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

Paso 3: Inicializa Braze desde tu Scene

Llama a getBrazeInstance() desde tu componente Scene, por ejemplo en init():

1
2
3
4

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

Advertencia

Si llamas a getBrazeInstance() desde cualquier otro componente, el SDK no puede adjuntar la superposición a la Scene y el mensaje se pierde.

No necesitas observar BrazeTask.BrazeInAppMessage ni crear ninguna interfaz de usuario para los mensajes predeterminados.

Cómo funciona la interfaz de usuario predeterminada

Mensajes compatibles

La interfaz de usuario predeterminada solo muestra mensajes dentro de la aplicación de tipo MODAL. El SDK descarta los demás tipos y registra un error.

La interfaz de usuario predeterminada usa los siguientes campos e ignora cualquier otro.

Visualización y descarte

Para cada mensaje modal, el SDK hace lo siguiente:

1. Espera display_delay segundos, si está configurado.
2. Añade una superposición BrazeDefaultInAppMessage de pantalla completa a tu Scene y le da el foco.
3. Registra la impresión.
4. Borra BrazeTask.BrazeInAppMessage.
5. Cuando el mensaje se cierra, elimina la superposición y restaura el foco.

Si dismiss_type es AUTO_DISMISS, el mensaje se cierra después de duration milisegundos y no se registra ningún clic. De lo contrario, el mensaje permanece hasta que el usuario lo cierra.

El SDK muestra un mensaje cada vez y no pone los mensajes en cola:

• Un mensaje más reciente cancela un mensaje que todavía está esperando su display_delay.
• Un mensaje más reciente reemplaza al mensaje en pantalla cuando se muestra, después de su propio display_delay.
• Los mensajes descartados (que no son MODAL o que no tienen un valor message) no cancelan ni reemplazan nada.

Control remoto

Foco

Si tu aplicación llama a setFocus mientras se muestra la superposición, por ejemplo cuando se carga contenido, cambian las pantallas o se reproduce un video, la superposición recupera el foco. Cuando el mensaje se cierra, el foco vuelve al último nodo que tu aplicación enfocó.

Si tu aplicación abre un dialog de Scene mientras se muestra la superposición, el diálogo conserva el foco hasta que se cierra.

Manejo de clics y vínculos profundos

El SDK nunca abre URI. Para manejar el click_action y el uri de un mensaje, implementa brazeHandleInAppMessageClick(event) en tu Scene y decláralo en la <interface> de la Scene. Si no está declarado, el SDK no lo llama.

1
2
3
4
5
6

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

El parámetro event tiene la siguiente estructura:

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

Ten en cuenta lo siguiente:

• El SDK llama a esta función después de quitar la superposición y restaurar el foco, así que puedes abrir una nueva pantalla desde ella.
• Los botones con un click_action de "NONE" también llaman a esta función. Comprueba click_action antes de actuar.
• El SDK ignora el valor de retorno.
• El SDK no llama a esta función cuando el usuario cierra el mensaje con el botón de cierre ×, con Atrás o con AUTO_DISMISS.
• El SDK no llama a esta función para los mensajes que renderizas con brazeHandleCustomInAppMessage.

Ejemplo: Dirigir un vínculo profundo

1. En el panel de Braze, configura el comportamiento al hacer clic del mensaje o del botón como un vínculo profundo con una URI que tu aplicación entienda, como myapp://details/123. El SDK lo entrega como click_action = "URI", con la URI en uri.
2. En brazeHandleInAppMessageClick, analiza la URI y dirige al usuario a la pantalla correspondiente:

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

Nota

El valor de uri puede llegar como un número, por ejemplo, si el valor en el panel es numérico. Conviértelo con ToStr() antes de analizarlo.

Renderizar mensajes específicos con una interfaz de usuario personalizada

Para renderizar algunos mensajes con tu propia interfaz de usuario y usar la interfaz predeterminada para el resto, implementa brazeHandleCustomInAppMessage(in_app_message) en tu Scene y declárala en la <interface> de la Scene.

El SDK llama a esta función para cada mensaje MODAL después de display_delay. Devuelve true si renderizaste el mensaje. Devuelve false para mostrarlo con la interfaz de usuario predeterminada.

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

Para ver un componente personalizado completo, consulta CustomSideBySideInAppMessage en la aplicación de ejemplo torchietv del repositorio del SDK de Roku de Braze.

Ten en cuenta lo siguiente:

• El SDK llama a esta función solo cuando automatic_iam_display es true y los archivos de la interfaz de usuario predeterminada están en tu aplicación.
• Solo los mensajes MODAL llegan a esta función.
• Tu interfaz de usuario personalizada se encarga de registrar las impresiones, los clics y los clics en botones, de eliminar su propio nodo y de restaurar el foco.
• El SDK borra BrazeTask.BrazeInAppMessage y aplica display_delay por sí mismo, así que no gestiones ninguno de los dos tú mismo.
• Cuando llega un mensaje más reciente, el SDK elimina la superposición predeterminada antes de llamar a esta función. No puede eliminar un diseño personalizado que hayas renderizado antes, así que elimínalo en tu Scene.

Usar una interfaz de usuario personalizada para todos los mensajes

Si dejas automatic_iam_display sin configurar, tu aplicación gestiona todos los mensajes dentro de la aplicación. Tu observador, tu interfaz de usuario y tu registro funcionan igual que antes del SDK de Roku 2.3.0, para todos los tipos de mensaje.

Paso 1: Añade un observador

Para procesar los mensajes dentro de la aplicación, puedes añadir un observador en BrazeTask.BrazeInAppMessage:

1

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

Paso 2: Accede a los mensajes desencadenados

Después, dentro de tu controlador, tienes acceso al mensaje dentro de la aplicación de mayor prioridad que hayan desencadenado tus campañas:

1
2
3
4

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

Actualizar al SDK de Roku 2.3.0

El SDK de Roku 2.3.0 añade la interfaz de usuario predeterminada. Está desactivada de forma predeterminada, así que actualizar no cambia cómo se muestran tus mensajes dentro de la aplicación. Elige una de las siguientes opciones.

Mantener tu interfaz de usuario personalizada

1. Reemplaza tus archivos actuales del SDK por los archivos del directorio sdk_files de la versión 2.3.0.
2. No configures automatic_iam_display.

Tu observador, tu interfaz de usuario y tu registro siguen funcionando como antes, para todos los tipos de mensajes. El SDK usa los archivos BrazeDefaultInAppMessage solo cuando automatic_iam_display es true, así que puedes copiarlos con seguridad junto con el resto de sdk_files.

Cambiar a la interfaz de usuario predeterminada

1. Reemplaza tus archivos actuales del SDK por los archivos del directorio sdk_files de la versión 2.3.0 y añade los archivos BrazeDefaultInAppMessage.brs, BrazeDefaultInAppMessage.xml y BrazeDefaultInAppMessageStyles.brs a components. Tu antiguo componente de ejemplo BrazeInAppMessage no se modifica. Puedes eliminarlo después de hacer el cambio.
2. Activa la interfaz de usuario predeterminada.
3. Comprueba que se llama a getBrazeInstance() desde tu Scene.
4. Elimina tu gestión actual de mensajes dentro de la aplicación:
   • El observador: m.BrazeTask.observeField("BrazeInAppMessage", "onInAppMessageReceived") y su controlador
   • La creación y adición de tu nodo de mensaje dentro de la aplicación
   • Las llamadas a LogInAppMessageImpression, LogInAppMessageClick y LogInAppMessageButtonClick
   • m.BrazeTask.BrazeInAppMessage = invalid
5. Mueve tu gestión de clics y vínculos profundos a brazeHandleInAppMessageClick.

Advertencia

El SDK añade su propio observador y no reemplaza el tuyo. Si mantienes tu observador y tu registro al activar la interfaz de usuario predeterminada, los mensajes pueden mostrarse dos veces, y las impresiones y los clics se registran dos veces.

Mantener algunos de tus diseños personalizados

Sigue los pasos de Cambiar a la interfaz de usuario predeterminada. Después, mueve el código de renderizado de tu antiguo controlador a brazeHandleCustomInAppMessage.

En comparación con tu antiguo controlador:

• Mantén tu registro de impresiones y clics.
• Sigue eliminando tu propio nodo y restaurando el foco.
• Elimina m.BrazeTask.BrazeInAppMessage = invalid. El SDK lo borra.
• Elimina tu propia gestión de display_delay. El SDK la aplica.
• Solo los mensajes MODAL llegan a la función. Si renderizas otros tipos de mensajes, sigue usando una interfaz de usuario personalizada para todos los mensajes.

Campos del mensaje

Estos campos están disponibles en in_app_message cuando renderizas mensajes con una interfaz de usuario personalizada. La interfaz de usuario predeterminada los aplica por ti.

Gestión

A continuación se enumeran los campos que necesitarás para gestionar tus mensajes dentro de la aplicación:

Importante

En los mensajes dentro de la aplicación que contienen botones, el click_action del mensaje también se incluirá en la carga útil final si la acción de clic se añade antes de añadir el texto del botón.

Estilo

También hay varios campos de estilo que puedes elegir usar desde el panel:

Como alternativa, puedes implementar el mensaje dentro de la aplicación y darle estilo dentro de tu aplicación de Roku utilizando una paleta estándar:

Botones