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 de sinalização.

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.

Com o uso de selos, é fácil notificar o usuário de forma sutil sobre 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 costumam 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:

  • Chat, e-mail e apps sociais, para sinalizar a chegada de novas mensagens 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 indicar que uma ação do jogador é necessária (por exemplo, no xadrez, quando é a vez dele).

Suporte

A API App Badging funciona no Windows e no macOS no Chrome 81 e 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.
  3. Abra como um PWA instalado. Observe que ele precisa estar sendo executado como um PWA instalado (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 sinalização, 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 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 presuma 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 como "99"), o "+" não vai aparecer. Seja qual for o número real, basta chamar setAppBadge(unreadCount) e permitir que o user agent faça a exibição dele 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 por meio de uma sincronização periódica em segundo plano, da API Push ou de uma combinação de ambos.

Sincronização periódica em segundo plano

A sincronização em segundo plano periódica 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 é bom para alguns casos de uso (por exemplo, mostrar uma notificação ao atualizar o selo), mas torna impossível atualizar o selo sutilmente sem exibir 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. Além disso, as informações de menor prioridade são entregues atualizando o selo quando a página está aberta ou por meio de uma sincronização periódica em segundo plano.

Feedback

A equipe do Chrome quer saber mais sobre suas experiências 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 à API

Quer 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