Registro do gerenciador de protocolo de URL para PWAs

Permita que os PWAs instalados processem links que usam um protocolo específico para uma experiência mais integrada.

Informações gerais sobre esquemas (ou protocolos)

Um Uniform Resource Identifier (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 dentro desse esquema. 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. Confira 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 Uniform Resource Locator (URL) se refere ao subconjunto de URIs que, além de identificar um recurso, fornecem um meio de localizá-lo, descrevendo o mecanismo de acesso primário (por exemplo, o local da rede).

Informações sobre o método registerProtocolHandler()

O método Navigator somente 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 da seguinte forma: 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 escapado a ser processado.

O esquema precisa ser um dos esquemas da lista de permissões (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 esclarecer isso, veja um exemplo concreto do fluxo:

  1. O usuário visita um site em https://coffeeshop.example.com/ que faz a seguinte chamada: navigator.registerProtocolHandler('web+coffee', 'coffee?type=%s').
  2. Mais tarde, 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>.
  3. 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 vai ler ?type=web+coffee://latte-macchiato.

O que é o processamento de protocolo

O atual mecanismo de registro do gerenciador de protocolos de URL para PWAs trata de oferecer o registro do gerenciador de protocolos como parte de uma instalação do PWA pelo manifesto. Depois de registrar um PWA como um gerenciador de protocolo, quando um usuário clica em um hiperlink com um esquema específico, como mailto, bitcoin ou web+music, em um navegador ou em um app específico da plataforma, o PWA registrado é aberto e recebe o URL. É importante observar que o registro com base no manifesto proposto e o registerProtocolHandler() tradicional desempenham papéis muito semelhantes na prática, permitindo a possibilidade de experiências do usuário complementares:

  • As semelhanças incluem requisitos relacionados à lista de esquemas permitidos para registro, o nome e o formato dos parâmetros etc.
  • As diferenças no registro baseado em manifesto são sutis, mas podem ser úteis para melhorar a experiência dos usuários de PWA. Por exemplo, o registro de PWA baseado em manifesto pode não exigir uma ação adicional do usuário além da instalação iniciada pelo usuário do PWA.

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, a PWA de apresentação é aberta automaticamente no escopo correto e mostra a apresentação de slides.
  • Em um app de chat específico da plataforma, o usuário recebe um link para um URL magnet em uma mensagem de chat. Ao clicar no link, um PWA de torrent instalado é iniciado e começa a fazer o download.
  • O usuário tem um app 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 nele, o PWA de streaming de música é iniciado automaticamente em uma janela independente.

Como usar o registro do gerenciador de protocolos de URL para PWAs

A API para registro do gerenciador de protocolos de URL é modelada de forma semelhante a navigator.registerProtocolHandler(). Desta vez, as informações são transmitidas de maneira declarativa por meio do manifesto do app da Web em uma nova propriedade chamada "protocol_handlers", que usa uma matriz de objetos com as duas chaves necessá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 necessá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 que se registram para o mesmo protocolo

Se vários aplicativos se registrarem como gerenciadores do mesmo esquema (por exemplo, o protocolo mailto), o sistema operacional mostrará ao usuário um seletor e permitirá que ele decida qual dos gerenciadores registrados será usado.

O mesmo app está se registrando para vários protocolos

O mesmo app pode se registrar para vários protocolos, conforme mostrado no exemplo de código acima.

Atualizações de apps e registro do gerenciador

Os registros de 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 app).
  • Uma atualização que remove processadores aciona o desregistro do processador (separado da desinstalação do app).

Depuração do gerenciador de protocolos no DevTools

Navegue até a seção Protocol Handlers no painel Application > Manifest. É possível visualizar e testar todos os protocolos disponíveis aqui.

Por exemplo, instale este PWA de demonstração. Na seção Protocol Handlers, digite "americano" e clique em Test protocol para abrir a página de café na PWA.

Gerenciadores de protocolo no painel &quot;Manifest&quot;

Demonstração

Confira uma demonstração do registro do gerenciador de protocolos de URL para PWAs no Glitch.

  1. Acesse https://protocol-handler.glitch.me/, instale o PWA e recarregue o app após a instalação. O navegador agora registrou o PWA como um gerenciador do protocolo web+coffee com o sistema operacional.
  2. Na janela do PWA instalado, clique no link https://protocol-handler-link.glitch.me/. Isso vai abrir uma nova guia do navegador com três links. Clique no primeiro ou no segundo (latte macchiato ou americano). O navegador vai mostrar uma solicitação e perguntar se você está de acordo com o app sendo um gerenciador de protocolo para o protocolo web+coffee. Se você concordar, o PWA vai abrir e mostrar o café selecionado.
  3. Para comparar com o fluxo tradicional que usa navigator.registerProtocolHandler(), clique no botão Registrar gerenciador de protocolo na PWA. Depois, na guia do navegador, clique no terceiro link (chai). Ele também mostrará um prompt, mas abrirá o PWA em uma guia, não em uma janela do navegador.
  4. Envie uma mensagem para você mesmo 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. Ele também precisa abrir o PWA instalado.

Demonstração do gerenciador de protocolos de URL com guia do navegador com links à esquerda e janela de PWA independente à direita.

Considerações sobre segurança

Como a instalação do PWA exige que o contexto seja seguro, o processamento de protocolos herda essa restrição. A lista de gerenciadores de protocolo registrados não é exposta na Web de forma alguma. Por isso, ela não pode ser usada como um vetor 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 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 no registerProtocolHandler(), há uma lista de permissões de protocolos que os apps podem registrar para processar.

No primeiro lançamento da PWA devido a um protocolo invocado, o usuário vai receber uma caixa de diálogo de permissão. 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 vai cancelar o registro do gerenciador de protocolo se o usuário selecionar "Lembrar minha escolha" e "Não permitir".

Feedback

A equipe do Chromium quer saber sobre suas experiências com o registro do gerenciador de protocolos de URL para PWAs.

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? Tem dúvidas ou comentários sobre o modelo de segurança? Envie um problema de especificação no repositório do GitHub correspondente ou adicione sua opinião 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 é ótimo para compartilhar reproduções rápidas e fáceis.

Mostrar suporte à API

Você planeja usar o registro do gerenciador de protocolos de URL para PWAs? Seu apoio público ajuda a equipe do Chromium a priorizar recursos e mostra a outros fornecedores de navegadores a importância de oferecer suporte a eles.

Compartilhe como você planeja usá-lo na discussão do Discourse do WICG. Envie um Tweet para @ChromiumDev usando a hashtag #ProtocolHandler e nos informe onde e como você está usando o recurso.

Agradecimentos

O registro do gerenciador de protocolos 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.