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á introduzindo esse recurso e quando você pode usá-lo.

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 teto do app principal. Esse tipo de arquitetura de site tem implicações no contexto de Apps Web Progressivos. 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 de janela (barra "fora do escopo") indicando que o usuário saiu da experiência do PWA. Para saber como contornar alguns desses problemas, leia os 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 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 para 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 quando se trata da interface do app da Web e da 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.

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

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: permita que os usuários naveguem entre origens associadas sem interromper a experiência do usuário, invocando a interface da janela que informa ao usuário que ele está saindo do PWA.
  • Captura de links entre origens: permite que os apps da Web capturem as navegações dos usuários para sites afiliados.

Navegação entre origens no escopo

Por padrão, quando os usuários navegam entre origens em um PWA independente, eles veem uma interface de janela indicando que 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 do aplicativo, mas podem perceber que estão sendo levadas para fora dele.

Barra fora do escopo na parte de cima de um PWA independente.

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, de modo que o PWA seja apresentado como uma experiência unificada.

A captura de links se refere à capacidade de um app de capturar links dentro do escopo dele. A forma como isso é implementado varia de acordo com os navegadores e sistemas operacionais. No Chrome no ChromeOS, por exemplo, os 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 desse ponto.

Solicitação da omnibox 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 que está fora do escopo do PWA (incluindo links para subdomínios ou domínios de nível superior), eles não serão reconhecidos como pertencentes 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)

{
  "id": "/",
  "name": "Example",
  "display": "standalone",
  "start_url": "/index.html",
  "scope_extensions": [
    { "type": "origin", "origin": "https://help.example.com" },
    { "type": "origin", "origin": "https://example.co.uk" },
    { "type": "origin", "origin": "https://help.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 web-app-origin-association e ser disponibilizado exatamente nesse local, já que é um URI conhecido.

/.well-known/web-app-origin-association (origem associada)

{
  "https://example.com/": {
    "scope": "/"
  }
}

O arquivo lista os apps da Web com que a origem se associa. Cada chave é o ID do manifesto do app da Web, e cada valor pode definir um escopo opcional que é relativo à origem associada. Se você deixar o escopo de fora, o padrão será "/".

Demonstração

A demonstração consiste em dois sites:

Para realizar os testes a seguir, é necessário ativar a flag about://flags/#enable-desktop-pwas-scope-extensions (disponível a partir do Chrome v115).

Testar a navegação entre origens

Como condição prévia 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 que não está no escopo estendido.

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

PWA de demonstração com links para a origem no escopo estendido e a origem fora do escopo estendido.

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

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

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

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 (no escopo estendido)

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

Janela principal do PWA sem a barra de fora do escopo depois de 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 as extensões de escopo.

  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 um aviso é mostrado para abri-lo no PWA instalado.

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

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

Se você quiser testar essa API no seu aplicativo em campo com usuários reais, faça isso com um teste de origem. Os testes de origem permitem que você teste recursos experimentais com seus usuários ao receber um token de teste vinculado ao seu domínio. Em seguida, implante o app e espere que ele funcione em um navegador compatível com o recurso que você está testando (neste caso, ele está disponível no Chrome de 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 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

Agradecimentos

Agradecemos especialmente à 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.