Notificações push são uma visão comum na web moderna. Eles permitem que você comunique informações oportunas ao usuário, mesmo se o seu site não estiver realmente aberto. O navegador do usuário lida com eventos push de entrada e exibe notificações usando superfícies de IU do sistema, como o Windows Action Center e a tela de bloqueio do Android.
Implementar Web Push em seu site ou PWA requer a combinação de duas APIs de navegador distintas. O código responsável por assinar e receber notificações usa o componente Push API de service workers. Este código é executado continuamente em segundo plano e será invocado pelo navegador quando uma nova notificação precisar ser tratada.
Quando um evento é recebido, o service worker deve usar a API Notification para realmente exibir a notificação. Isso cria um alerta visual por meio de interfaces no nível do sistema operacional.
Aqui está um guia completo para fazer o Web Push funcionar em seu site. Vamos supor que você já tem um componente do lado do servidor que pode registrar assinaturas push e enviar seus alertas.
O Service Worker
Vamos começar com o service worker. Os prestadores de serviço têm várias funções - eles podem armazenar dados em cache para uso offline, executar sincronizações periódicas em segundo plano e atuar como manipuladores de notificação. Os prestadores de serviço usam uma arquitetura orientada a eventos. Depois de registrado por um site, o navegador do usuário invocará o service worker em segundo plano quando os eventos para os quais ele se inscreve forem gerados.
Para Web Push, um evento central é necessário: push. Isso recebe um PushEvent objeto que permite acessar a carga enviada do servidor.
self.addEventListener("push", e => { const payload = JSON.parse(e.data.text()); e.waitUntil(self.registration.showNotification( payload.title, { body: payload.body, icon: "/icon.png" } )); });
O código acima configura um service worker capaz de reagir aos eventos push de entrada. Ele espera que o servidor envie payloads JSON parecidos com este:
{
"title": "Title text for the notification",
"body": "This is the longer text of the notification."
}Quando um evento push é recebido, o service worker exibe uma notificação do navegador chamando o showNotification() função disponível em seu self.registration propriedade. A função está envolvida em um waitUntil() call para que o navegador aguarde a exibição da notificação antes de encerrar o service worker.

