Esta página foi traduzida pela API Cloud Translation.

Extensões de escopo de apps da Web

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.

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 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.

Diagrama mostrando um PWA principal e as subexperiências associadas.

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.

Fora da barra de escopo na parte superior de um PWA independente.

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.

Solicitação 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 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.

Janela principal de PWA com links no escopo e 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.

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

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 é.

Janela principal do PWA sem a barra de escopo depois de clicar no link de escopo estendido.

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.

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

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

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.