Selos para ícones de apps

A API App Badging permite que os apps da Web instalados definam um selo em todo o aplicativo no ícone do app.

Pete LePage

O que é a API App Badging?

Exemplo do Twitter com oito notificações e outro app mostrando um selo do tipo bandeira.
Exemplo do Twitter com oito notificações e outro app mostrando um selo do tipo bandeira.

A API App Badging permite que os apps da Web instalados definam um selo em todo o aplicativo, exibido em um local específico do sistema operacional associado ao aplicativo, como a prateleira ou a tela inicial.

Os selos facilitam a notificação sutil do usuário de que há uma nova atividade que pode exigir atenção ou indicar uma pequena quantidade de informações, como uma contagem de mensagens não lidas.

Os selos tendem a ser mais fáceis de usar do que as notificações e podem ser atualizados com uma frequência muito maior, já que não interrompem o usuário. E, como elas não interrompem o usuário, não precisam da permissão dele.

Possíveis casos de uso

Exemplos de apps que podem usar essa API:

  • Apps de chat, e-mail e redes sociais, para indicar que novas mensagens chegaram ou mostrar o número de itens não lidos.
  • Apps de produtividade, para sinalizar que uma tarefa de segundo plano de longa duração (como renderizar uma imagem ou um vídeo) foi concluída.
  • Jogos, para sinalizar que uma ação do jogador é necessária (por exemplo, no xadrez, quando é a vez do jogador).

Suporte

A API App Badging funciona no Windows e no macOS, no Chrome 81 e no Edge 81 ou versões mais recentes. O suporte para o ChromeOS está em desenvolvimento e será disponibilizado em uma versão futura. No Android, a API Badging não é compatível. Em vez disso, o Android mostra automaticamente um selo no ícone do app da Web instalado quando há uma notificação não lida, assim como nos apps Android.

Testar

  1. Abra a demonstração da API App Badging.
  2. Quando solicitado, clique em Instalar para instalar o app ou use o menu do Chrome para fazer isso.
  3. Abra como um PWA instalado. Ele precisa estar em execução como uma PWA instalada (na barra de tarefas ou na base).
  4. Clique no botão Set ou Clear para definir ou limpar o selo do ícone do app. Você também pode fornecer um número para o Valor do selo.

Como usar a API App Badging

Para usar a API App Badging, seu app da Web precisa atender aos critérios de instalabilidade do Chrome e os usuários precisam adicioná-lo às telas iniciais.

A API Badge consiste em dois métodos em navigator:

  • setAppBadge(number): define o selo do app. Se um valor for fornecido, defina o selo como o valor fornecido. Caso contrário, mostre um ponto branco simples (ou outra flag, conforme apropriado para a plataforma). Definir number como 0 é o mesmo que chamar clearAppBadge().
  • clearAppBadge(): remove o selo do app.

Ambos retornam promessas vazias que podem ser usadas para o tratamento de erros.

O selo pode ser definido na página atual ou no service worker registrado. Para definir ou limpar o selo (na página em primeiro plano ou no service worker), chame:

// Set the badge
const unreadCount = 24;
navigator.setAppBadge(unreadCount).catch((error) => {
  //Do something with the error.
});

// Clear the badge
navigator.clearAppBadge().catch((error) => {
  // Do something with the error.
});

Em alguns casos, o sistema operacional pode não permitir a representação exata do selo. Nesses casos, o navegador vai tentar fornecer a melhor representação para esse dispositivo. Por exemplo, como a API Badging não tem suporte para o Android, ele só mostra um ponto em vez de um valor numérico.

Não suponha nada sobre como o user agent exibe o selo. Alguns user agents podem usar um número como "4000" e reescrevê-lo como "99+". Se você saturar o selo (por exemplo, definindo-o como "99"), o "+" não vai aparecer. Não importa o número real, chame setAppBadge(unreadCount) e deixe que o agente do usuário o exiba corretamente.

Embora a API App Badging no Chrome exija um app instalado, não faça chamadas para a API Badging que dependam do estado de instalação. Chame a API quando ela existir, já que outros navegadores podem mostrar o selo em outros lugares. Se funciona, funciona. Caso contrário, ele simplesmente não vai funcionar.

Como definir e limpar o selo em segundo plano de um service worker

Também é possível definir o selo do app em segundo plano usando o service worker. Faça isso usando a sincronização em segundo plano periódica, a API Push ou uma combinação de ambas.

Sincronização periódica em segundo plano

A sincronização periódica em segundo plano permite que um worker de serviço consulte periodicamente o servidor, que pode ser usado para receber um status atualizado e chamar navigator.setAppBadge().

No entanto, a frequência em que a sincronização é chamada não é totalmente confiável e é chamada à discrição do navegador.

API Web Push

A API Push permite que os servidores enviem mensagens para service workers, que podem executar o código JavaScript mesmo quando nenhuma página em primeiro plano está em execução. Assim, um push do servidor pode atualizar o selo chamando navigator.setAppBadge().

No entanto, a maioria dos navegadores, incluindo o Chrome, exige que uma notificação seja exibida sempre que uma mensagem push é recebida. Isso é adequado para alguns casos de uso (por exemplo, mostrar uma notificação ao atualizar o selo), mas torna impossível atualizar o selo sutilmente sem mostrar uma notificação.

Além disso, os usuários precisam conceder a permissão de notificação do site para receber mensagens push.

Uma combinação das opções anteriores

Embora não seja perfeito, o uso da API Push e da sincronização periódica em segundo plano é uma boa solução. As informações de alta prioridade são enviadas pela API Push, mostrando uma notificação e atualizando o selo. E as informações de prioridade mais baixa são enviadas atualizando o selo, seja quando a página está aberta ou por meio de sincronização periódica em segundo plano.

Feedback

A equipe do Chrome quer saber sobre sua experiência com a API App Badging.

Conte sobre o design da API

Há algo na API que não funciona como esperado? Ou há métodos ou propriedades ausentes que você precisa para implementar sua ideia? Você tem alguma dúvida ou comentário sobre o modelo de segurança?

Informar um problema com a implementação

Você encontrou um bug na implementação do Chrome? Ou a implementação é diferente da especificação?

  • Registre um bug em https://new.crbug.com. Inclua o máximo de detalhes possível, instruções simples para reprodução e defina Components como UI>Browser>WebAppInstalls. O Glitch é ótimo para compartilhar reproduções rápidas e fáceis.

Mostrar suporte para a API

Você planeja usar a API App Badging no seu site? Seu apoio público ajuda a equipe do Chrome a priorizar recursos e mostra a outros fornecedores de navegadores a importância de oferecer suporte a eles.

Links úteis

Foto do herói de Prateek Katyal no Unsplash