Ativação de push e inscrição de push

Este artigo de referência aborda os conceitos de ativação de push e estados de inscrição de push na Braze, incluindo as diferenças fundamentais de comportamento entre iOS, Android e Web.

Estados de inscrição push

Um “estado de inscrição por push” na Braze identifica a preferência global de um usuário quanto ao desejo de receber notificações por push. Como o estado da inscrição é baseado no usuário, ele não é específico de nenhum app individual. Os estados de inscrição tornam-se sinalizadores úteis ao decidir quais usuários devem ser direcionados para notificações por push.

Nota

O estado da inscrição push de um usuário se aplica a todo o seu perfil de usuário, que inclui todos os dispositivos do usuário.

As seguintes opções de estado de inscrição existem: Subscribed, Opted-In e Unsubscribed.

Por padrão, para que seu usuário receba suas mensagens por push, o estado de inscrição por push deve ser Subscribed ou Opted-In, e ele deve ter o push em primeiro plano ativado. Você pode substituir essa configuração, se necessário, ao criar uma mensagem.

Importante

A Braze não altera automaticamente o estado da inscrição push de um usuário para Unsubscribed. Lembre-se de que, se o estado de inscrição por push de um usuário for Unsubscribed, então o filtro Foreground Push Enabled do usuário na segmentação é false.

Registro de push e usuários contatáveis

O estado de inscrição push reflete a preferência de um usuário, mas se ele conta como contatável para push no dashboard também depende do registro de push — ou seja, um token de push em primeiro plano válido no perfil. Para saber como a Braze calcula as contagens por canal, consulte Medir o tamanho do segmento.

• Campaigns e Canvas de push: Usuários que não estão registrados para push não são incluídos em Usuários contatáveis para Push para Android ou Push para iOS nas estatísticas de público, mesmo quando o estado de inscrição push é Subscribed ou Opted-In.
• Outros canais: Os mesmos usuários ainda podem contar como contatáveis para outros canais para os quais se qualificam (por exemplo, e-mail ou mensagens no app).
• Segments: A associação ao segmento segue seus filtros. Usuários sem registro de push permanecem no segmento, a menos que um filtro os exclua (por exemplo, Foreground Push Enabled). A associação total ao segmento pode ser maior do que a soma de usuários exibidos nas linhas de Usuários contatáveis específicas de push.

Um perfil de usuário pode exibir o estado de inscrição push Subscribed sem que nenhum token de push esteja atribuído. Esses usuários ainda não contam para Usuários contatáveis para Push para Android ou Push para iOS até que a Braze registre um token válido.

Para definições de filtros, consulte Filtros de segmentação.

Atualização dos estados de inscrição push

Veja a seguir as maneiras de atualizar o estado de inscrição por push de um usuário:

Aceitação automática (padrão)

Por padrão, a Braze define o estado da inscrição push de um usuário como Opted-In quando ele autoriza pela primeira vez as notificações por push para o seu app. A Braze também faz isso quando um usuário reativa as permissões push nas configurações do sistema após tê-las desativado anteriormente.

• android
• swift

1

<bool name="com_braze_optin_when_push_authorized">false</bool>

1
2
3
4

configuration.optInWhenPushAuthorized = false // disables the default behavior

let braze = Braze(configuration: configuration)
AppDelegate.braze = braze

Integração SDK

Você pode atualizar o estado da inscrição de um usuário com o SDK da Braze usando o método setPushNotificationSubscriptionType na Web, Android ou iOS. Por exemplo, você pode usar esse método para criar uma página de configurações no seu app em que os usuários possam ativar ou desativar manualmente as notificações por push.

REST API

Você pode atualizar o estado de inscrição de um usuário com a REST API da Braze usando o endpoint /users/track para atualizar o atributo push_subscribe.

Diferenças entre ativação de push e estado de inscrição push

A ativação de push refere-se a se um usuário concedeu permissão em nível de sistema operacional ou navegador para receber notificações em um dispositivo específico. O estado de inscrição push é uma configuração em nível da Braze que representa a preferência global de um usuário para receber push em todo o seu perfil.

