Extensões de escopo de apps da Web

A partir do Chrome 122, você pode 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 web app. Este documento explica por que a equipe do Chrome está lançando esse recurso e quando você pode querer usá-lo.

Demián Renzulli

Thomas Steiner

Visão geral

Alguns aplicativos da Web têm várias origens, por exemplo, example.com como o app principal e space_1.example.com, …, space_n.example.com, às vezes combinados com special-example.com, como subexperiências, tudo sob o mesmo app principal. Esse tipo de arquitetura de site tem implicações no contexto dos PWAs. As limitações incluem não poder compartilhar service workers, qualquer tipo de dispositivo, armazenamento local e permissões entre origens. Além disso, a navegação entre origens em um PWA independente mostra uma interface do usuário da janela (barra "fora do escopo") indicando que o usuário saiu da experiência do PWA. Saiba como contornar alguns desses problemas nos artigos Apps Web Progressivos em sites de várias origens e Como criar vários Apps Web Progressivos no mesmo domínio.

A API Scope Extensions permite que apps da Web superem alguns dos desafios que a política de mesma origem impõe a esse tipo de arquitetura de site. Ele permite que os apps da Web estendam o escopo para outras origens e ajudem a alcançar uma experiência unificada, desde que haja um acordo entre a origem principal do app da Web e as origens associadas.

Observação: no momento da redação deste artigo, apenas o ChromeOS é compatível com os dois recursos das extensões de escopo abordados neste documento (navegação no escopo entre origens e captura de links entre origens). A navegação entre origens no escopo também é compatível com o Chrome no Windows, macOS e Linux, mas a integração com a captura de links ainda não está disponível nessas plataformas. As extensões de escopo ainda não estão disponíveis em dispositivos móveis.

Metas

O principal objetivo da API Scope Extensions é permitir que 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 interface do usuário do app da Web e captura de links. 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 PWAs de várias origens se comportem como um app da Web contíguo quando se trata da interface do app da Web.

Na prática, isso se traduz em duas metas mais específicas:

• Navegação entre origens:permite que os usuários naveguem entre origens associadas sem interromper a experiência do usuário. Para isso, invoca a interface do usuário da janela, informando que o usuário está saindo do PWA.
• Captura de links de origem cruzada:permite que apps da Web capturem navegações do usuário para sites afiliados.

Navegação no escopo entre origens

Por padrão, quando os usuários navegam entre origens em um PWA independente, uma interface de janela é mostrada indicando que eles estão saindo 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, já que as pessoas esperam continuar navegando no mesmo contexto de aplicativo, mas podem perceber que estão sendo retiradas dele.

Barra "Fora do escopo" mostrada no Chrome quando os usuários navegam por diferentes origens em um PWA independente.

Com as extensões de escopo, a interface da janela não será mostrada quando os usuários navegarem para qualquer uma das origens associadas. Assim, o PWA é apresentado como uma experiência unificada.

Captura de links entre origens

A captura de links se refere à capacidade de um app capturar links no escopo dele. A forma como isso é implementado varia entre navegadores e sistemas operacionais. No Chrome no ChromeOS, por exemplo, os links no escopo de uma PWA instalada 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 desse 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 ao usuário de que há um app capaz de processar o link. A API Scope Extensions permite estender o escopo do PWA para que as origens associadas sejam tratadas como links no escopo.

Implementação

Para implementar extensões de escopo, é necessário estabelecer a relação entre a origem principal e as origens 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 para 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 web app usando um arquivo de configuração /.well-known/web-app-origin-association. Esse arquivo precisa ser nomeado como web-app-origin-association e veiculado 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 pelo 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 pelo arquivo web-app-origin-association.

Para realizar os testes a seguir, ative a flag about://flags/#enable-desktop-pwas-scope-extensions (disponível no Chrome v115 e versões mais recentes).

Testar a navegação entre origens

Como pré-condição para esses testes, abra o PWA principal em um navegador, instale-o como um PWA e abra 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.

PWA de demonstração com links para origem no escopo estendido e origem não no escopo estendido.

Navegação entre origens padrão (não no escopo estendido)

1. Clique no link para a origem não incluída no escopo estendido dentro do PWA em tela cheia.
2. Como resultado, a navegação acontece e a barra fora do escopo é mostrada.

A barra "Fora do escopo" mostrada por padrão para uma navegação entre origens de um PWA no modo independente.

Navegação entre origens com extensões de escopo (em escopo estendido)

1. Volte para a página inicial do PWA.
2. Clique no link para a origem fora do escopo estendido.
3. Por padrão, uma barra "fora do escopo" deve ser mostrada, mas devido à associação de extensões de escopo, isso não acontece.

A barra "Fora do escopo" não é mostrada na navegação entre origens depois que a associação de origem é feita com as extensões de escopo.

Testar a captura de links de diferentes origens

1. Abra e instale o PWA principal em um dispositivo ChromeOS.
2. Clique no seguinte link: origem associada.
3. O link é aberto em uma nova guia do navegador, e uma solicitação é mostrada para abri-lo no PWA instalado.

Ao clicar em um link para a origem associada de um PWA, ele é aberto 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

Se quiser testar essa API no seu aplicativo em campo com usuários reais, faça isso com um teste de origem. Com os testes de origem, você pode testar recursos experimentais com seus usuários ao receber um token de teste vinculado ao seu domínio. Depois, implante o app e espere que ele funcione em um navegador compatível com o recurso que você está testando. Nesse caso, ele está disponível no Chrome da versão 121 à 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 saber se essa API é útil. Para ajudar a equipe a desenvolver essa API 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 de escopo de apps da Web
• Explicação sobre extensões de escopo para aplicativos da Web
• Intenção de experimentar
• Posição da Mozilla sobre padrões
• Posição de padrões da Apple
• Bug do Chromium
• Progressive Web Apps em sites de várias origens
• Como criar vários Progressive Web Apps no mesmo domínio

Agradecimentos

Agradecemos à equipe responsável pelo desenvolvimento dessa API. As extensões de escopo foram especificadas por Alan Cutter e Lu Huang, com contribuições de Matt Giuca. A API foi implementada por Alan Cutter do Google Chrome e Hassan Talat, Kristin Lee e Lu Huang do Microsoft Edge.