Permita que os PWAs instalados processem links que usam um protocolo específico para uma experiência mais integrada.
Contexto sobre esquemas (também conhecidos como protocolos)
Um Identificador de recurso uniforme (URI) é uma sequência compacta de caracteres que identifica um recurso abstrato ou físico. Cada URI começa com um nome de esquema que se refere a uma especificação para atribuir identificadores nesse esquema. Assim, a sintaxe do URI é um sistema de nomenclatura federado e extensível, em que a especificação de cada esquema pode restringir ainda mais a sintaxe e a semântica dos identificadores que usam esse esquema. Os esquemas também são conhecidos como protocolos. Veja alguns exemplos de esquemas abaixo.
tel:+1-816-555-1212
mailto:Jane.Doe@example.com
news:comp.infosystems.www.servers.unix
https://web.dev/
O termo Localizador Uniforme de Recursos (URL, na sigla em inglês) refere-se ao subconjunto de URIs que, além de identificar um recurso, fornecem um meio de localizar o recurso descrevendo o principal mecanismo de acesso (por exemplo, o local da rede).
Segundo plano sobre o método registerProtocolHandler()
O método Navigator
somente de conteúdo seguro
registerProtocolHandler()
permite que os sites registrem a capacidade de abrir ou processar esquemas de URL específicos. Portanto, os sites precisam
chamar o método desta maneira: navigator.registerProtocolHandler(scheme, url)
. Os dois parâmetros são definidos da seguinte maneira:
scheme
: uma string que contém o protocolo que o site quer processar.url
: uma string que contém o URL do gerenciador. Esse URL precisa incluir%s
como um marcador de posição que será substituído pelo URL com escape que será processado.
O esquema precisa ser um dos esquemas seguros (por exemplo, mailto
, bitcoin
ou magnet
) ou começar com web+
, seguido por pelo menos uma ou mais letras ASCII minúsculas após o prefixo web+
. Por exemplo, web+coffee
.
Para deixar isso mais claro, aqui está um exemplo concreto do fluxo:
- O usuário visita um site em
https://coffeeshop.example.com/
que faz a seguinte chamada:navigator.registerProtocolHandler('web+coffee', 'coffee?type=%s')
. - Posteriormente, ao visitar
https://randomsite.example.com/
, o usuário clica em um link como<a href="web+coffee:latte-macchiato">All about latte macchiato</a>
. - Isso faz com que o navegador navegue para o seguinte URL:
https://coffeeshop.example.com/coffee?type=web%2Bcoffee%3A%2F%2Flatte-macchiato
. A string de pesquisa decodificada por URL, então, lê?type=web+coffee://latte-macchiato
.
do que se trata o tratamento de protocolo,
O mecanismo atual de registro do gerenciador de protocolo de URL para PWAs oferece o registro de gerenciador de protocolo
como parte de uma instalação do PWA por meio do manifesto dele. Depois de registrar um PWA como um
gerenciador de protocolo, quando um usuário clicar em um hiperlink com um esquema específico, como mailto
, bitcoin
ou web+music
em um navegador ou app específico da plataforma, o PWA registrado será aberto
e receberá o URL. É importante observar que o registro baseado em manifesto proposto e
o registerProtocolHandler()
tradicional desempenham papéis muito semelhantes na prática, mas ainda
permitem a possibilidade de experiências do usuário complementares:
- As semelhanças incluem requisitos relacionados à lista de esquemas que podem ser registrados, o nome e o formato dos parâmetros etc.
- Diferenças no registro baseado em manifesto são sutis, mas podem ser úteis para melhorar a experiência dos usuários do PWA. Por exemplo, o registro do PWA baseado em manifesto pode não exigir uma outra ação do usuário além da instalação iniciada pelo usuário.
Casos de uso
- Em um PWA de processamento de texto, o usuário em um documento encontra um link para uma apresentação como
web+presentations://deck2378465
. Quando o usuário clica no link, o PWA da apresentação é aberto automaticamente no escopo correto e mostra a apresentação de slides. - Em um app de chat específico da plataforma, o usuário em uma mensagem de chat recebe um link para um URL
magnet
. Ao clicar no link, um PWA do torrent instalado é iniciado e o download é iniciado. - O usuário tem um PWA de streaming de música instalado. Quando um amigo compartilha um link para uma música, como
web+music://songid=1234&time=0:13
, e o usuário clica nela, o PWA de streaming de música é iniciado automaticamente em uma janela independente.
Como usar o registro do gerenciador de protocolo de URL para PWAs
A API para registro do gerenciador de protocolo de URL é modelada com base em
navigator.registerProtocolHandler()
. Só desta vez, as informações são transmitidas de maneira declarativa pelo
manifesto do app da Web em uma nova propriedade chamada "protocol_handlers"
, que usa uma matriz de
objetos com as duas chaves obrigatórias, "protocol"
e "url"
. O snippet de código abaixo mostra como
registrar web+tea
e web+coffee
. Os valores são strings que contêm o URL do gerenciador com o marcador %s
obrigatório para o URL com escape.
{
"protocol_handlers": [
{
"protocol": "web+tea",
"url": "/tea?type=%s"
},
{
"protocol": "web+coffee",
"url": "/coffee?type=%s"
}
]
}
Vários apps registrados para o mesmo protocolo
Se vários aplicativos se registrarem como gerenciadores do mesmo esquema, como o
protocolo mailto
, o sistema operacional mostrará ao usuário um seletor e permitirá que ele decida qual
dos gerenciadores registrados usar.
O mesmo app se registra para vários protocolos
O mesmo app pode se registrar para vários protocolos, como você pode conferir no exemplo de código acima.
Atualizações de apps e registro de gerenciadores
Os registros do gerenciador são sincronizados com a versão mais recente do manifesto fornecida pelo app. Há dois casos:
- Uma atualização que adiciona novos gerenciadores aciona o registro de gerenciadores (separado da instalação do aplicativo).
- Uma atualização que remove gerenciadores aciona o cancelamento do registro (separado da desinstalação do app).
Depuração do manipulador de protocolo no DevTools
Navegue até a seção Gerenciadores de protocolo pelo painel Aplicativo > Manifesto. Confira e teste todos os protocolos disponíveis aqui.
Por exemplo, instale este PWA de demonstração. Na seção Gerenciadores de protocolo, digite "EUA" e clique em Protocolo de teste para abrir a página no PWA.
Demonstração
Confira uma demonstração do registro do gerenciador de protocolo de URL para PWAs no Glitch.
- Acesse https://protocol-handler.glitch.me/, instale o
PWA e recarregue o app após a instalação. O navegador registrou o PWA como um
gerenciador do protocolo
web+coffee
com o sistema operacional. - Na janela do PWA instalado, clique no link
https://protocol-handler-link.glitch.me/. Uma nova guia do navegador será aberta com três links. Clique no primeiro ou no segundo (latte macchiato ou
americano). O navegador mostrará uma solicitação e perguntará se o app é um
gerenciador de protocolos para o protocolo
web+coffee
. Se você concordar, o PWA será aberto e mostrará o café selecionado. - Para comparar com o fluxo tradicional que usa
navigator.registerProtocolHandler()
, clique no botão Registrar gerenciador de protocolo no PWA. Em seguida, na guia do navegador, clique no terceiro link (chai). Da mesma forma, um prompt será exibido, mas o PWA será aberto em uma guia, não em uma janela do navegador. - Envie para si mesmo uma mensagem em um aplicativo específico da plataforma, como o Skype no Windows, com um link como
<a href="web+coffee://americano">Americano</a>
e clique nele. Da mesma forma, o PWA instalado será aberto.
Considerações sobre segurança
Como a instalação do PWA exige que o contexto seja seguro, o processamento de protocolo herda essa restrição. A lista de gerenciadores de protocolo registrados não é exposta à Web de maneira alguma e, portanto, não pode ser usada como um vetor de técnicas de impressão digital.
Tentativas de navegação não iniciadas pelo usuário
As tentativas de navegação que não são iniciadas pelo usuário, mas que são programáticas, podem não abrir apps. O URL do protocolo personalizado só pode ser usado em contextos de navegação de nível superior, mas não, por exemplo, como o URL de um iframe.
Lista de permissões de protocolos
Assim como com registerProtocolHandler()
, há uma lista de permissões de protocolos que os apps podem registrar
para processar.
Solicitação de consentimento
Na primeira inicialização do PWA devido a um protocolo invocado, o usuário verá uma caixa de diálogo de permissões. Essa caixa de diálogo vai mostrar o nome e a origem do app e perguntar ao usuário se o app tem permissão para processar links do protocolo. Se um usuário rejeitar a caixa de diálogo de permissão, o gerenciador de protocolo registrado será ignorado pelo sistema operacional. Para cancelar o registro do gerenciador de protocolo, o usuário precisa desinstalar o PWA que o registrou. O navegador também cancelará a inscrição do gerenciador de protocolos se o usuário selecionar "Lembrar minha escolha" e "Não permitir".
Feedback
A equipe do Chromium quer saber mais sobre suas experiências com o registro de gerenciador de protocolo de URL para PWAs.
Fale sobre o design da API
Há algo na API que não funciona como você esperava? Ou há métodos ou propriedades ausentes que você precisa para implementar sua ideia? Tem alguma dúvida ou comentário sobre o modelo de segurança? Registre um problema de especificação no repositório do GitHub correspondente ou adicione suas ideias a um problema existente.
Informar um problema com a implementação
Você encontrou um bug na implementação do Chromium? Ou a implementação é diferente da especificação?
Registre um bug em new.crbug.com. Inclua o máximo de detalhes possível,
instruções simples para reprodução e insira UI>Browser>WebAppInstalls
na caixa
Componentes. O Glitch funciona muito bem para compartilhar repetições rápidas e fáceis.
Mostrar suporte à API
Você planeja usar o registro de gerenciador de protocolo de URL para PWAs? Seu apoio público ajuda a equipe do Chromium a priorizar recursos e mostra a outros fornecedores de navegadores como é fundamental oferecer suporte a eles.
Conte como você planeja usá-lo na conversa do discurso do WICG (em inglês). Envie um tweet para
@ChromiumDev com a hashtag
#ProtocolHandler
e conte para nós onde e como você está usando a hashtag.
Links úteis
Agradecimentos
O registro do gerenciador de protocolo de URL para PWAs foi implementado e especificado por Fabio Rocha, Diego González, Connor Moody e Samuel Tang, da equipe do Microsoft Edge. Este artigo foi revisado por Joe Medley e Fabio Rocha. Imagem principal de JJ Ying no Unsplash (links em inglês).