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
  • Testar as opções de notificação

Compatibilidade com navegadores

  • Chrome: 20.
  • Edge: 14.
  • Firefox: 22.
  • Safari: 7.

Origem

Remixar o app de exemplo e acessá-lo em uma nova guia

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

  1. Clique em Remix to Edit para tornar o projeto editável.
  2. Para visualizar o site, pressione View App. Em seguida, pressione Fullscreen tela cheia.

O Glitch vai abrir em uma nova guia do Chrome:

Captura de tela mostrando o app remixado em uma nova guia

Ao trabalhar neste codelab, faça mudanças no código no Glitch incorporado nesta página. Atualize a nova guia com o app em tempo real para conferir as mudanças.

Conhecer o app inicial e o código dele

Comece conferindo o app em tempo real na nova guia do Chrome:

  1. Pressione "Control+Shift+J" (ou "Command+Option+J" no Mac) para abrir as Ferramentas do desenvolvedor. 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 em tempo real: Solicitar permissão para enviar notificações e Enviar uma notificação.

    O console mostra 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 conferir o código do app de exemplo no Glitch incorporado nesta página. Abra public/index.js e confira algumas partes importantes do código:

  • A função showPermission usa a API Notifications para receber o estado atual de permissão do site e fazer o registro dele 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ê 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 uma funcionalidade para solicitar a permissão do 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 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. Recarregue a guia do Chrome em que você está visualizando o app.

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

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

Resposta do usuário Estado da permissão de notificação
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á 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 vai 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 fechar o pop-up:

  • Notification.permission continua sendo default.

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

  • Chamadas subsequentes para Notification.requestPermission vão produzir mais pop-ups.

    No entanto, se o usuário continuar a dispensar os pop-ups, o navegador poderá bloquear o site, definindo Notification.permission como denied. Os pop-ups de solicitação de permissão e as notificações não podem ser mostrados ao usuário.

    No momento da escrita, 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 solicitar a permissão de notificação em resposta a alguma interação iniciada pelo usuário, para que ele saiba 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 exibi-la. Se o estado da permissão for granted, a notificação será mostrada.

  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 em tempo real 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 saber 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 gerenciador 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 cadeado 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 Solicitar 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 de erro (Could not send notification) e o objeto de evento são registrados no console.

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

Testar as opções de notificação

Agora você já sabe o básico sobre como solicitar permissão 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 várias opções de visualização e 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 no MDN para mais informações sobre essas opções.

Os navegadores e dispositivos implementam essas opções de maneira diferente. Portanto, vale a pena testar suas notificações em diferentes plataformas para conferir 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 o Notification Generator de Peter Beverloo para mais ideias.

Se você tiver problemas, confira o código completo deste codelab: glitch.com/edit/#!/codelab-notifications-get-started-completed

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