Skip to content

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.

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.

Estado de aceitação Descrição
Subscribed Estado padrão da inscrição push quando um perfil de usuário é criado na Braze.
Opted-In Um usuário expressou explicitamente uma preferência por receber notificações por push. A Braze move automaticamente o estado de aceitação de um usuário para Opted-In se o usuário aceitar um prompt de push em nível de sistema operacional.

Isso não se aplica a usuários do Android 12 ou inferior.
Unsubscribed Um usuário cancelou explicitamente a inscrição de push por meio do seu app ou outros métodos fornecidos pela sua marca. Por padrão, as Campaigns de push da Braze visam apenas usuários que estão Subscribed ou Opted-in para push.

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.

Para desativar esse comportamento padrão, adicione a seguinte propriedade ao arquivo braze.xml do seu projeto do Android Studio:

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

A partir da versão 7.5.0 do Braze Swift SDK, você pode desativar ou personalizar ainda mais esse comportamento adicionando a configuração optInWhenPushAuthorized ao arquivo AppDelegate.swift do seu projeto Xcode:

1
2
3
4
configuration.optInWhenPushAuthorized = false // disables the default behavior

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

Integração de 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.

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

Perfil de usuário de John Doe com o estado de inscrição push definido como Subscribed.

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 “Push token 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.

Ação do usuário Foreground Push Enabled Foreground Push Enabled for App Tipo de registro de push Status de inscrição de push
O usuário instala o app e registra uma sessão false* Não atualizado Segundo plano Subscribed
O usuário recebe o prompt nativo de push do iOS e seleciona Allow true true Primeiro plano Opted-In**
O usuário recebe o prompt nativo de push do iOS e seleciona Don’t Allow false Não atualizado Segundo plano Não atualizado
O usuário ativa push nas configurações do dispositivo e registra uma sessão true true Primeiro plano Opted-In**
O usuário desativa push nas configurações do dispositivo e registra uma sessão false false Segundo plano Não atualizado
O usuário exclui o app Não atualizado Atualizado quando o token de push é retirado Atualizado quando o token de push é retirado Não atualizado

* 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 Atualizando estados de inscrição de push.

Permissão de push

Todas as plataformas com push ativado — iOS, Web e Android — exigem opt-in explícito por meio de um prompt do sistema no nível do SO, com algumas pequenas diferenças descritas abaixo.

Como a decisão do usuário é final e você não pode perguntar novamente após uma recusa, usar mensagens no app de push primer é uma estratégia importante para aumentar suas taxas de opt-in.

Prompts nativos de permissão de push do SO

Plataforma Captura de tela Descrição
iOS Um prompt nativo de push do iOS perguntando "My App would like to send you notifications" com dois botões, "Don't Allow" e "Allow" na parte inferior da mensagem. Isso não se aplica ao solicitar permissão de push provisório.
Android Uma mensagem de push do Android perguntando "Allow Kitchenerie to send you notifications?" com dois botões, "Allow" e "Don't allow" na parte inferior da mensagem. Essa permissão de push foi introduzida no Android 13. Antes do Android 13, a permissão não era necessária para enviar push.
Web Um prompt nativo de push do navegador web perguntando "Braze.com wants to show notification" com dois botões, "Block" e "Allow" na parte inferior da mensagem.  

Android

Antes do Android 13, a permissão não era necessária 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 de push. Nesse ponto, o usuário está com push ativado com um token de 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 ao 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

Uma notificação na central de notificações do sistema com uma mensagem na parte inferior perguntando "Keep receiving notifications from the Yachtr app?" com dois botões abaixo para "Keep" ou "Turn Off"

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 som ou alerta.

Autorização provisória e push silencioso

Antes do iOS 12 (lançado em 2018), todos os usuários precisavam fazer opt-in explícito 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 que eles façam opt-in explícito, dando a você a chance de demonstrar o valor das suas mensagens antecipadamente. Consulte autorização provisória para saber mais.

Navegador web

Para Web, você deve solicitar opt-in explícito 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ó exibirão o prompt se acionado por um “gesto do usuário” (clique do mouse ou pressionamento de tecla). Se 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 apenas quando o usuário clicar em algum lugar do seu site, e não aleatoriamente quando uma página carregar.

Tokens de push

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

Existem duas formas de classificar um token de 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 oferece a capacidade de enviar notificações por push regulares e visíveis para o primeiro plano do dispositivo do usuário.
  2. Push em segundo plano está disponível independentemente de um dispositivo específico ter feito opt-in para receber notificações por push daquela marca. O push em segundo plano permite que 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 rastreamento de desinstalação.

