Mensagens no app

Pré-requisitos

Antes de usar este recurso, você precisará integrar o Roku Braze SDK. Além disso, as mensagens no app só serão enviadas para dispositivos Roku que estejam executando a versão mínima suportada do SDK:

Tipos de mensagem

O Roku SDK oferece suporte apenas a mensagens no app do tipo modal.

Escolher um método de exibição

O Roku SDK 2.3.0 e versões posteriores podem exibir mensagens no app para você. Você também pode continuar renderizando essas mensagens com sua própria interface.

Se você estiver fazendo upgrade e já usa uma interface personalizada, consulte Upgrade para o Roku SDK 2.3.0. Sua interface personalizada continua funcionando desde que você não ative a interface padrão.

Usando a interface padrão

Importante

A interface padrão requer o Roku SDK 2.3.0 ou posterior.

Etapa 1: Adicione os arquivos da interface padrão

Adicione os seguintes arquivos do diretório sdk_files/components do repositório do Braze Roku SDK ao diretório components do seu app:

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

Se esses arquivos estiverem ausentes, o SDK registra BrazeDefaultInAppMessage component not found e não exibe a mensagem.

Etapa 2: Ative a interface padrão

Em main.brs, defina automatic_iam_display como true na sua configuração da Braze:

1
2

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

Etapa 3: Inicialize a Braze a partir da sua Scene

Chame getBrazeInstance() a partir do seu componente Scene, por exemplo, em init():

1
2
3
4

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

Aviso

Se você chamar getBrazeInstance() a partir de qualquer outro componente, o SDK não consegue anexar a sobreposição à Scene, e a mensagem é perdida.

Você não precisa observar BrazeTask.BrazeInAppMessage nem criar nenhuma interface para as mensagens padrão.

Como a interface padrão funciona

Mensagens compatíveis

A interface padrão exibe apenas mensagens no app do tipo MODAL. O SDK descarta outros tipos e registra um erro.

A interface padrão usa os campos a seguir e ignora todos os outros.

Exibição e dispensa

Para cada mensagem modal, o SDK faz o seguinte:

1. Aguarda display_delay segundos, se definido.
2. Adiciona uma sobreposição BrazeDefaultInAppMessage em tela inteira à sua Scene e dá foco a ela.
3. Registra a impressão.
4. Limpa BrazeTask.BrazeInAppMessage.
5. Quando a mensagem é fechada, remove a sobreposição e restaura o foco.

Se dismiss_type for AUTO_DISMISS, a mensagem é fechada depois de duration milissegundos e nenhum clique é registrado. Caso contrário, a mensagem permanece na tela até que o usuário a feche.

O SDK mostra uma mensagem por vez e não coloca mensagens em fila:

• Uma mensagem mais recente cancela uma mensagem que ainda está aguardando seu display_delay.
• Uma mensagem mais recente substitui a mensagem na tela quando é exibida, depois do seu próprio display_delay.
• Mensagens descartadas (que não são MODAL ou que não têm um valor de message) não cancelam nem substituem nada.

Controle remoto

Foco

Se o seu app chamar setFocus enquanto a sobreposição estiver sendo exibida (por exemplo, quando um conteúdo carrega, as telas mudam ou um vídeo é reproduzido), a sobreposição retoma o foco. Quando a mensagem é fechada, o foco volta para o último nó que recebeu foco no seu app.

Se o seu app abrir um dialog da Scene enquanto a sobreposição estiver sendo exibida, o diálogo mantém o foco até ser fechado.

Como lidar com cliques e deep links

O SDK nunca abre URIs. Para lidar com o click_action e o uri de uma mensagem, implemente brazeHandleInAppMessageClick(event) na sua Scene e declare essa função na <interface> da Scene. Se ela não for declarada, o SDK não a chama.

1
2
3
4
5
6

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

O parâmetro event tem a seguinte estrutura:

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

Lembre-se do seguinte:

• O SDK chama essa função depois de remover a sobreposição e restaurar o foco. Então, você pode abrir uma nova tela a partir dela.
• Botões com click_action igual a "NONE" também chamam essa função. Verifique o click_action antes de agir.
• O SDK ignora o valor de retorno.
• O SDK não chama essa função quando o usuário fecha a mensagem com o botão de fechar ×, com o botão Voltar ou com AUTO_DISMISS.
• O SDK não chama essa função para mensagens que você renderiza com brazeHandleCustomInAppMessage.

Exemplo: Encaminhar um deep link

1. No dashboard da Braze, defina o comportamento ao clicar da mensagem ou do botão como um deep link com um URI que seu app entenda, como myapp://details/123. O SDK o entrega como click_action = "URI", com o URI em uri.
2. Em brazeHandleInAppMessageClick, analise o URI e encaminhe para a tela correspondente:

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

O valor de uri pode chegar como número, por exemplo, se o valor no dashboard for numérico. Converta-o com ToStr() antes de analisá-lo.

Renderização de mensagens específicas com uma interface personalizada