Quando a aceitação automática está ativada (o padrão), a Braze atualiza o estado de inscrição push de um usuário para Opted-In quando ele autoriza as notificações por push para o seu app ou reativa as permissões nas configurações do sistema (por exemplo, no iOS, Android 13+ e navegadores web compatíveis). Caso contrário, o estado de inscrição push do usuário permanece Subscribed até que você o altere explicitamente usando um método do SDK ou uma chamada à REST API.

A Braze não altera automaticamente o estado de inscrição push de um usuário para Unsubscribed quando ele desativa as notificações no nível do sistema operacional, navegador ou app. Para atualizar o estado de inscrição push de um usuário, você deve atualizá-lo na Braze. Por exemplo, se um usuário desativar o push em uma Central de Preferências no app, atualize o estado de inscrição push para Unsubscribed na Braze. A Braze não atualiza perfis de usuários com base na sua Central de Preferências. Para alinhar os estados de inscrição com as preferências do usuário no app, chame os métodos apropriados usando o SDK (iOS ou Android) ou a REST API. Para mais informações, consulte Atualização dos estados de inscrição push.

Tokens de push importados (iOS)

Quando você importa tokens de push do iOS com push_token_import, o estado de inscrição push do usuário normalmente é Subscribed até que ele registre uma sessão no seu app integrado com a Braze. Após a primeira sessão, a Braze pode atualizar o estado para Opted-In se a aceitação automática se aplicar (por exemplo, quando o usuário autoriza o push no iOS e optInWhenPushAuthorized está ativado).

Revise as Configurações de contato no perfil do usuário após a importação e novamente após a primeira sessão do usuário no app para confirmar o estado esperado.

Verificação do estado de inscrição push

Você pode verificar o estado de inscrição por push de um usuário com a Braze de qualquer uma das seguintes maneiras:

• Perfil do usuário: Você pode acessar perfis de usuários individuais por meio do dashboard da Braze na página Pesquisa de usuários. Depois de encontrar o perfil de um usuário (por meio de endereço de e-mail, número de telefone ou ID de usuário externo), é possível selecionar a guia Engagement para visualizar e ajustar manualmente o estado da inscrição de um usuário.
• Exportação da REST API: Você pode exportar perfis de usuários individuais em formato JSON usando os endpoints de exportação Usuários por segmento ou Usuários por identificador. A Braze retorna um objeto de tokens de push que contém informações de ativação de push por dispositivo.

Onde o registro e o status de push aparecem

Você pode verificar o estado de inscrição de push, o registro e a ativação em três locais principais na Braze:

1. Perfis de usuário na guia Engagement
2. Segmentação no criador de segmentos
3. Analytics de Campaign e Canvas na página de análise de dados de cada mensagem

Perfis de usuário e changelog de push

No perfil de um usuário (Pesquisar usuários > selecione o usuário > guia Engagement), Contact Settings lista o estado de inscrição de push, Push Registered For (quais apps e plataformas a Braze pode usar para enviar push em primeiro plano para aquele perfil) e o Push Changelog para movimentações de token, erros e atualizações de registro. Para saber como interpretar Push Registered For e a autorização de primeiro plano versus segundo plano, consulte Verificando o status de registro de push.

No iOS e Android, quando um dispositivo passa de autorização de push em primeiro plano para apenas segundo plano (por exemplo, depois que o usuário desativa notificações nas configurações do sistema e o SDK reporta a mudança), o changelog de push pode incluir uma entrada como “token por push was updated from foreground push enabled to foreground push disabled”.

Depois de esperar novos dados do SDK (por exemplo, logo após uma sessão de teste), selecione Refresh no perfil do usuário se os valores parecerem desatualizados. Pode haver um pequeno atraso entre o envio dos dados pelo SDK e a atualização do perfil com o registro de push mais recente.

Para usuários que você adiciona a um grupo interno, selecione Record User Events for group members nas Internal Group Settings daquele grupo para que as solicitações do SDK apareçam no registro. Em seguida, abra o Registro de usuários de eventos em Settings > Event User Log, encontre as solicitações do SDK do usuário e expanda a carga útil bruta. Você pode inspecionar campos como remote_notification_enabled ao validar se o dispositivo reporta notificações remotas como ativadas ou desativadas.

