No Chrome 122, é possível se inscrever no teste de origem do membro do manifesto do app scope_extensions
,
que permite que sites que controlam vários subdomínios e domínios
de nível superior sejam apresentados como um único app da Web. Este documento explica por que
a equipe do Chrome está lançando esse recurso e quando você pode querer usá-lo.
Visão geral
Alguns aplicativos da Web têm várias
origens. Por
exemplo, example.com
como o app principal e depois space_1.example.com
, ...,
space_n.example.com
, às vezes combinados com special-example.com
, como
subexperiências, tudo sob o teto do app principal. Esse tipo de arquitetura
de site tem implicações no contexto dos Progressive Web Apps.
As limitações incluem a impossibilidade de compartilhar service workers, qualquer tipo de dispositivo,
armazenamento local e permissões entre origens. Além disso, a navegação de origem cruzada em
um PWA autônomo mostra uma interface de janela (barra "fora do escopo") indicando que o usuário
saiu da experiência do PWA. Saiba como resolver alguns
desses problemas nos artigos
Progressive Web Apps em sites de várias origens
e
Como criar vários Progressive Web Apps no mesmo domínio.
Com a API Scope Extensions, os apps da Web superam alguns dos desafios impostos pela política de mesma origem nesse tipo de arquitetura de site. Ele permite que os apps da Web estendam o escopo a outras origens para ajudar a alcançar uma experiência unificada, de acordo com o acordo entre a origem principal do app da Web e as origens associadas.
Objetivos
O objetivo principal da API Scope Extensions é que os sites que controlam
vários subdomínios e domínios de nível superior se comportem como um app da Web contíguo
quando se trata de captura de links e interface de apps da Web. Por exemplo, permitir que o site
example.com
, que abrange example.com.co.uk
e support.example.com
, se comporte
o máximo possível como um único aplicativo da Web.
As extensões de escopo permitem que os PWAs de várias origens se comportem como um app da Web contíguo quando se trata de interface de app da Web.
Na prática, isso se traduz em duas metas mais específicas:
- Navegação de origem cruzada: permita que os usuários naveguem por origens associadas sem interromper a experiência do usuário invocando a interface da janela informando que ele está se afastando do PWA.
- Captura de links de origem cruzada: permite que apps da Web capturem as navegações dos usuários para sites a que estão afiliados.
Navegação no escopo de origem cruzada
Por padrão, quando os usuários navegam pelas origens em um PWA autônomo, eles recebem uma interface de janela indicando que estão migrando da experiência do PWA. No Chrome, essa interface consiste em uma barra "fora do escopo" que contém o URL da nova origem. Isso prejudica a experiência do usuário, porque ele espera continuar navegando dentro do mesmo contexto de aplicativo, mas pode perceber que está sendo removido dele.
Barra "fora do escopo" mostrada no Chrome quando os usuários navegam em diferentes origens em um PWA autônomo.
Com as extensões de escopo, a interface da janela não é mostrada quando os usuários navegam para qualquer uma das origens associadas. Portanto, o PWA é apresentado como uma experiência unificada.
Captura de links de origem cruzada
A captura de link se refere à capacidade de um app de capturar links dentro do escopo. A maneira como isso é implementado varia entre navegadores e sistemas operacionais. No Chrome no ChromeOS, por exemplo, links no escopo de um PWA instalado abrem por padrão uma guia do navegador com uma indicação na barra de endereço de que há um app capaz de processar esses links, permitindo que o usuário ative a captura automática de links a partir daquele ponto.
Fragmento da barra de endereço do Chrome para uma guia no ChromeOS, mostrando uma indicação visual de que o link pode ser processado por um PWA e a opção de lembrar essa decisão.
Se um usuário clicar em um link fora do escopo do PWA (incluindo links para subdomínios ou domínios de nível superior), ele não será reconhecido como pertencente a ele. Por exemplo, os links serão abertos em uma guia do navegador sem qualquer indicação para o usuário de que há um app capaz de processar o link. A API Scope Extensions permite ampliar o escopo do PWA para que as origens associadas sejam tratadas como links no escopo.
Implementação
A implementação de extensões de escopo requer o estabelecimento da relação entre a origem principal e as associadas.
Declarar a lista de origens associadas
Adicione um membro do manifesto do app da Web scope_extensions
à origem principal do PWA para
permitir que o app da Web estenda o escopo a outras origens.
Manifesto do app da Web (https://example.com)
{
"name": "Example",
"display": "standalone",
"start_url": "/index.html",
"scope_extensions": [
{ "origin": "https://*.example.com" },
{ "origin": "https://example.co.uk" },
{ "origin": "https://*.example.co.uk" }
]
}
Confirmar associações
Cada uma das origens listadas confirma a associação com o app da Web usando um
arquivo de configuração /.well-known/web-app-origin-association
. Esse arquivo precisa
ser chamado de web-app-origin-association
e ser exibido nesse local exato, já que
é um URI conhecido.
/.well-known/web-app-origin-association (origem associada)
{
"web_apps": [{ "web_app_identity": "https://example.com" }]
}
Demonstração
A demonstração consiste em dois sites:
- PWA principal: o PWA real que
declara a lista de origens associadas por meio do membro
scope_extensions
no manifesto do app da Web. - Origem no escopo estendido: uma
origem fora do escopo principal do PWA, mas associada a ele depois de ser listada
pelo PWA principal como uma origem associada e confirmar a relação
por meio do
arquivo
web-app-origin-association
.
Para executar os testes abaixo, é necessário ativar a
flag about://flags/#enable-desktop-pwas-scope-extensions
(disponível a partir
do Chrome v115).
Testar a navegação de origem cruzada
Como pré-condição para esses testes, abra o PWA principal em um navegador, instale-o como um PWA e abra-o para executá-lo no modo independente. O PWA contém links para uma origem no escopo estendido e para uma origem não no escopo estendido.
Demonstração de PWA com links para a origem no escopo estendido e origem não no escopo estendido.
Navegação de origem cruzada padrão (não no escopo estendido)
- Clique no link para a origem não no escopo estendido no PWA em tela cheia.
- Como resultado, a navegação acontece e a barra fora do escopo é mostrada.
Barra "fora do escopo" mostrada por padrão para navegação de origem cruzada para um PWA no modo independente.
Navegação de origem cruzada com extensões de escopo (em escopo estendido)
- Volte para a página inicial do PWA.
- Clique no link para a origem não está no escopo estendido.
- Por padrão, uma barra "fora do escopo" é exibida, mas, devido à associação das extensões de escopo, ela não é.
A barra "Fora do escopo" não é mostrada na navegação de origem cruzada após a associação da origem com as extensões de escopo.
Testar a captura de links de origem cruzada
- Abra e instale o PWA principal em um dispositivo ChromeOS.
- Clique neste link: associação de origem.
- O link é aberto em uma nova guia do navegador, e um prompt é exibido para abri-lo no PWA instalado.
Clicar em um link para a origem associada a um PWA abre o link em uma nova guia e mostra um ícone "Abrir no app", permitindo que o usuário ative a captura automática de links.
Teste de origem
Para testar essa API no seu aplicativo com usuários reais, use um teste de origem. Com os testes de origem, você pode testar recursos experimentais com seus usuários usando um token de teste vinculado ao seu domínio. Em seguida, você pode implantar o app e esperar que ele funcione em um navegador compatível com o recurso testado. Nesse caso, ele está disponível no Chrome da versão 121 a 126. Para receber seu próprio token e executar um teste de origem, preencha o formulário de inscrição.
Feedback
A equipe do Chrome quer receber feedback sobre a utilidade dessa API. Para ajudar a equipe a fazer essa API evoluir com feedback sobre a utilidade dela e novos casos de uso não abordados na versão atual, abra um problema no GitHub.
Outros recursos
- API Scope Extensions: teste de origem
- Status do Chrome: extensões do escopo do app da Web
- Explicação sobre as extensões de escopo para aplicativos da Web
- Intenção de fazer experimentos
- Posição dos Padrões do Mozilla (em inglês)
- Posição nos padrões da Apple
- Bug do Chromium
- Progressive Web Apps em sites com várias origens
- Como criar vários Progressive Web Apps no mesmo domínio
Agradecimentos
Um agradecimento especial à equipe responsável pelo desenvolvimento dessa API. As extensões de escopo foram especificadas por Alan Cutter e Lu Huang, com contribuição de Matt Giuca. A API foi implementada por Alan Cutter, do Google Chrome e Hassan Talat, Kristin Lee e Lu Huang do Microsoft Edge.