Esta página foi traduzida pela API Cloud Translation.

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.

Thomas Steiner

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. 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. 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 do recurso 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 assim: 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 esquema 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, confira um exemplo concreto do fluxo:

O usuário acessa um site em https://coffeeshop.example.com/ que faz a seguinte chamada: navigator.registerProtocolHandler('web+coffee', 'coffee?type=%s').
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>.
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 mecanismo atual de registro do gerenciador de protocolos de URL para PWAs (link em inglês) é sobre oferecer o registro do gerenciador de protocolos como parte de uma instalação de 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 proposto baseado em manifesto e o registerProtocolHandler() tradicional desempenham funções muito semelhantes na prática, permitindo a possibilidade de experiências complementares do usuário:

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 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 forma declarativa pelo manifesto do app da Web em uma nova propriedade chamada "protocol_handlers", que recebe 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 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 processadores para o mesmo esquema, por exemplo, o protocolo mailto, o sistema operacional vai mostrar ao usuário um seletor e permitir que ele decida qual dos processadores registrados usar.

O mesmo app se registra 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 de manipuladores

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. Confira e teste 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 "Manifest"

Demonstração

Confira uma demonstração do registro do gerenciador de protocolos 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 agora registrou o PWA como um gerenciador do protocolo web+coffee com o sistema operacional.
Na janela da PWA instalada, 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ê concorda que o app seja um gerenciador de protocolo para o protocolo web+coffee. Se você concordar, o PWA vai abrir e mostrar o café selecionado.
Para comparar com o fluxo tradicional que usa navigator.registerProtocolHandler(), clique no botão Registrar gerenciador de protocolo na PWA. Em seguida, na guia do navegador, clique no terceiro link (chai). Ele também vai mostrar um comando, mas vai abrir o PWA em uma guia, não em uma janela do navegador.
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 protocolo 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 protocolo herda essa restrição. A lista de manipuladores de protocolo registrados não é exposta à Web de nenhuma forma, portanto, 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.

Solicitação de consentimento

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 mostra o nome e a origem do app e pergunta ao usuário se ele 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 digite UI>Browser>WebAppInstalls na caixa Components. O Glitch é ótimo para compartilhar reprosagens rápidas e fáceis.

Mostrar suporte para a 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.

Links úteis

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.