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 de Twitter com oito notificações e outro app mostrando um selo de sinalização.
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 para todo o aplicativo, mostrado em um local específico do sistema operacional associado ao aplicativo (como a estante ou a tela inicial).

Os selos ajudam a notificar sutilmente o usuário de que há uma nova atividade que pode exigir atenção ou a 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 eles 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 incluem:

  • Apps de chat, e-mail e sociais para sinalizar que novas mensagens chegaram ou mostrar o número de itens não lidos.
  • Apps de produtividade, para sinalizar que uma tarefa em 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. A compatibilidade com o ChromeOS está em desenvolvimento e será disponibilizada em uma versão futura. No Android, não há suporte para a API Badging. Em vez disso, o Android vai mostrar automaticamente um selo no ícone do app da Web instalado quando houver 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 Google Chrome para instalá-lo.
  3. Abra-o como um PWA instalado. Observe que ele precisa ser executado como um PWA instalado (na barra de tarefas ou na base).
  4. Clique no botão Definir ou Limpar para remover 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 instalação 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 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 tratar erros.

O selo pode ser definido na página atual ou no service worker registrado. Para definir ou limpar o selo (na página de 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 não permite a representação exata do selo. Nesses casos, o navegador vai tentar oferecer a melhor representação para o dispositivo. Por exemplo, como a API Badging não tem suporte no 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 pegar um número como "4000" e reescrever como "99+". Se você saturar o selo por conta própria (por exemplo, definindo "99"), o "+" não vai aparecer. Não importa o número real, basta chamar setAppBadge(unreadCount) e deixar que o user agent o exiba.

Embora a API App Badging no Chrome exija um app instalado, não faça chamadas para ela dependendo do estado de instalação. Basta chamar a API quando ela existir, já que outros navegadores podem mostrar o selo em outros lugares. Se funciona, também funciona. Caso contrário, simplesmente não tem.

Definição e limpeza do crachá em segundo plano com 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 periódica em segundo plano, a API Push ou uma combinação de ambos.

Sincronização periódica em segundo plano

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

No entanto, a frequência com que a sincronização é chamada não é perfeitamente confiável e é chamada a critério 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 de 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 indicador), mas impossibilita atualizar sutilmente o indicador sem exibir uma notificação.

Além disso, os usuários precisam conceder 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 juntos é uma boa solução. As informações de alta prioridade são entregues pela API Push, mostrando uma notificação e atualizando o selo. Além disso, as informações de menor prioridade são entregues com a atualização do selo, seja quando a página está aberta ou pela sincronização periódica em segundo plano.

Feedback

A equipe do Chrome quer saber mais sobre suas experiências com a API App Badging.

Fale sobre o design da API

Algo na API 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 Componentes como UI>Browser>WebAppInstalls. O Glitch funciona muito bem para compartilhar reproduções rápidas e fáceis.

Mostrar suporte à API

Quer usar a API App Badging no seu site? Seu suporte público ajuda a equipe do Chrome a priorizar recursos e mostra a outros fornecedores de navegador a importância do suporte a eles.

  • Envie um tweet para @ChromiumDev com a hashtag #BadgingAPI e conte para a gente onde e como você está usando a hashtag.

Links úteis

Foto principal de Prateek Katyal no Unsplash (links em inglês)