Migração de origem da PWA sem interrupções: mude de domínio sem perder usuários

Dibyajyoti Pal

Dan Murphy

Marijn Kruisselbrink

Publicado em: 3 de junho de 2026

Os Progressive Web Apps (PWAs) revolucionaram a Web ao oferecer experiências semelhantes a apps. No entanto, um dos maiores pontos fortes também tem sido um desafio constante: a identidade do app está fortemente vinculada à origem da Web.

Para mudar a marca ou reestruturar sua arquitetura (por exemplo, migrar de www.example.com/social para social.example.com), você enfrentou um dilema difícil. Não havia como "mover" um PWA instalado. Os usuários eram obrigados a desinstalar manualmente o app antigo e encontrar o botão de instalação do novo.

A equipe de PWA tem o prazer de apresentar a migração de origem de PWA no Chrome 150. Com esse novo recurso da plataforma, é possível fazer a transição de PWAs instalados para uma origem nova no mesmo site com interrupção mínima para o usuário, mantendo-o informado.

O que a migração de origem permite

É possível modificar a arquitetura do site sem prejudicar a experiência do usuário:

• Liberdade de arquitetura técnica:mude o subdomínio ou o caminho do seu aplicativo.
• Correção dos estados de app dividido:resolvemos o problema em que a mudança de um start_url sem um ID estável criava acidentalmente instalações de app duplicadas.

Os usuários podem migrar os apps com uma caixa de diálogo de atualização simples. Eles são informados sobre a migração de maneira semelhante a uma atualização do app padrão. Com um único clique, o app antigo é desinstalado e o novo é instalado e iniciado.

Como migrar uma PWA

Para migrar um PWA, siga estas etapas. O restante da postagem entra em mais detalhes:

1. Implante o handshake:
   • Adicione migrate_from ao novo app.
   • Adicione o campo allow_migration ao arquivo /.well-known/web-app-origin-association na origem antiga.
2. Escolher comportamento:suggest (ou vazio) evita interromper o usuário, o que provavelmente é útil durante um lançamento inicial. force bloqueia o usuário e exige a migração se ele não puder continuar usando os URLs antigos.
3. Mantenha o app antigo atualizado:se o site antigo redirecionar para o novo, use a propriedade install_url no bloco migrate_from para garantir que o navegador ainda possa encontrar o manifesto antigo para possíveis atualizações.
4. Implemente id no manifesto de destino:o Chrome exige que o manifesto do app de destino inclua um campo id. Isso garante que o app não cometa o erro comum de criar apps divididos mudando o start_url sem ter um id definido.

O handshake bidirecional: como funciona

Para garantir a segurança e evitar aquisições hostis, a migração exige um handshake seguro entre as origens antiga e nova. Esse handshake garante que os dois sites sejam controlados pela mesma entidade.

Etapa 1: o novo app declara o antecessor (obrigatório)

Adicione um campo migrate_from ao manifesto do app da Web do aplicativo novo.

// Manifest at https://fileman.google.com/manifest.json
{
  "name": "File Manager",
  "id": "/files/",
  "start_url": "/files/index.html",
  ....
  "migrate_from": [
    "https://drive.google.com/"
  ]
}

Etapa 2: a origem antiga confirma a migração (obrigatório)

Para evitar que um novo site sequestre unilateralmente um app antigo, a origem antiga precisa autorizar explicitamente a migração. Isso é feito com um arquivo de configuração .well-known.

// File at https://drive.google.com/.well-known/web-app-origin-association
{
  "https://fileman.google.com/files/": {
    "allow_migration": true
  }
}

Etapa 3: sinalização proativa (opcional)

Para acionar a atualização sem esperar que o usuário visite o novo site, atualize o manifesto do app antigo para apontar para o novo.

// Manifest at https://drive.google.com/manifest.json
{
  "name": "Drive",
  "start_url": "/",
  "migrate_to": {
    "id": "https://fileman.google.com/files/",
    "install_url": "https://fileman.google.com/drive/installwebapp?usp=migrate"
  }
}

Etapa 4: processar redirecionamentos (opcional)

Como alternativa ao uso do campo migrate_to, é possível sinalizar a migração redirecionando os URLs do app antigo para o novo e contando com o scope_extensions para que o banner fora do escopo não seja exibido no app antigo. Isso significa que o manifesto do app antigo nunca será visto e, portanto, nunca poderá ser atualizado. Para permitir que o app antigo continue sendo atualizado antes da migração, defina o install_url dentro de migrate_from para informar ao navegador um URL a ser buscado que ainda tenha o manifesto antigo anexado sem redirecionamento.

// Manifest at https://fileman.google.com/manifest.json
{
  "name": "File Manager",
  "id": "/files/",
  "start_url": "/files/index.html",
  ....
  "migrate_from": [
    {
      "id": "https://drive.google.com/",
      "install_url": "https://drive.google.com/drive/installwebapp?usp=migrate"
    }
  ]
}

Pronto! A UX é semelhante à usada para atualização de apps, em que o usuário recebe uma notificação no canto superior direito da janela do app:

Ao clicar em Analisar atualização do app, a seguinte UX é mostrada (dependendo do que mudou no manifesto):

Controlar a experiência do usuário

Você pode escolher a intensidade da migração usando a flag behavior:

1. Sugerir (padrão): o usuário recebe uma notificação passiva (por exemplo, no menu do app). Eles podem atualizar, desinstalar o app ou ignorar a migração abrindo a caixa de diálogo.
2. Forçar:no próximo lançamento do app, o usuário vai receber uma caixa de diálogo de bloqueio. Ele precisa atualizar para a nova origem ou desinstalar o app (confira a captura de tela a seguir).

O exemplo a seguir mostra como definir essa opção:

"migrate_from": [
  { 
    "id": "https://example.com/social/",
    "behavior": "force" // or suggest
  }
]

Conclusão

Com o recurso de migração de PWAs, os desenvolvedores podem continuar criando arquiteturas da Web modernas e flexíveis sem deixar os usuários para trás.