Segmentação e filtros de push

No criador de segmentos, use filtros como Foreground Push Enabled, Foreground Push Enabled for App, Background or Foreground Push Enabled e filtros de inscrição de push para segmentar ou auditar usuários por preferência e autorização no nível do dispositivo. No iOS, como esses filtros são interpretados para um determinado usuário depende de ele ter concluído o prompt do SO, alterado configurações ou usar autorização provisória; consulte Ações do usuário no iOS e status de push e Outros cenários específicos de plataforma.

Analytics de Campaign e Canvas

Na página de análise de dados de uma Campaign ou Canvas de push, métricas como Enviadas, Bounces e Aberturas refletem a entrega e o engajamento daquele envio. Para cruzar esses números com perfis individuais, exporte os destinatários em Campaign Details ou Canvas Details usando User Data (CSV). Para etapas e permissões, consulte Exportar dados de Campaign e Exportar dados de Canvas. Se as contagens entre a análise de dados e uma exportação não coincidirem, consulte Analytics de Campaign e Canvas na solução de problemas de exportação.

Ações do usuário no iOS e status de push

A tabela a seguir mostra como diferentes ações do usuário afetam a ativação de push no iOS, o registro de push em primeiro ou segundo plano e o status de inscrição de push na Braze. Quando um usuário instala seu app e inicia a primeira sessão, o estado geralmente é o mostrado na primeira linha. Cada ação subsequente pode atualizar alguns desses valores, mas não outros.

^{* Se o app não usar push provisório, Foreground Push Enabled será false até que o usuário permita notificações por push. Se o app usar push provisório, Foreground Push Enabled será true no início da primeira sessão. Para saber mais, consulte Autorização provisória e push silencioso.}

^{** A partir da versão 7.5.0 do Braze Swift SDK, a propriedade de configuração optInWhenPushAuthorized controla se o estado de inscrição de push é automaticamente definido como Opted-In quando a permissão de push é autorizada. Para saber mais, consulte Tokens de push.}

Permissão de push

Todas as plataformas com push habilitado — iOS, web e Android — exigem aceitação explícita por meio de um prompt do sistema no nível do SO, com algumas pequenas diferenças descritas na seção a seguir.

Como a decisão do usuário é final e não é possível perguntar novamente após uma recusa, usar mensagens no app de push primer é uma estratégia importante para aumentar suas taxas de aceitação.

Prompts nativos de permissão de push do SO

Plataforma	Captura de tela	Descrição
iOS		Isso não se aplica ao solicitar permissão de push provisório.
Android		Essa permissão de push foi introduzida no Android 13. Antes do Android 13, não era necessária permissão para enviar push.
Web

Android

Antes do Android 13, não era necessária permissão para enviar notificações por push. No Android 12 e versões anteriores, todos os usuários são considerados Subscribed na primeira sessão, quando a Braze solicita automaticamente um token por push. Nesse ponto, o usuário está habilitado para push com um token por push válido para aquele dispositivo e um estado de inscrição padrão de Subscribed.

A partir do Android 13, a permissão de push deve ser solicitada e concedida pelo usuário. Seu app pode solicitar manualmente a permissão do usuário em momentos oportunos, mas, caso contrário, os usuários serão solicitados automaticamente quando seu app criar um canal de notificação.

iOS

Seu app pode solicitar push provisório ou push autorizado.

O push autorizado exige permissão explícita do usuário antes de enviar qualquer notificação, enquanto o push provisório permite enviar notificações silenciosamente, diretamente para a central de notificações sem nenhum som ou alerta.

Autorização provisória e push silencioso

Antes do iOS 12 (lançado em 2018), todos os usuários precisavam aceitar explicitamente para receber notificações por push.

No iOS 12, a Apple introduziu a autorização provisória, permitindo que marcas enviem notificações por push silenciosas para a central de notificações dos usuários antes de eles aceitarem explicitamente, oferecendo a chance de demonstrar o valor das suas mensagens desde cedo. Consulte autorização provisória para saber mais.

Web

Para web, você deve solicitar a aceitação explícita do usuário por meio do diálogo nativo de permissão do navegador.

