Começar a usar a API Notifications

Neste codelab, você vai usar recursos básicos da API Notifications para:

• Solicitar permissão para enviar notificações
• Envie notificações
• Teste as opções de notificação

Conhecer o app inicial e o código dele

Comece conferindo o app ativo na nova guia do Chrome:

1. Pressione "Control+Shift+J" (ou "Command+Option+J" no Mac) para abrir o DevTools. Clique na guia Console.

   Você vai ver a seguinte mensagem no console:

   Notification permission is default
   

   Se você não sabe o que isso significa, não se preocupe. Tudo será revelado em breve.

2. Clique nos botões no app ativo: Solicitar permissão para enviar notificações e Enviar uma notificação.

   O console imprime mensagens "TODO" de alguns stubs de função: requestPermission e sendNotification. Estas são as funções que você vai implementar neste codelab.

Agora vamos analisar o código do app de exemplo. Abra public/index.js e confira algumas partes importantes do código atual:

• A função showPermission usa a API Notifications para receber o estado atual da permissão do site e registrar no console:

  // Print current permission state to console;
  // update onscreen message.
  function showPermission() {
    let permission = Notification.permission;
    console.log('Notification permission is ' + permission);
    let p = document.getElementById('permission');
    p.textContent = 'Notification permission is ' + permission;
  }
  

  Antes de solicitar permissão, o estado dela é default. No estado de permissão default, um site precisa solicitar e receber permissão antes de enviar notificações.

• A função requestPermission é um stub:

  // Use the Notification API to request permission to send notifications.
  function requestPermission() {
    console.log('TODO: Implement requestPermission()');
  }
  

  Você vai implementar essa função na próxima etapa.

• A função sendNotification é um stub:

  // Use the Notification constructor to create and send a new Notification.
  function sendNotification() {
    console.log('TODO: Implement sendNotification()');
  }
  

  Você vai implementar essa função depois de implementar requestPermission.

• O listener de eventos window.onload chama a função showPermission no carregamento da página, mostrando o estado atual da permissão no console e na página:

  window.onload = () => { showPermission(); };
  

Solicitar permissão para enviar notificações

Nesta etapa, você vai adicionar a funcionalidade para pedir permissão ao usuário para enviar notificações.

Você vai usar o método Notification.requestPermission() para acionar um pop-up que pede ao usuário para permitir ou bloquear notificações do seu site.

1. Substitua o stub da função requestPermission em public/index.js pelo código a seguir:

   // Use the Notification API to request permission to send notifications.
   function requestPermission() {
     Notification.requestPermission()
       .then((permission) => {
         console.log('Promise resolved: ' + permission);
         showPermission();
       })
       .catch((error) => {
         console.log('Promise was rejected');
         console.log(error);
       });
   }
   

2. Recarregue a guia do Chrome em que você está visualizando o app ativo.

3. Na interface do app ativo, clique em Pedir permissão para enviar notificações. Um pop-up vai aparecer.

O usuário pode dar uma de três respostas ao pop-up de permissão.

Se o usuário clicar em "Permitir":

• Notification.permission é definido como granted.

• O site poderá mostrar notificações.

• As chamadas subsequentes para Notification.requestPermission serão resolvidas como granted sem um pop-up.

Se o usuário clicar em "Bloquear":

• Notification.permission é definido como denied.

• O site não poderá mostrar notificações ao usuário.

• As chamadas subsequentes para Notification.requestPermission serão resolvidas como denied sem um pop-up.

Se o usuário dispensar o pop-up:

• Notification.permission continua sendo default.

• O site não poderá mostrar notificações ao usuário.

• As chamadas subsequentes para Notification.requestPermission vão gerar mais pop-ups.

  No entanto, se o usuário continuar dispensando os pop-ups, o navegador poderá bloquear o site, definindo Notification.permission como denied. Nenhum pop-up de solicitação de permissão nem notificações podem ser mostrados ao usuário.

  No momento da redação deste artigo, o comportamento do navegador em resposta aos pop-ups de permissão de notificações dispensadas ainda está sujeito a mudanças. A melhor maneira de lidar com isso é sempre pedir permissão de notificação em resposta a alguma interação iniciada pelo usuário. Assim, ele vai esperar a solicitação e saber o que está acontecendo.

