O Guia Definitivo da Notifications API do JavaScript

Introdução à Notifications API

A Notifications API permite que uma aplicação web exiba mensagens no nível do sistema operacional fora da aba do navegador — os pequenos pop-ups que o sistema operacional exibe no canto da tela. Como aparecem mesmo quando o usuário mudou para outra aba ou aplicativo, as notificações são uma forma direta de apresentar informações urgentes: uma nova mensagem de chat, um upload concluído, um lembrete de calendário.

Esta página cobre o ciclo de vida completo: verificar se a API está disponível, solicitar permissão ao usuário, criar e personalizar notificações, reagir a cliques e exibir notificações a partir de um service worker para que continuem funcionando após o fechamento da página. Ela termina com as regras que impedem as notificações de se tornarem incômodas.

Alguns fatos para definir expectativas antes da primeira linha de código:

• As notificações exigem uma concessão de permissão explícita do usuário. Você não pode exibir nenhuma até que a permissão seja granted.
• Elas só funcionam em um contexto seguro (https://, ou http://localhost durante o desenvolvimento).
• A aparência e o comportamento de uma notificação são controlados pelo sistema operacional, não pelo seu CSS. Você fornece o conteúdo; o SO decide como renderizá-lo.

Verificando o suporte

Sempre faça a detecção de recursos antes de usar a API, para que o código seja degradado graciosamente em ambientes que não a possuem (navegadores mais antigos, alguns webviews incorporados e renderização do lado do servidor):

if ('Notification' in window) {
  // The Notifications API is available
} else {
  console.log('This browser does not support notifications.');
}

Entendendo as permissões

O estado da permissão reside na propriedade estática Notification.permission e é um dos três valores de string:

• 'granted' — o usuário permitiu as notificações; você pode exibi-las.
• 'denied' — o usuário as bloqueou; as chamadas para exibir uma notificação são ignoradas silenciosamente.
• 'default' — o usuário ainda não decidiu, o que é tratado como 'denied' até que você pergunte.

Solicite permissão com Notification.requestPermission(). Ela retorna uma promise que resolve para a string de permissão resultante:

Notification.requestPermission().then((permission) => {
  console.log('Permission:', permission); // 'granted', 'denied', or 'default'
});

Um padrão robusto verifica o estado atual primeiro e só solicita quando a decisão ainda é 'default':

async function ensurePermission() {
  if (Notification.permission === 'granted') {
    return true;
  }
  if (Notification.permission === 'denied') {
    return false; // can't re-prompt; the user must change it in browser settings
  }
  const permission = await Notification.requestPermission();
  return permission === 'granted';
}

A forma baseada em promise se combina naturalmente com async/await e a Promise API mais ampla.

Criando e exibindo notificações

Uma vez que a permissão é granted, construa uma notificação com o construtor Notification. O primeiro argumento é o título (obrigatório); o segundo é um objeto de opções opcional.

if (Notification.permission === 'granted') {
  new Notification('Hello, world!', {
    body: 'Here is the body of the notification.',
    icon: '/icon-192.png'
  });
}

A notificação aparece no momento em que o objeto é criado — você não chama um método "show" separado.

Opções comuns

O objeto de opções aceita muitos campos. Os mais úteis:

new Notification('New message', {
  body: 'You have 1 unread message from Alex.',
  icon: '/icon-192.png',
  tag: 'chat-alex',          // replacing an earlier "Alex" notification
  data: { conversationId: 42 },
  requireInteraction: true
});

Evitando spam de notificações com tag

A opção tag é a maneira mais simples de parar de acumular duplicatas. Se três mensagens chegarem da mesma pessoa, reutilizar uma tag faz com que o usuário veja uma única notificação atualizada em vez de três:

function notifyUnread(count) {
  new Notification('Inbox', {
    body: `You have ${count} unread messages.`,
    tag: 'inbox-count' // each call updates the same notification
  });
}

Eventos de notificação

Uma instância de Notification dispara eventos que você pode ouvir. O mais importante é click, disparado quando o usuário ativa a notificação:

const notification = new Notification('Interactive Notification', {
  body: 'Click me to do something',
  icon: '/icon-192.png'
});

notification.onclick = (event) => {
  event.preventDefault();    // stop the browser's default focus behavior
  window.open('https://example.com', '_blank');
  notification.close();      // remove the notification once handled
};

Outros eventos disponíveis são show (exibida), error (falha ao exibir) e close (dispensada). Você também pode anexar manipuladores com addEventListener — veja tratamento de eventos no DOM para o padrão geral.

Fechando notificações programaticamente

Chame close() para dispensar uma notificação você mesmo — útil para limpar um aviso de "baixando…" assim que o download termina:

const note = new Notification('Downloading…', { tag: 'download' });

// later, when the work is done:
setTimeout(() => note.close(), 4000);

Notificações silenciosas

Defina silent: true para exibir uma notificação sem som ou vibração — adequado para atualizações de baixa prioridade e ambiente:

new Notification('Silent Notification', {
  body: 'This is a silent notification.',
  silent: true
});

Notificações a partir de um service worker

O construtor simples Notification só funciona enquanto uma página está aberta. Para entregar notificações quando seu site está em segundo plano — ou em resposta a uma mensagem push do servidor — exiba-as a partir de um service worker usando ServiceWorkerRegistration.showNotification():

// In the page: ask the service worker to show a notification
navigator.serviceWorker.ready.then((registration) => {
  registration.showNotification('Background-capable notification', {
    body: 'This can be shown even after the tab is closed.',
    icon: '/icon-192.png',
    actions: [
      { action: 'open', title: 'Open' },
      { action: 'dismiss', title: 'Dismiss' }
    ]
  });
});

As notificações de service worker também suportam botões de ação (o array actions), o que o construtor simples não faz. Trate os cliques dentro do próprio service worker:

// In the service worker (sw.js)
self.addEventListener('notificationclick', (event) => {
  event.notification.close();
  if (event.action === 'open') {
    event.waitUntil(clients.openWindow('/inbox'));
  }
});

Esse caminho via service worker é o que alimenta o verdadeiro web push: um servidor envia uma mensagem, a Push API acorda o service worker, e o worker chama showNotification().

Suporte a navegadores e ressalvas

• Somente contexto seguro. As notificações precisam de HTTPS (ou localhost). Não funcionarão em páginas http:// simples.
• A permissão é persistente. Uma vez que o usuário escolhe 'denied', você não pode solicitar novamente via JavaScript — ele deve alterar isso nas configurações do site no navegador. Não fique pedindo novamente.
• iOS Safari historicamente não suportava notificações web; o suporte chegou apenas para sites adicionados à Tela Inicial como PWA. Sempre faça a detecção de recursos.
• A aparência é controlada pelo SO. Não dependa de um tamanho, posição ou estilo específico — concentre-se em um texto claro e breve.

Boas práticas

Para manter as notificações como um recurso que os usuários apreciam, em vez de silenciarem:

• Solicite no contexto, após um gesto. Solicite permissão quando o usuário acabou de fazer algo que torna as notificações obviamente úteis (por exemplo, ativar alertas), nunca no primeiro carregamento.
• Respeite um "não". Se a permissão for 'denied', pare. Solicitações repetidas nem são tecnicamente possíveis, e insistir na interface erode a confiança.
• Seja oportuno e relevante. Envie apenas notificações que o usuário genuinamente desejaria naquele momento.
• Use com moderação. Agrupe com tag, faça lotes quando possível e reserve notificações para o que é verdadeiramente importante — notificar em excesso treina os usuários a ignorar ou bloquear você.
• Torne os cliques significativos. Um clique deve levar o usuário diretamente ao conteúdo relevante, não apenas à sua página inicial.

Conclusão

A Notifications API do JavaScript permite que aplicações web alcancem os usuários com mensagens oportunas no nível do sistema — tanto enquanto uma página está aberta quanto, por meio de um service worker, após ela ter sido fechada. O fluxo de trabalho é consistente: detectar recursos, solicitar permissão em resposta a um gesto do usuário, criar notificações com o construtor Notification (ou showNotification() em um worker) e responder a eventos de clique. Combine isso com uso disciplinado e moderado, e as notificações se tornam um recurso que os usuários mantêm ativado, em vez de um que eles se apressam em desativar.

Prática