Como enviar notificações push para sites

Como a notificação chega ao navegador

Quem envia não fala direto com o computador ou o celular. Cada navegador tem o seu serviço de push (do Google, da Mozilla, da Apple ou da Microsoft). Quando alguém aceita receber notificações, o navegador cria uma inscrição com um endereço desse serviço. O envio vai para esse endereço, criptografado, e o serviço entrega ao navegador.

No aparelho, quem recebe e mostra a notificação é um service worker: um pequeno arquivo JavaScript do seu site que o navegador mantém registrado.

O que o seu site precisa

• HTTPS. Navegadores só liberam Web Push em páginas seguras (localhost funciona para testes).
• Um service worker publicado na raiz do seu domínio.
• Um pedido de permissão feito depois de uma ação da pessoa, como um clique num botão. Pedir ao abrir a página costuma ser bloqueado ou recusado.
• Um par de chaves VAPID, que identifica quem está enviando para os serviços de push.

Navegadores atendidos

Chrome, Edge, Firefox e Safari, no computador e no Android. No iPhone e no iPad, o Safari recebe notificações de sites a partir do iOS 16.4, desde que a pessoa adicione o site à tela de início.

Chaves VAPID: quem gera e onde ficam

Ao ativar o canal Web de um app, o vivapush gera o par de chaves VAPID. A chave privada fica criptografada e nunca aparece por inteiro no painel. A chave pública é entregue ao navegador pelo script do site. Você informa um contato (e-mail ou endereço do site) que os serviços de push podem usar para falar com você.

Uma inscrição fica ligada à chave VAPID com que foi criada. Se a chave mudar, quem já estava inscrito precisa aceitar de novo. Por isso, não troque a chave sem necessidade.

Passo a passo com o vivapush

1. Crie o app no painel e ative o canal Web. As chaves VAPID são geradas nessa hora.
2. Autorize o domínio do site e prove que ele é seu: publique o arquivo /.well-known/vivapush-verification.txt com o código ou crie o registro DNS TXT _vivapush.<seu domínio>. Endereços locais, como localhost, são verificados automaticamente.
3. Copie o service worker de /sdk/vivapush-sw.js e publique na raiz do seu domínio, como /vivapush-sw.js.
4. Carregue o script no site e chame VivaPush.init com a chave pública do app (começa com vp_pub_).
5. Chame VivaPush.subscribe num clique de botão. O script pede a permissão, cria a inscrição e registra o navegador com fuso, idioma e navegador.
6. Depois do login, chame VivaPush.setUser com o ID do cliente no seu sistema para poder enviar a uma pessoa específica.

<script src="https://vivapush.com/sdk/vivapush.js"></script>
<script>
  VivaPush.init({ appKey: "vp_pub_...", apiUrl: "https://vivapush.com" });
  botao.onclick = () => VivaPush.subscribe({ externalUserId: "cliente-42" });
</script>

O script é um exemplo de integração pronto para copiar ou adaptar, não um SDK oficial. O contrato é a API pública, então você pode escrever a sua própria versão.

Como enviar a notificação

Pelo painel, a campanha tem cinco passos: informações, conteúdo, público, envio e revisão. O público pode ser todo mundo, um segmento salvo ou um filtro por plataforma, país, idioma, tags e atividade. Antes de falar com todos, mande um teste para os seus aparelhos de teste. Você pode agendar no seu fuso ou no fuso de cada pessoa.

Pelo seu sistema, use POST /api/v1/notifications com "platforms": ["web"] e uma chave de servidor. A resposta 202 quer dizer que a notificação foi salva e está na fila, ainda não entregue. Repetir a mesma Idempotency-Key não envia de novo.

Como saber o que chegou

O vivapush separa as etapas. “Aceita para entrega” quer dizer que o serviço de push do navegador recebeu a mensagem. “Chegou ao dispositivo” só conta quando o service worker confirma o recebimento. O mesmo service worker registra aberturas e cliques.

Quando um navegador recusa uma inscrição (por exemplo, a pessoa bloqueou as notificações), o dispositivo deixa de receber e o seu sistema pode ser avisado pelo webhook subscriptions.invalidated.

Boas práticas

• Explique o que a pessoa vai receber antes de mostrar o pedido do navegador.
• Separe avisos de pedido e de conta (transacionais) de promoções (marketing) e deixe a pessoa recusar só o marketing, com VivaPush.setPreferences.
• Título curto e direto: a API aceita até 65 caracteres no título e 240 na mensagem.
• Use o envio no fuso de cada pessoa para ninguém receber de madrugada.

Perguntas frequentes