Diferentemente do iOS e do Android, que permitem que seu app exiba o prompt de permissão a qualquer momento, alguns navegadores modernos só exibem o prompt quando acionados por um “gesto do usuário” (clique do mouse ou pressionamento de tecla). Se o seu site tentar solicitar permissão de notificação por push no carregamento da página, provavelmente será ignorado ou silenciado pelo navegador.

Por isso, você deve solicitar permissão somente quando o usuário clicar em algum lugar do seu website, e não aleatoriamente quando uma página for carregada.

Tokens por push

Tokens por push são identificadores anônimos e exclusivos gerados pelo dispositivo de um usuário e enviados à Braze para identificar para onde enviar a notificação de cada destinatário.

Existem duas formas de classificar um token por push que são essenciais para entender como uma notificação por push pode ser enviada aos seus usuários.

1. Push em primeiro plano permite enviar notificações por push regulares e visíveis para o primeiro plano do dispositivo de um usuário.
2. Push em segundo plano está disponível independentemente de o dispositivo ter aceitado receber notificações por push da marca. O push em segundo plano permite que as marcas enviem notificações por push silenciosas — notificações que intencionalmente não são exibidas — para dispositivos, a fim de dar suporte a funcionalidades essenciais como o Uninstall Tracking.

Quando um perfil de usuário possui um token por push de primeiro plano válido associado a um app, a Braze considera o usuário como “registrado para push” naquele app. A Braze então disponibiliza um filtro de segmentação específico, Foreground Push Enabled for App, para ajudar a identificar esses usuários. Esse filtro identifica usuários registrados para push em um app, mas não restringe qual app recebe a mensagem. Para restringir a entrega a apps específicos, use um Segment que tenha Apps and websites targeted definido como Users from specific apps. Em um Canvas, adicione esse Segment às validações de entrega de cada etapa de mensagem.

Nota

O filtro Foreground Push Enabled for App considera apenas a presença de um token por push de primeiro plano e segundo plano válido para o app em questão. No entanto, o filtro mais genérico Foreground Push Enabled segmenta usuários que ativaram explicitamente as notificações por push para qualquer app no seu espaço de trabalho. Essa contagem inclui apenas push de primeiro plano e não inclui usuários que cancelaram a inscrição. Para saber mais sobre esses e outros filtros, consulte Filtros de segmentação.

Para uma pequena porcentagem de usuários, atrasos no processamento podem causar uma incompatibilidade temporária: um usuário pode ter um token por push de primeiro plano válido em seu perfil, mas ainda não corresponder ao filtro Foreground Push Enabled. O perfil pode mostrar brevemente que o push de primeiro plano não está ativado, mesmo que o token esteja presente. Isso geralmente se resolve assim que o processamento é concluído.

Múltiplos usuários em um único dispositivo

Os tokens por push são específicos tanto para o dispositivo quanto para o app, por isso não é possível usar tokens por push para distinguir entre múltiplos usuários que utilizam o mesmo dispositivo.

Por exemplo, digamos que você tenha dois usuários: Charlie e Kim. Se Charlie ativou as notificações por push do seu app no celular dele e Kim usa o celular de Charlie para sair do perfil dele e entrar no dela, o token por push será reatribuído ao perfil de Kim. O token por push permanecerá atribuído ao perfil de Kim naquele dispositivo até que ela saia e Charlie faça login novamente.

Um app ou website pode ter apenas uma inscrição de push por dispositivo. Então, quando um usuário sai de um dispositivo ou website e um novo usuário faz login, o token por push é reatribuído ao novo usuário. Isso é refletido no perfil do usuário, na seção Contact Settings da guia Engagement:

Como não há uma forma de os provedores de push (APNs/FCM) distinguirem entre múltiplos usuários em um único dispositivo, o token por push é passado ao último usuário que fez login para determinar qual usuário será o alvo no dispositivo para push.

Múltiplos dispositivos e um único usuário

