Esta página foi traduzida pela API Cloud Translation.

Extensões de escopo de apps da Web

No 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 app da Web. Este documento explica por que a equipe do Chrome está lançando esse recurso e quando você pode 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, em seguida, space_1.example.com, …, space_n.example.com, às vezes combinados com special-example.com, como subexperiências, tudo sob o mesmo 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 independente mostra uma interface de janela ("barra fora do escopo") indicando que o usuário saiu da experiência do PWA. Você pode aprender a contornar alguns desses problemas nos artigos Progressive Web Apps em sites de várias origens e Criação de vários Progressive Web Apps no mesmo domínio.

A API Scope Extensions permite que os 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 a outras origens para ajudar a alcançar uma experiência unificada, considerando o acordo entre a origem principal do app da Web e as origens associadas.

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 único app da Web contíguo no que se refere à interface 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 mais possível como um único aplicativo da Web.

Diagrama mostrando um PWA principal e subexperiências associadas.

As extensões de escopo permitem que PWAs de várias origens se comportem como um app da Web contíguo em relação à 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, invocando a interface da janela informando que ele está saindo da PWA.
Captura de links entre origens:permita que os apps da Web capturem as navegações dos usuários para sites aos quais eles estão afiliados.

Navegação de origem cruzada no escopo

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 atrapalha a experiência do usuário, já que as pessoas esperam continuar navegando no mesmo contexto do aplicativo, mas podem perceber que estão sendo retiradas dele.

Barra "Out of scope" na parte de cima de um PWA independente.

Barra "Fora do escopo" mostrada no Chrome quando os usuários navegam por diferentes origens em uma PWA autônoma.

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

Captura de links de origem cruzada

Captura de links refere-se à capacidade de um app capturar links dentro do escopo. A forma de implementação varia de acordo com os navegadores e sistemas operacionais. No Chrome no ChromeOS, por exemplo, os links no escopo de um PWA instalado abrem 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.

Solicitação da Omnibar para um PWA instalado.

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 da PWA (incluindo links para subdomínios ou domínios de nível superior), ele não será reconhecido como pertencente a ela. Por exemplo, os links serão abertos em uma guia do navegador sem nenhuma indicação ao usuário de que há um app capaz de processar o link. A API Scope Extensions permite estender o escopo da 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 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 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 nomeado como web-app-origin-association e ser enviado nesse local exato, porque é 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 do PWA principal, mas associada a ele depois de ser listada pelo PWA principal como uma origem associada e confirmar o relacionamento pelo arquivo web-app-origin-association.

Para realizar os testes a seguir, ative a flag about://flags/#enable-desktop-pwas-scope-extensions (disponível a partir da Chrome v115).

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-o para executá-lo no modo independente. A PWA contém links para uma origem no escopo estendido e para uma origem que não está no escopo estendido.

Janela principal do PWA com links de escopo e de escopo estendido.

Demonstração de PWA com links para a origem em escopo estendido e origem que não estão no escopo estendido.

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

Clique no link para a origem não está no escopo estendido no PWA em tela cheia.
Como resultado, a navegação acontece e a barra fora do escopo é exibida.

Janela principal da PWA com a barra fora do escopo depois de clicar no link fora do escopo.

Barra "Fora do escopo" mostrada por padrão para uma navegação de origem cruzada para um PWA no modo independente.

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

Volte para a página inicial da PWA.
Clique no link para a origem não está no escopo estendido.
Por padrão, uma barra "fora do escopo" precisa ser mostrada, mas, devido à associação de extensões de escopo, ela não é.

Janela principal da PWA sem a barra de fora do escopo após clicar no link de escopo estendido.

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

Testar a captura de links de diferentes origens

Abra e instale a PWA principal em um dispositivo ChromeOS.
Clique no seguinte link: origem associada.
O link será aberto em uma nova guia do navegador e um prompt será mostrado para abri-lo no PWA instalado.

Solicitação da Omnibar para um PWA instalado com escopo estendido.

Clicar em um link para a origem associada de uma 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

Se você quiser testar essa API no seu aplicativo 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. Em seguida, é possível implantar o app e esperar que ele funcione em um navegador compatível com o recurso que você está testando. Nesse caso, ele está disponível no Chrome 121 a 126. Para ter 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 (link em inglês).

Outros recursos

Agradecimentos

Agradecemos especialmente à equipe por trás do desenvolvimento desta API. As extensões de escopo foram especificadas por Alan Cutter e Lu Huang, com entrada de Matt Giuca. A API foi implementada por Alan Cutter, do Google Chrome, e Hassan Talat, Kristin Lee e Lu Huang, do Microsoft Edge.