Notificações push no Android com o FCM

Como funciona

O app, com o SDK do Firebase Messaging, recebe um token de registro: o endereço daquele app naquele aparelho. Quem envia manda a notificação para o FCM pela API HTTP v1, autenticando com uma conta de serviço do projeto Firebase. O Google entrega ao aparelho.

O que você precisa

• Um projeto no Firebase com o seu app Android cadastrado.
• O SDK do Firebase Messaging no app, para obter o token de registro.
• O arquivo JSON de uma conta de serviço do projeto.
• No Android 13 ou mais recente, pedir a permissão POST_NOTIFICATIONS ao usuário. Sem ela, o aparelho não mostra as notificações.

Conectar o FCM ao vivapush

1. No Firebase Console, abra Configurações do projeto → Contas de serviço e gere uma nova chave privada. O Firebase baixa um arquivo JSON.
2. No painel do vivapush, abra as credenciais do app e envie esse JSON no canal Android.
3. O vivapush testa a conta com um envio de validação (sem notificação real) aceito pelo FCM e mostra o resultado.

A chave fica criptografada e nunca aparece por inteiro. Se o Google recusar a conta de serviço mais tarde, a credencial é marcada como inválida e o aviso aparece no monitor de envio, em vez de virar uma fila de tentativas.

Se você não tem esse arquivo, convide quem desenvolve o app pelo painel. Essa pessoa recebe acesso só para conectar os canais.

Registrar o aparelho

O vivapush não tem um SDK nativo para Android. O app fala com a API pública em poucas chamadas, usando a chave pública do app (começa com vp_pub_), que só registra aparelhos e não envia nada.

POST /api/v1/devices
X-VivaPush-App-Key: vp_pub_...

{
  "installation_id": "inst-123456",
  "platform": "android",
  "token": "token de registro do FCM",
  "external_user_id": "cliente-42",
  "language": "pt-BR", "country": "BR", "timezone": "America/Sao_Paulo",
  "push_opt_in": true
}

O registro é idempotente por installation_id: se o FCM trocar o token (o SDK avisa em onNewToken), registre de novo e o token novo substitui o antigo da mesma instalação. Quando o app for aberto, chame POST /api/v1/devices/activity para contar o usuário como ativo no mês.

O que chega ao app

Cada notificação leva título, mensagem e, se houver, imagem grande. Nos dados extras vão vp_nid (o ID da notificação), vp_url (o que abrir ao tocar) e os campos que você definir.

Com o app em segundo plano, o Android mostra a notificação sozinho. Com o app aberto, o SDK do Firebase entrega a mensagem ao seu código, que decide o que mostrar.

Prioridade alta serve para avisos urgentes; a normal deixa o sistema economizar bateria. O tempo de validade (TTL) define por quanto tempo o FCM tenta entregar a um aparelho desligado.

Confirmar entrega e aberturas

Quando o app recebe ou abre uma notificação, chame POST /api/v1/events com o vp_nid e o tipo ("delivered", "opened" ou "clicked"). Essa é a única fonte de “chegou ao dispositivo” no vivapush: “aceita para entrega” só diz que o FCM recebeu a mensagem.

Quando o FCM informa que um token não existe mais (por exemplo, o app foi desinstalado), o aparelho é marcado como sem receber e o webhook subscriptions.invalidated avisa o seu sistema.

Perguntas frequentes