O showNotification() A função recebe dois argumentos: o texto do título da notificação e um objeto de opções. Duas opções são passadas neste exemplo, algum texto de corpo mais longo e um ícone a ser exibido na notificação. Muitas outras opções estão disponíveis que permitem configurar padrões de vibração, emblemas personalizados e requisitos de interação. Nem todos os navegadores e sistemas operacionais oferecem suporte a todos os recursos expostos pela API.
Conclua o lado do service worker do código, registrando-o novamente em seu JavaScript principal:
if (navigator.serviceWorker) { // replace with the path to your service worker file navigator.serviceWorker.register("/sw.js").catch(() => { console.error("Couldn't register the service worker.") }); }
Este código deve ser executado em cada carregamento de página. Ele garante que o navegador oferece suporte a service workers e, em seguida, registra o arquivo de trabalho. Os navegadores atualizarão automaticamente o service worker sempre que a cópia do servidor apresentar diferenças de bytes em relação à versão atualmente instalada.
Registrando-se para assinaturas push
Agora você precisa se inscrever no navegador para enviar notificações. O código a seguir pertence ao seu arquivo JavaScript principal, fora do service worker.
async function subscribeToPush() { if (navigator.serviceWorker) { const reg = await navigator.serviceWorker.getRegistration(); if (reg && reg.pushManager) { const subscription = await reg.pushManager.getSubscription(); if (!subscription) { const key = await fetch("https://example.com/vapid_key"); const keyData = await key.text(); const sub = await reg.pushManager.subscribe({ applicationServerKey: keyData, userVisibleOnly: true }); await fetch("https://example.com/push_subscribe", { method: "POST", headers: {"Content-Type": "application/json"}, body: JSON.stringify({ endpoint: sub.endpoint, expirationTime: sub.expirationTime, keys: sub.toJSON().keys }) }); } } } }
Em seguida, chame sua função para inscrever o navegador para notificações push:
Vamos examinar o que o código de assinatura está fazendo. As primeiras linhas verificam a presença de um service worker, recuperam seu registro e detectam o suporte a notificações push. pushManager não será definido em navegadores que não suportam Web Push.
Chamando pushManager.getSubscription() retorna uma promessa que resolve para um objeto que descreve a assinatura push atual do navegador para o seu site. Se isso já estiver definido, não precisamos inscrever novamente o usuário.
O fluxo de assinatura real começa com a solicitação de busca das chaves VAPID do servidor. A especificação VAPID é um mecanismo que permite ao navegador verificar se os eventos push estão realmente vindo de seu servidor. Você deve expor um endpoint de API do servidor que fornece uma chave VAPID. Isso é dado ao pushManager.subscribe() função para que o navegador saiba a chave para confiar. O separado userVisibleOnly opção indica que exibiremos apenas notificações que são exibidas visivelmente na tela.
O pushManager.subscribe() chamada retorna um PushSubscription objeto que descreve sua nova assinatura. Esses dados são enviados ao servidor em outra solicitação de busca. Em um aplicativo real, você também enviaria a ID do usuário ativo para que pudesse vincular a assinatura push ao dispositivo.
Seu código do lado do servidor para enviar uma notificação push para um usuário deve ser semelhante a este:
- Consulte seu armazenamento de dados para todas as assinaturas push vinculadas ao usuário de destino.
- Envie sua carga de notificação para o endpoint indicado por cada assinatura, certificando-se de incluir as chaves de autenticação da assinatura (
keysnos dados enviados pelo navegador ao se inscrever). Assine o evento com a mesma chave VAPID que você enviou para o navegador.
Cada assinatura endpoint fará referência à plataforma de entrega de notificações do fornecedor do navegador. Este URL já inclui um identificador exclusivo para a assinatura. Quando você envia uma carga útil para o endpoint, o processo de segundo plano do navegador eventualmente receberá os dados e chamará seu service worker. Para Chrome no Android, o processo do navegador é integrado diretamente ao daemon de notificação do sistema.
Quando inscrever o usuário?
Ao configurar fluxos de assinatura, lembre-se de que o usuário terá que reconhecer um prompt de permissão do navegador antes que o registro seja concluído. Muitos navegadores ocultam ou rejeitam automaticamente solicitações de permissão não solicitadas; em qualquer caso, pedir a um usuário que se inscreva no momento em que acessa seu site pode não gerar o resultado desejado.
Você tem a melhor chance de uma inscrição bem-sucedida unindo as solicitações de inscrição a uma ação direta do usuário. Considere fornecer um banner no aplicativo que explica os benefícios de habilitar notificações e oferece um botão “Habilitar agora”. Você pode verificar se o usuário já está inscrito e ocultar o banner com o pushManager.getSubscription() função mostrada acima.

Clicar no botão de ativação deve chamar sua função de inscrição. O processo pode levar alguns segundos enquanto o navegador configura o registro e as chamadas de rede são concluídas. Exibir um botão giratório de carregamento durante esse tempo ajudará a manter o usuário informado.
Os usuários também devem ter uma maneira de cancelar a assinatura. Embora possam revogar a permissão do navegador a qualquer momento, alguns usuários procurarão uma opção no aplicativo, especialmente se tiverem instalado seu site como um PWA.
Esta é uma implementação simples de cancelamento de assinatura:
async function unsubscribePush() { const reg = await navigator.serviceWorker.getRegistration(); const subscription = await reg.pushManager.getSubscription(); if (subscription) { await subscription.unsubscribe(); await fetch(`https://example.com/push_unsubscribe/${subscription.endpoint}`, {method: "DELETE"}); } else { // already subscribed } }
Chamando unsubscribe() com um PushSubscription cancela a assinatura, revertendo o navegador para seu estado padrão. Seu service worker irá parar de receber push eventos. O endpoint da assinatura é enviado ao seu servidor para que você possa removê-lo do armazenamento de dados e evitar o envio de dados para o que agora é um URL morto.
Tratamento de vencimentos e renovações
Você deve ter notado o expirationTime propriedade no PushSubscription objeto criado pelo navegador. Isso nem sempre será definido; quando for, o dispositivo irá parar de receber notificações após esse tempo.
Na prática, expirationTime não é usado atualmente nos principais navegadores. Os tokens produzidos pelo Chrome não expiram até que a inscrição seja manualmente cancelada, então expirationTime é sempre null. Firefox não configura expirationTime qualquer um, mas seu serviço de notificação pode substituir assinaturas durante sua vida.
Você pode responder ao navegador alterando sua assinatura push ativa implementando o pushsubscriptionchange evento em seu service worker. Infelizmente, existem duas versões desse evento: a implementação original, usada atualmente pelo Firefox, e a nova v2, ainda sem suporte em nenhum navegador.
A especificação original tem sérios problemas de usabilidade que tornam difícil responder ao evento. Quando você recebe um evento v1, o navegador excluiu a assinatura original e você precisa criar uma nova manualmente. O problema é que, sem acesso à assinatura expirada, você não pode emitir uma solicitação de "substituição" para o seu servidor - você não tem como acessar o antigo endpoint URL
A especificação v2 resolve isso fornecendo um evento com oldSubscription e newSubscription propriedades. Ao receber o evento, a assinatura anterior foi cancelada, mas você ainda pode acessar suas propriedades. A nova assinatura agora é criada para você pelo navegador.
Aqui está um exemplo de implementação pushsubscriptionchange com a nova especificação:
self.addEventListener("pushsubscriptionchange", e => { e.waitUntil(async () => { await fetch("https://example.com/push_change", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ auth: (e.newSubscription.toJSON().keys?.auth || null), endpoint: e.newSubscription.endpoint, endpointOld: e.oldSubscription.endpoint, expirationTime: e.newSubscription.expirationTime, p256dh: (e.newSubscription.toJSON().keys?.p256dh || null) }) }); }); });
Os pontos de extremidade são exclusivos para que seu servidor possa consultar a assinatura antiga e atualizar suas propriedades com as da nova assinatura. Se você quiser adicionar suporte para a especificação antiga também, precisará rastrear manualmente o endpoint de assinatura ativo fora da API push. Armazenando em localStorage ou IndexedDB permitirá que você o acesse dentro de seu pushsubscriptionchange manipulador para que você possa pedir ao servidor para substituir a assinatura.
A especificação revisada é muito mais fácil de implementar do que sua contraparte mais antiga. Mesmo que ainda não seja compatível com os navegadores, vale a pena adicioná-lo ao seu service worker. Algumas linhas de código irão preparar para o futuro seu manuseio de push em relação aos novos lançamentos do navegador.
Adicionando Botões de Ação
As notificações push podem incluir botões interativos que permitem ao usuário realizar ações imediatas. Aqui está um showNotification() chamada que cria um:
self.registration.showNotification( "Notification with actions", { body: "This notification has a button.", actions: [ { action: "/home", title: "Go to Homescreen", icon: "/home.png" } ] } );
Cada notificação pode incluir várias ações, cada uma com um rótulo, ícone e action. A última propriedade deve identificar uma ação que seu aplicativo pode iniciar em resposta à pressão do usuário.

