Personalize notificações por push

Pré-requisitos

Antes de usar este recurso, você precisará integrar o SDK Android Braze. Você também precisará configurar notificações por push.

Usando um retorno de chamada para eventos de push

A Braze fornece um retorno de chamada subscribeToPushNotificationEvents() para quando notificações por push são recebidas, abertas ou descartadas. Recomenda-se colocar este retorno de chamada no seu Application.onCreate() para não perder nenhum evento que ocorra enquanto seu aplicativo não estiver em execução.

Nota

Se anteriormente usava um Custom Broadcast Receiver para essa funcionalidade em seu aplicativo, você pode removê-lo com segurança em favor desta opção de integração.

• java
• kotlin

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
Braze.getInstance(context).subscribeToPushNotificationEvents(event -> {
  final BrazeNotificationPayload parsedData = event.getNotificationPayload();

  //
  // The type of notification itself
  //
  final boolean isPushOpenEvent = event.getEventType() == BrazePushEventType.NOTIFICATION_OPENED;
  final boolean isPushReceivedEvent = event.getEventType() == BrazePushEventType.NOTIFICATION_RECEIVED;
  // Sent when a user has dismissed a notification
  final boolean isPushDeletedEvent = event.getEventType() == BrazePushEventType.NOTIFICATION_DELETED;

  //
  // Notification data
  //
  final String pushTitle = parsedData.getTitleText();
  final Long pushArrivalTimeMs = parsedData.getNotificationReceivedTimestampMillis();
  final String deeplink = parsedData.getDeeplink();

  //
  // Custom KVP data
  //
  final String myCustomKvp1 = parsedData.getBrazeExtras().getString("my first kvp");
  final String myCustomKvp2 = parsedData.getBrazeExtras().getString("my second kvp");
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
Braze.getInstance(context).subscribeToPushNotificationEvents { event ->
    val parsedData = event.notificationPayload

    //
    // The type of notification itself
    //
    val isPushOpenEvent = event.eventType == BrazePushEventType.NOTIFICATION_OPENED
    val isPushReceivedEvent = event.eventType == BrazePushEventType.NOTIFICATION_RECEIVED
    // Sent when a user has dismissed a notification
    val isPushDeletedEvent = event.eventType == BrazePushEventType.NOTIFICATION_DELETED

    //
    // Notification data
    //
    val pushTitle = parsedData.titleText
    val pushArrivalTimeMs = parsedData.notificationReceivedTimestampMillis
    val deeplink = parsedData.deeplink

    //
    // Custom KVP data
    //
    val myCustomKvp1 = parsedData.brazeExtras.getString("my first kvp")
    val myCustomKvp2 = parsedData.brazeExtras.getString("my second kvp")
}

Dica

Com os botões de ação de notificação, as intents BRAZE_PUSH_INTENT_NOTIFICATION_OPENED são acionadas quando os botões com ações opens app ou deep link são clicados. O tratamento de deep link e extras permanece o mesmo. Os botões com ações close não disparam as intents BRAZE_PUSH_INTENT_NOTIFICATION_OPENED e descartam a notificação automaticamente.

Importante

Crie seu listener de notificação por push em Application.onCreate para garantir que ele seja disparado depois que um usuário final tocar em uma notificação enquanto o app estiver em estado finalizado.

Personalizando a exibição de notificações

Etapa 1: Crie sua fábrica de notificações personalizada

Em alguns cenários, você pode querer personalizar as notificações por push de maneiras que seriam complicadas ou não estariam disponíveis no lado do servidor. Para que você tenha controle total sobre a exibição de notificações, adicionamos a capacidade de definir seu próprio IBrazeNotificationFactory para criar objetos de notificação para serem exibidos pela Braze.

Se um IBrazeNotificationFactory personalizado for definido, a Braze chamará o método createNotification() da sua fábrica no recebimento do push antes que a notificação seja exibida ao usuário. A Braze transmitirá um Bundle contendo dados de push da Braze e outro Bundle contendo pares de chave-valor personalizados enviados por meio do dashboard ou das APIs de envio de mensagens:

A Braze passará um BrazeNotificationPayload contendo dados da notificação por push da Braze.

• java
• kotlin

1
2
3
4
5
6
7
8
9
// Factory method implemented in your custom IBrazeNotificationFactory
@Override
public Notification createNotification(BrazeNotificationPayload brazeNotificationPayload) {
  // Example of getting notification title
  String title = brazeNotificationPayload.getTitleText();

  // Example of retrieving a custom KVP ("my_key" -> "my_value")
  String customKvp = brazeNotificationPayload.getBrazeExtras().getString("my_key");
}

1
2
3
4
5
6
7
8
// Factory method implemented in your custom IBrazeNotificationFactory
override fun createNotification(brazeNotificationPayload: BrazeNotificationPayload): Notification {
  // Example of getting notification title
  val title = brazeNotificationPayload.getTitleText()

  // Example of retrieving a custom KVP ("my_key" -> "my_value")
  val customKvp = brazeNotificationPayload.getBrazeExtras().getString("my_key")
}

Você pode retornar null do seu método personalizado createNotification() para não mostrar a notificação, usar BrazeNotificationFactory.getInstance().createNotification() para obter nosso objeto padrão notification para esses dados e modificá-lo antes da exibição, ou gerar um objeto notification completamente separado para exibição.

Nota

Para obter a documentação sobre as chaves de dados push da Braze, consulte o SDK do Android.

Etapa 2: Defina sua fábrica de notificações personalizada

Para instruir a Braze a usar sua fábrica de notificações personalizada, use o método setCustomBrazeNotificationFactory para definir seu IBrazeNotificationFactory:

• java
• kotlin

1
setCustomBrazeNotificationFactory(IBrazeNotificationFactory brazeNotificationFactory);

1
setCustomBrazeNotificationFactory(brazeNotificationFactory: IBrazeNotificationFactory)

O local recomendado para definir seu IBrazeNotificationFactory personalizado é no método do ciclo de vida do aplicativo Application.onCreate() (não na atividade). Isso permitirá que a fábrica de notificações seja definida corretamente sempre que o processo do seu app estiver ativo.

Importante

Criar sua própria notificação do zero é um caso de uso avançado e deve ser feito somente com testes completos e um profundo conhecimento da funcionalidade push da Braze. Por exemplo, é preciso garantir que a notificação registre as aberturas de push corretamente.

Para cancelar a configuração personalizada do IBrazeNotificationFactory e retornar ao tratamento padrão da Braze para push, passe null para o configurador de fábrica de notificações personalizadas:

• java
• kotlin

1
setCustomBrazeNotificationFactory(null);

1
setCustomBrazeNotificationFactory(null)

Renderizando texto multicolorido

Na versão 3.1.1 do SDK da Braze, HTML pode ser enviado a um dispositivo para renderizar texto multicolorido em notificações por push.

Esse exemplo é renderizado com o seguinte HTML:

1
2
3
<p><span style="color: #99cc00;">M</span>u<span style="color: #008080;">lti</span>Colo<span style="color: #ff6600;">r</span> <span style="color: #000080;">P</span><span style="color: #00ccff;">u</span><span style="color: #ff0000;">s</span><span style="color: #808080;">h</span></p>

<p><em>test</em> <span style="text-decoration: underline; background-color: #ff6600;"><strong>message</strong></span></p>

Tenha em mente que o Android limita quais elementos e tags HTML são válidos em suas notificações por push. Por exemplo, marquee não é permitido.

Importante

A renderização de texto multicolorido é específica do dispositivo e pode não ser exibida com base no dispositivo ou versão do Android.

Para renderizar texto multicolorido em uma notificação por push, você pode atualizar seu braze.xml ou BrazeConfig:

• braze.xml
• brazeconfig

1
<bool translatable="false" name="com_braze_push_notification_html_rendering_enabled">true</bool>

1
2
3
4
BrazeConfig brazeConfig = new BrazeConfig.Builder()
  .setPushHtmlRenderingEnabled(true)
  .build();
Braze.configure(this, brazeConfig);

1
2
3
4
val brazeConfig = BrazeConfig.Builder()
    .setPushHtmlRenderingEnabled(true)
    .build()
Braze.configure(this, brazeConfig)

Tags HTML suportadas

Atualmente, o Google não lista suas tags HTML suportadas para Android diretamente em sua documentação—essa informação só pode ser encontrada no arquivo Html.java do repositório Git deles. Tenha isso em mente ao consultar a tabela a seguir, pois essa informação foi extraída deste arquivo e as tags HTML suportadas podem estar sujeitas a alterações.

Renderização de imagens inline

Como funciona

Você pode exibir uma imagem maior dentro da sua notificação por push do Android usando push de imagem inline. Com esse design, os usuários não precisarão expandir manualmente o push para ampliar a imagem. Ao contrário das notificações por push normais do Android, as imagens de push inline têm uma proporção de 3:2.

Compatibilidade

Embora você possa enviar imagens inline para qualquer dispositivo, dispositivos e SDKs que não atendem às versões mínimas exibirão uma imagem padrão. Para que as imagens inline sejam exibidas corretamente, tanto o SDK da Braze para Android v10.0.0+ quanto um dispositivo rodando Android M+ são necessários. O SDK também deve estar ativado para que a imagem seja renderizada.

Nota

Os dispositivos que executam o Android 12 serão renderizados de forma diferente devido a alterações nos estilos de notificação por push personalizados.

Enviando um push de imagem inline

Ao criar uma mensagem push para Android, esse recurso está disponível no menu suspenso Notification Type.

Configurações

Existem muitas configurações avançadas disponíveis para notificações por push do Android enviadas pelo dashboard da Braze. Este artigo descreve esses recursos e como usá-los com sucesso.

ID da notificação

Um ID de notificação é um identificador único para uma categoria de mensagem de sua escolha que informa o serviço de envio de mensagens a respeitar apenas a mensagem mais recente desse ID. Definir um ID de notificação permite que você envie apenas a mensagem mais recente e relevante, em vez de uma pilha de mensagens desatualizadas e irrelevantes.

Prioridade de entrega do Firebase Messaging

O campo Prioridade de entrega do Firebase Messaging permite que você controle se um push é enviado com prioridade “normal” ou “alta” para o Firebase Cloud Messaging.

Time to live (TTL)

O campo TTL permite que você defina um tempo personalizado para armazenar mensagens com o serviço de push. Os valores padrão para TTL são quatro semanas para FCM e 31 dias para ADM.

Texto resumido

O texto resumido permite que você defina texto adicional na visualização expandida da notificação. Ele também serve como legenda para notificações com imagens.

O texto resumido será exibido sob o corpo da mensagem na visualização expandida.

Para notificações por push que incluem imagens, o texto da mensagem será mostrado na visualização recolhida, enquanto o texto resumido será exibido como a legenda da imagem quando a notificação for expandida.

URIs personalizados

O recurso Custom URI permite que você especifique um URL da web ou um recurso do Android para navegar quando a notificação for clicada. Se nenhum URI personalizado for especificado, clicar na notificação leva os usuários para o seu app. Você pode usar o URI personalizado para fazer deep link dentro do seu app e direcionar os usuários para recursos que existem fora do seu app. Isso pode ser especificado por meio da API de envio de mensagens ou do nosso dashboard em Advanced Settings no criador de push, conforme ilustrado:

Prioridade de exibição de notificação

Importante

A configuração de prioridade de exibição de notificação não é mais usada em dispositivos com Android O ou mais recente. Para dispositivos mais novos, defina a prioridade por meio da configuração do canal de notificação.

O nível de prioridade de uma notificação por push afeta a forma como a notificação é exibida na bandeja de notificações em relação a outras notificações. Também pode afetar a velocidade e a maneira de entrega, pois mensagens normais e de baixa prioridade podem ser enviadas com uma latência ligeiramente maior ou agrupadas para preservar a vida útil da bateria, enquanto mensagens de alta prioridade são sempre enviadas imediatamente.

No Android O, a prioridade de notificação se tornou uma propriedade dos canais de notificação. Você precisará trabalhar com seu desenvolvedor para definir a prioridade de um canal durante sua configuração e, em seguida, usar o dashboard para selecionar o canal adequado ao enviar seus sons de notificação. Para dispositivos que executam versões do Android anteriores ao O, especificar um nível de prioridade para notificações do Android é possível por meio do dashboard da Braze e da API de envio de mensagens.

Para enviar mensagens para toda a sua base de usuários com uma prioridade específica, recomendamos que você especifique indiretamente a prioridade por meio da configuração do canal de notificação (para direcionar dispositivos O+) e envie a prioridade individual a partir do dashboard (para direcionar dispositivos <O).

Os níveis de prioridade que você pode definir em notificações por push do Android ou Fire OS são:

Para saber mais, consulte a documentação de notificação do Android do Google.

Sons

No Android O, os sons de notificação se tornaram uma propriedade dos canais de notificação. Você precisará trabalhar com seu desenvolvedor para definir o som de um canal durante sua configuração e, em seguida, usar o dashboard para selecionar o canal adequado ao enviar suas notificações.

Para dispositivos executando versões do Android anteriores ao O, a Braze permite que você defina o som de uma mensagem push individual por meio do criador do dashboard. Você pode fazer isso especificando um recurso de som local no dispositivo (por exemplo, android.resource://com.mycompany.myapp/raw/mysound). Especificar “default” neste campo reproduzirá o som de notificação padrão no dispositivo. Isso pode ser especificado por meio da API de envio de mensagens ou do dashboard em Advanced Settings no criador de push.

Digite o URI completo do recurso de som (por exemplo, android.resource://com.mycompany.myapp/raw/mysound) no prompt do dashboard.

Para enviar mensagens para toda a sua base de usuários com um som específico, recomendamos que você especifique indiretamente o som por meio da configuração do canal de notificação (para direcionar dispositivos O+) e envie o som individual a partir do dashboard (para direcionar dispositivos <O).