O estado da inscrição de push é baseado no usuário e não é específico de nenhum app individual. O estado da inscrição de push é o último valor definido. Portanto, se um usuário aceitou receber notificações por push, o estado da inscrição de push dele será Opted-In em todos os dispositivos elegíveis. Se o usuário posteriormente cancelar explicitamente a inscrição de notificações por push por meio do seu aplicativo ou de outros métodos que a sua marca disponibilize, o estado da inscrição de push dele será atualizado para Unsubscribed e nenhum dispositivo registrado para push poderá receber notificações por push.

Filtro Foreground Push Enabled

Foreground Push Enabled é um filtro de segmentação na Braze que permite que profissionais de marketing identifiquem facilmente usuários que permitem que a Braze envie notificações por push e usuários que não expressaram preferências para não receber notificações por push.

O filtro Foreground Push Enabled leva em consideração o seguinte:

• A capacidade da Braze de enviar uma notificação por push (token de push de primeiro plano)
• A preferência geral do usuário de receber push em qualquer um dos seus dispositivos (estado de inscrição de push)

Um usuário é considerado “com push ativado” ou “registrado para push” se tiver um token de push de primeiro plano ativo para um app dentro do seu espaço de trabalho, o que significa que o status de ativação de push é específico do app.

Nota

Para informações sobre como verificar o estado de registro de push, visite status de registro de push

Encontrando informações de registro de push e changelog

No dashboard, você pode encontrar informações sobre registro de push e changelogs de push em:

• Segmentação – Filtre por estados de inscrição dos usuários, estado ativado e estado ativado em primeiro e segundo plano.
• Análise de dados de Campaign – Visualize estatísticas de push e feedback para uma única Campaign ou Canvas.
• Perfil de usuário (guia Engajamento) – Visualize as Configurações de contato e o changelog de push para um usuário específico.

Ao revisar o estado de push ativado, Push registrado para indica para quais plataformas a Braze pode enviar push em primeiro plano para aquele usuário. No iOS e Android, se um usuário mudou de push em primeiro plano ativado para push em segundo plano ativado (remote_notification_enabled), isso será documentado no changelog de push como “Push token was updated from foreground push enabled to foreground push disabled.”

Se o usuário for adicionado como usuário teste, em Console de desenvolvedor > Registro de usuários de eventos, o perfil de usuário exibirá uma solicitação do SDK com remote_notification_enabled como true ou false. Pode ser necessário atualizar o perfil de usuário para visualizar as atualizações, já que há um pequeno atraso para que as atualizações do SDK cheguem ao perfil de usuário.

Filtros de segmentação para estado de push no iOS:

• Push em primeiro plano e segundo plano desativados no iOS: O usuário ainda não recebeu um pedido de permissão de push.
• Segundo plano ativado no iOS: O usuário recebeu o pedido de permissão de push e recusou, ou aceitou e depois desativou as notificações por push nas configurações do dispositivo (refletido após o usuário ter uma sessão).
• Primeiro plano ativado no iOS: O usuário recebeu o pedido de permissão de push e está elegível para receber push em primeiro plano.

A análise de dados de Campaign refletirá as estatísticas de push em linha com os detalhes anteriores nesta seção. Você também pode baixar os perfis de usuários que entraram na Campaign ou Canvas para fazer referência cruzada com os perfis de usuários.

Outros cenários específicos por plataforma

• web
• android
• ios

Quando um usuário aceita o pedido nativo de permissão para push, o status de inscrição dele será alterado para opted in.

Para gerenciar inscrições, você pode usar o método de usuário setPushNotificationSubscriptionType para criar uma página de configurações de preferências no seu site. Depois disso, você pode filtrar usuários por status de cancelamento no dashboard.

Se um usuário desativar as notificações no navegador, a próxima notificação por push enviada a esse usuário sofrerá bounce, e a Braze atualizará o token por push do usuário de acordo. Isso é usado para gerenciar a elegibilidade dos filtros de push ativado (Background or Foreground Push Enabled, Foreground Push Enabled e Foreground Push Enabled for App). O status de inscrição definido no perfil do usuário é uma configuração em nível de usuário e não muda quando um push sofre bounce.