Enviar uma notificação

Nesta etapa, você vai enviar uma notificação ao usuário.

Você vai usar o construtor Notification para criar uma nova notificação e tentar mostrá-la. Se o estado da permissão for granted, a notificação será exibida.

1. Substitua o stub da função sendNotification em index.js pelo seguinte código:

   // Use the Notification constructor to create and send a new Notification.
   function sendNotification() {
     let title = 'Test';
     let options = {
       body: 'Test body',
       // Other options can go here
     };
     console.log('Creating new notification');
     let notification = new Notification(title, options);
   }
   

   O construtor Notification usa dois parâmetros: title e options. options é um objeto com propriedades que representam configurações visuais e dados que podem ser incluídos em uma notificação. Consulte a documentação do MDN sobre parâmetros de notificação para mais informações.

2. Atualize a guia do Chrome em que você está visualizando o app ativo e clique no botão Enviar notificação. Uma notificação com o texto Test body vai aparecer.

O que acontece quando você envia notificações sem permissão?

Nesta etapa, você vai adicionar algumas linhas de código para ver o que acontece quando você tenta mostrar uma notificação sem a permissão do usuário.

• Em public/index.js, no final da função sendNotification, defina o manipulador de eventos onerror da nova notificação:

// Use the Notification constructor to create and send a new Notification.
function sendNotification() {
  let title = 'Test';
  let options = {
    body: 'Test body',
    // Other options can go here
  };
  console.log('Creating new notification');
  let notification = new Notification(title, options);
  notification.onerror = (event) => {
    console.log('Could not send notification');
    console.log(event);
  };
}

Para observar um erro de permissão de notificação:

1. Clique no ícone de bloqueio ao lado da barra de URL do Chrome e redefina a configuração de permissão de notificação do site para o padrão.

2. Clique em Pedir permissão para enviar notificações e selecione Bloquear no pop-up.

3. Clique em Enviar notificação e veja o que acontece. O texto do erro (Could not send notification) e o objeto de evento são registrados no console.

Se quiser, redefina as permissões de notificação do site novamente. Tente pedir permissão e dispensar o pop-up várias vezes para ver o que acontece.

Teste as opções de notificação

Agora você já conhece o básico de como pedir permissão e enviar notificações. Você também viu o impacto das respostas dos usuários na capacidade do app de mostrar notificações.

Agora você pode testar as várias opções visuais e de dados disponíveis ao criar uma notificação. Confira abaixo o conjunto completo de opções disponíveis. Consulte a documentação de notificações na MDN para mais informações sobre essas opções.

Navegadores e dispositivos implementam essas opções de maneiras diferentes. Por isso, vale a pena testar as notificações em várias plataformas para ver como elas aparecem.

let options = {
  dir: 'auto',              // Text direction
  lang: 'en-US',            // A language tag
  badge: '/orange-cat.png', // Display when insufficient room
  body: 'Hello World',      // Body text
  tag: 'mytag',             // Tag for categorization
  icon: '/line-cat.png',    // To display in the notification
  image: '/orange-cat.png', // To display in the notification
  data: {                   // Arbitrary data; any data type
    cheese: 'I like cheese',
    pizza: 'Excellent cheese delivery mechanism',
    arbitrary: {
      faveNumber: 42,
      myBool: true
    }},
  vibrate: [200, 100, 200], // Vibration pattern for hardware
  renotify: false,          // Notify if replaced? Default false
  requireInteraction: false,// Active until click? Default false
  /*
    actions:   // Array of NotificationActions
               // Only usable with a service worker
    [{
      action: 'shop',
      title: 'Shop!',
      icon: '/bags.png'
    },],
  */
}

Confira mais ideias no Gerador de notificações de Peter Beverloo.

Confira o próximo codelab desta série, Processar notificações com um service worker, para saber mais.