Começar a usar a API Notifications

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

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

Compatibilidade com navegadores

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

Origem

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

  1. Clique em Remixar para editar para tornar o projeto editável.
  2. Para visualizar o site, pressione Ver app. Em seguida, pressione Tela cheia tela cheia

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

Captura de tela mostrando o app remixado da transmissão ao vivo em uma nova guia

Durante este codelab, faça mudanças no código no Glitch incorporado nesta página. Atualize a nova guia com o app ativo para conferir as mudanças.

Conhecer o app inicial e o código dele

Comece conferindo o aplicativo publicado 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; tudo isso 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 mostra "TODO" mensagens 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 nesta página. Abra public/index.js e confira algumas partes importantes do código já existente:

  • A função showPermission usa a API Notifications para receber o estado atual da permissão do site e registre-o 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ê 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 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 a funcionalidade de 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 seu 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 Google Chrome na qual você está visualizando seu aplicativo ativo.

  3. Na interface do app publicado, clique em Solicitar permissão para enviar notificações. Uma janela pop-up será exibida.

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

Resposta do usuário Estado da 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 vão ser resolvidas para 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 para o usuário.

  • As chamadas seguintes para Notification.requestPermission vão ser 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 para o usuário.

  • As chamadas subsequentes para Notification.requestPermission produzirão 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. Não será possível exibir pop-ups nem notificações de solicitação de permissão ao usuário.

    Até a data deste artigo, o comportamento do navegador em resposta a pop-ups de permissão de notificações dispensados ainda está sujeito a alterações. 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 esteja esperando e saiba o que está acontecendo.

.

Enviar uma notificação

Nesta etapa, você 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 de 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 Google Chrome na qual você está visualizando seu aplicativo 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ê vai adicionar algumas linhas de código para conferir 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çã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ções do site para o padrão.

  2. Clique em Solicitar permissão para enviar notificações e selecione Bloquear na janela pop-up.

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

Se quiser, redefina as permissões de notificação do site novamente. Solicite a permissão e dispense o pop-up várias vezes para entender o que acontece.

Teste as opções de notificação

Agora você sabe como solicitar permissões e enviar notificações. Você também viu o impacto que as respostas do usuário têm na capacidade do seu app de exibir notificações.

Agora você pode testar as diversas 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 forma diferente, Por isso, teste suas notificações em diferentes plataformas para verificar 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'
    },],
  */
}

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

Se você não souber o que fazer, 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.