Começar a usar a API Notifications

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

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

Remixar o app de exemplo e abrir em uma nova guia

As notificações são bloqueadas automaticamente no app Glitch incorporado. Por isso, não será possível visualizar o app nesta página. Em vez disso, faça o seguinte:

1. Clique em Remix para editar e torne o projeto editável.
2. Para visualizar o site, pressione Ver app e Tela cheia .

O Glitch será aberto em uma nova guia do Chrome:

Ao longo deste codelab, faça mudanças no código no Glitch incorporado desta página. Atualize a nova guia com seu app ativo para conferir as mudanças.

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ê verá a seguinte mensagem no Console:

   Notification permission is default
   

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

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. Essas são as funções que você vai implementar neste codelab.

Agora, vamos analisar o código do app de exemplo no Glitch incorporado desta página. Abra public/index.js e observe algumas partes importantes do código existente:

• A função showPermission usa a API Notifications para ver o estado de permissão atual do site e registrá-lo 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 a 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ê 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ê implementará essa função depois de implementar requestPermission.

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

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

Pedir permissão para enviar notificações

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

Use o método Notification.requestPermission() para acionar um pop-up que solicita que o usuário permita ou bloqueie notificações do site.

1. Substitua o stub de função requestPermission em public/index.js pelo seguinte código:

   // 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. Atualize a guia do Chrome na qual você está visualizando o aplicativo ativo.

3. Na interface ativa do app, clique em Solicitar permissão para enviar notificações. Será exibido um pop-up.

O usuário pode fazer uma das três respostas no pop-up de permissão.

Resposta do usuário	Estado de permissão de notificações
O usuário seleciona Permitir.	granted
O usuário seleciona Bloquear.	denied
O usuário dispensa o pop-up sem fazer uma seleção	default

Se o usuário clicar em "Permitir":

• Notification.permission é definido como granted.

• O site poderá exibir notificações.

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

Se o usuário clicar em "Bloquear":

• Notification.permission é definido como denied.

• O site não poderá exibir notificações para o usuário.

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

Se o usuário dispensar o pop-up:

• Notification.permission continua sendo default.

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

• As chamadas seguintes para Notification.requestPermission produzirão 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. Assim, não é possível exibir pop-ups nem notificações de solicitação de permissão para o usuário.

  No momento em que este artigo foi escrito, o comportamento do navegador em resposta a pop-ups de permissão de notificações dispensadas ainda está sujeito a mudanças. A melhor maneira de lidar com isso é sempre solicitar a permissão de notificações em resposta a alguma interação que o usuário iniciou, para que eles já estejam esperando e saibam o que está acontecendo.

Enviar uma notificação

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

Você usará o construtor Notification para criar uma nova notificação e tentar mostrá-la. Se o estado de permissão for granted, sua 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 você pode incluir 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 será exibida.

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

Nesta etapa, você adicionará algumas linhas de código que permitirão ver o que acontece quando você tenta exibir 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ções:

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

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

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

Como opção, redefina as permissões de notificações do site novamente. Você pode solicitar a permissão e dispensar o pop-up várias vezes para ver o que acontece.

Teste as opções de notificação

Agora você aprendeu as noções básicas sobre como solicitar permissões e enviar notificações. Você também aprendeu o impacto das respostas dos usuários na capacidade do app de mostrar notificações.

Agora você pode testar as muitas 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ção no MDN para mais informações sobre essas opções.

Os navegadores e dispositivos implementam essas opções de maneiras diferentes. Por isso, vale a pena testar suas notificações em diferentes plataformas para conferir a aparência delas.

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'
    },],
  */
}

Consulte o Gerador de notificações de Pedro Beverloo (em inglês) para mais ideias.

Se tiver dúvidas, aqui está o código completo deste codelab: glitch.com/edit/#!/codelab-notifications-get-started-completed (link em inglês)

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