Quando o usuário toca em uma ação, seu service worker recebe um notificationclick evento:
self.addEventListener("notificationclick", e => { const uri = e.action; const notification = e.notification; notification.close(); clients.openWindow(`${self.location.origin}${action}`); });
Estamos usando o action para declarar um URI para o qual o usuário pode navegar. Uma nova guia é aberta para o URI quando a notificação é pressionada. Chamando notification.close() garante que a notificação também seja descartada. Caso contrário, algumas plataformas farão com que o usuário o deslize manualmente.
Resumo
Implementar o Web Push pode parecer assustador se você nunca trabalhou com as APIs relevantes antes. Mais do que questões técnicas, você deve manter a experiência do usuário em primeiro lugar em sua mente e certificar-se de comunicar Por quê vale a pena habilitar as notificações.
A inscrição e o cancelamento da inscrição no push ocorrem no código JavaScript principal do seu aplicativo, usando navigator.serviceWorker APIs. O código que responde a novos eventos push e exibe notificações do navegador reside no próprio service worker.
O Web Push agora é suportado pela maioria dos principais navegadores da web, sendo o Safari a exceção proeminente. Lembre-se de que as notificações serão processadas de maneira diferente em cada navegador e família de sistema operacional, portanto, não presuma que um determinado recurso do showNotification() A API estará disponível universalmente.



