A API App Badging permite que os apps da Web instalados definam um selo em todo o aplicativo no ícone do app.
O que é a API App Badging?
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 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 sinalizar que novas mensagens chegaram ou mostrar o número de itens não lidos.
- Apps de produtividade, para sinalizar que uma tarefa de longa duração em segundo plano (como renderizar uma imagem ou 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 ao 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
- Abra a demonstração da API App Badging.
- Quando solicitado, clique em Instalar para instalar o app ou use o menu do Chrome.
- Abra como um PWA instalado. Observe que ele precisa estar sendo executado como um PWA instalado (na barra de tarefas ou na base).
- Clique no botão Set ou Clear para definir ou limpar o ícone no í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). Definirnumber
como0
é o mesmo que chamarclearAppBadge()
.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 no Android, ele mostra apenas 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-o 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 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 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. 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 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?
- Registre um problema de especificação no repositório da API de selos do GitHub (link em inglês) ou adicione suas opiniões a um problema atual.
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
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.
- Envie um tweet para @ChromiumDev usando a hashtag
#BadgingAPI
e nos informe onde e como você está usando.
Links úteis
- Explicações públicas
- Especificação do rascunho
- Demonstração da API Badging | Fonte da demonstração da API Badging
- Rastreamento de bugs
- Entrada de ChromeStatus.com
- Componente Blink:
UI>Browser>WebAppInstalls
Foto do herói de Prateek Katyal no Unsplash