Para renderizar algumas mensagens com sua própria interface e usar a interface padrão para as demais, implemente brazeHandleCustomInAppMessage(in_app_message) na sua Scene e declare essa função na <interface> da Scene.

O SDK chama essa função para cada mensagem MODAL depois do display_delay. Retorne true se você renderizou a mensagem. Retorne false para exibi-la com a interface padrão.

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 um componente personalizado completo, consulte CustomSideBySideInAppMessage no app de exemplo torchietv no repositório do Roku SDK da Braze.

Lembre-se do seguinte:

• O SDK só chama essa função quando automatic_iam_display é true e os arquivos da interface padrão estão no seu app.
• Somente mensagens MODAL chegam a essa função.
• Sua interface personalizada é responsável por registrar impressões, cliques e cliques em botões, remover o próprio nó e restaurar o foco.
• O SDK limpa BrazeTask.BrazeInAppMessage e aplica o display_delay por conta própria. Então, não faça nenhuma dessas ações você mesmo.
• Quando uma mensagem mais recente chega, o SDK remove a sobreposição padrão antes de chamar essa função. Ele não consegue remover um layout personalizado que você renderizou antes, então remova-o na sua Scene.

Usando uma interface personalizada para todas as mensagens

Se você deixar automatic_iam_display sem definir, seu app processa todas as mensagens no app. Seu observador, sua interface e seu registro funcionam como antes do Roku SDK 2.3.0, para todos os tipos de mensagem.

Etapa 1: Adicionar um observador

Para processar mensagens no app, você pode adicionar um observador em BrazeTask.BrazeInAppMessage:

1

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

Etapa 2: Acessar as mensagens disparadas

Depois, dentro do seu manipulador, você tem acesso à mensagem no app de maior prioridade que suas Campaigns dispararam:

1
2
3
4

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

Atualização para o Roku SDK 2.3.0

O Roku SDK 2.3.0 adiciona a interface padrão. Ela vem desativada por padrão, então a atualização não muda a forma como suas mensagens no app são exibidas. Escolha um dos caminhos a seguir.

Manter sua interface personalizada

1. Substitua seus arquivos de SDK existentes pelos arquivos do diretório sdk_files da versão 2.3.0.
2. Deixe automatic_iam_display sem definir.

Seu observador, sua interface e seu registro continuam funcionando como antes, para todos os tipos de mensagem. O SDK usa os arquivos BrazeDefaultInAppMessage somente quando automatic_iam_display é true, então é seguro copiá-los junto com o restante de sdk_files.

Mudar para a interface padrão

1. Substitua seus arquivos de SDK existentes pelos arquivos do diretório sdk_files da versão 2.3.0 e adicione os arquivos BrazeDefaultInAppMessage.brs, BrazeDefaultInAppMessage.xml e BrazeDefaultInAppMessageStyles.brs a components. Seu antigo componente de exemplo BrazeInAppMessage não é alterado. Você pode excluí-lo depois de fazer a mudança.
2. Ative a interface padrão.
3. Verifique se getBrazeInstance() é chamado a partir da sua Scene.
4. Remova o tratamento de mensagens no app que você já tem:
   • O observador: m.BrazeTask.observeField("BrazeInAppMessage", "onInAppMessageReceived") e o respectivo handler
   • A criação e a anexação do seu nó de mensagem no app
   • As chamadas para LogInAppMessageImpression, LogInAppMessageClick e LogInAppMessageButtonClick
   • m.BrazeTask.BrazeInAppMessage = invalid
5. Mova o tratamento de cliques e deep links para brazeHandleInAppMessageClick.

Aviso

O SDK adiciona o próprio observador e não substitui o seu. Se você mantiver seu observador e seu registro ao ativar a interface padrão, as mensagens podem ser exibidas duas vezes, e as impressões e os cliques são registrados em dobro.

Manter alguns dos seus layouts personalizados

Siga as etapas em Mudar para a interface padrão. Depois, mova o código de renderização do seu antigo handler para brazeHandleCustomInAppMessage.

Em comparação com o seu antigo handler:

• Mantenha o registro de impressões e cliques.
• Continue removendo seu próprio nó e restaurando o foco.
• Remova m.BrazeTask.BrazeInAppMessage = invalid. O SDK faz essa limpeza.
• Remova seu próprio tratamento de display_delay. O SDK aplica esse valor.
• Somente mensagens MODAL chegam à função. Se você renderiza outros tipos de mensagem, continue usando uma interface personalizada para todas as mensagens.

Campos de mensagem

Estes campos estão disponíveis em in_app_message quando você renderiza mensagens com uma interface personalizada. A interface padrão já os aplica para você.

Tratamento

Confira a seguir os campos de que você precisa para tratar suas mensagens no app:

Importante

Em mensagens no app com botões, o click_action da mensagem também será incluído na carga útil final se a ação de clique for adicionada antes do texto do botão.

Estilo

Também há vários campos de estilo que você pode usar a partir do dashboard:

Como alternativa, você pode implementar a mensagem no app e estilizá-la no seu aplicativo Roku usando uma paleta padrão:

Botões