Erros 410 de token de web push {#410-web-push-token-errors}

Se você receber um erro 410: Gone, isso pode ocorrer quando um usuário desativa as notificações por web push no navegador, nas configurações do sistema operacional, ou se ele está fazendo login como um usuário diferente no mesmo dispositivo, ou se o usuário não visitou o website há algum tempo.

Se você receber um erro 410: Endpoint Not Valid, isso pode significar que o token de web push (essencialmente a URL) expirou. Isso pode ocorrer se o usuário nunca mais visitar o site ou se o navegador invalidar o token. Também pode ocorrer periodicamente (geralmente a cada poucos meses), dependendo do navegador. Quando o usuário visitar o site novamente, se ele ainda tiver o navegador configurado para “Permitir”, a Braze coletará automaticamente um token novo para o dispositivo. Isso pressupõe que a opção de inicialização disablePushTokenMaintenance não esteja sendo usada durante a inicialização do SDK.

Nota

Plataformas web não permitem push em segundo plano ou silencioso.

Se um usuário com push em primeiro plano ativado desativar o push nas configurações do sistema operacional, no início da próxima sessão:

• A Braze o marcará como push em primeiro plano desativado e não tentará mais enviar mensagens push para ele.
• O filtro Foreground Push Enabled for App (Android) e o filtro de segmentação Foreground Push Enabled (supondo que nenhum outro app no perfil do usuário tenha um token de push em primeiro plano válido) retornarão false.

Nesse cenário, como um token de push em segundo plano ainda existirá, você pode continuar enviando notificações por push em segundo plano (silenciosas) com o filtro de segmentação Background or Foreground Push Enabled = true.

Para Android, a Braze considerará um usuário com push desativado se:

• O usuário desinstalar o app do dispositivo.
• Uma mensagem push não for entregue devido a um bounce. Isso geralmente é causado por uma desinstalação, mas também pode ser devido a atualizações do app, nova versão do token por push ou formato.
• O registro de push falhar no Firebase Cloud Messaging (às vezes causado por conexões de rede instáveis ou uma falha ao conectar ao FCM para retornar um token válido).
• O usuário bloquear as notificações por push do app nas configurações do dispositivo e, em seguida, registrar uma sessão.

Nota

Você só pode interceptar uma notificação por push do Android quando o app está em primeiro plano ou em segundo plano (mas ainda em execução). Não é possível interceptar notificações quando o app está encerrado ou completamente finalizado.

Independentemente de o usuário aceitar ou não o pedido de aceitação de push em primeiro plano, você ainda poderá enviar push em segundo plano se tiver as notificações remotas ativadas no Xcode e seu app chamar registerForRemoteNotifications().

Se o seu app tiver autorização provisória ou o usuário tiver aceitado o push, ele receberá um token de push em primeiro plano, permitindo que você envie todos os tipos de push. Na Braze, consideramos que um usuário no iOS com push em primeiro plano ativado está com push ativado, seja explicitamente (nível do app) ou provisoriamente (nível do dispositivo).

Se um usuário recusar receber notificações por push no nível do sistema operacional, o status de inscrição de push dele será Subscribed, e o perfil dele não mostrará que um token de push em primeiro plano foi registrado.

No cenário em que um usuário que inicialmente aceitou no nível do sistema operacional desativa as notificações por push nas configurações do sistema operacional, no início da próxima sessão, o seguinte ocorrerá:

• A Braze o marcará como push em primeiro plano desativado e não tentará mais enviar mensagens push.
• O filtro Foreground Push Enabled for App (iOS) e o filtro de segmentação Foreground Push Enabled (supondo que nenhum outro app no perfil do usuário tenha um token de push em primeiro plano válido) retornarão false.

Nesse cenário, como um token de push em segundo plano ainda existirá, você pode continuar enviando notificações por push em segundo plano (silenciosas) com o filtro de segmentação Background or Foreground Push Enabled = true.

Nota

O iOS não permite que apps interceptem uma notificação por push antes de ela ser exibida. Isso significa que os apps (e a Braze) não têm controle sobre a exibição ou ocultação da notificação. Um usuário pode desativar as notificações por push de um app nas configurações do dispositivo, mas isso é controlado pelo sistema operacional.

Práticas recomendadas

Consulte nosso artigo dedicado sobre Práticas recomendadas de push para orientações detalhadas sobre como otimizar o uso de push na Braze.