Quando um perfil de usuário tem um token de 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 fornece um filtro de segmentação específico, Foreground Push Enabled for App, para ajudar a identificar esses usuários.

Múltiplos usuários em um dispositivo

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

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

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

Changelog do token de push na guia Engagement do perfil de um usuário, que lista quando o token de push foi movido para outro usuário e qual era o token.

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

Múltiplos dispositivos e um usuário

O estado de inscrição de push é baseado no usuário e não é específico de nenhum app individual. O estado de inscrição de push é o valor que foi definido por último. Então, se um usuário fez opt-in para notificações por push, seu estado de inscrição de push será Opted-In em todos os dispositivos elegíveis. Se um usuário posteriormente cancelar explicitamente a inscrição de notificações por push por meio do seu aplicativo ou outros métodos que sua marca oferece, seu estado de inscrição de push 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)

Uma captura de tela do dashboard mostrando que um usuário está "Push Registered for Marketing (iOS)"

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.

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 de ativação e estado de ativação em primeiro e segundo plano.
  • Analytics de Campaign – Visualize estatísticas de push e feedback para uma única Campaign ou Canvas.
  • Perfil do usuário (guia Engagement) – Visualize Contact Settings e o changelog de push para um usuário específico.

Ao revisar o estado de push ativado, Push Registered for indica para quais plataformas a Braze pode enviar push em primeiro plano para aquele usuário. No iOS e Android, se um usuário passou de push de primeiro plano ativado para push de 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 > Event User Log, o perfil do usuário mostrará uma solicitação do SDK com remote_notification_enabled como true ou false. Pode ser necessário atualizar o perfil do usuário para visualizar as atualizações, pois há um pequeno atraso para que as atualizações do SDK cheguem ao perfil do usuário.

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

  • Push de primeiro plano e segundo plano desativado no iOS: O usuário ainda não recebeu um prompt de push.
  • Push de segundo plano ativado no iOS: O usuário recebeu o prompt de push e disse não, ou disse sim e depois desativou notificações por push nas configurações do dispositivo (refletido após o usuário ter uma sessão).
  • Push de primeiro plano ativado no iOS: O usuário recebeu o prompt 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 de acordo com os detalhes acima. 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 de plataforma

Quando um usuário aceita o prompt nativo de permissão de push, seu status de inscrição 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, após o que você pode filtrar usuários por status de descadastramento no dashboard.

Se um usuário desativar notificações no navegador, a próxima notificação por push enviada a esse usuário sofrerá bounce, e a Braze atualizará o token de push do usuário de acordo. Isso é usado para gerenciar a elegibilidade para os 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 no nível do usuário e não muda quando um push sofre bounce.

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

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

Se você receber um erro 410: Endpoint Not Valid, isso pode significar que o token de push para web (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 ainda tiver o navegador configurado como “Allow”, a Braze coletará automaticamente um novo token 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.

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

  • A Braze o marca como push de primeiro plano desativado e não tenta mais enviar mensagens push.
  • O filtro Foreground Push Enabled for App (Android) e o filtro de segmentação Foreground Push Enabled (assumindo que nenhum outro app no perfil do usuário tenha um token de push de 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 falhar na entrega 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 de push ou formato.
  • O registro de push falhar no Firebase Cloud Messaging (às vezes causado por conexões de rede ruins ou falha ao conectar ao FCM ou ao FCM retornar um token válido).
  • O usuário bloquear notificações por push para o app nas configurações do dispositivo e, em seguida, registrar uma sessão.

Independentemente de o usuário aceitar o prompt de opt-in de push em primeiro plano, você ainda poderá enviar push em segundo plano se tiver notificações remotas ativadas no Xcode e seu app chamar registerForRemoteNotifications().

Se seu app tiver autorização provisória ou o usuário tiver feito opt-in para push, ele receberá um token de push de primeiro plano, permitindo que você envie todos os tipos de push. Na Braze, consideramos um usuário no iOS que está com push de primeiro plano ativado como 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 SO, seu estado de inscrição de push será Subscribed, e seu perfil não mostrará que um token de push de primeiro plano foi registrado.

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

  • A Braze o marca como push de primeiro plano desativado e não tenta mais enviar mensagens push.
  • O filtro Foreground Push Enabled for App (iOS) e o filtro de segmentação Foreground Push Enabled (assumindo que nenhum outro app no perfil do usuário tenha um token de push de 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.

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.

New Stuff!