Migrazione dell'origine PWA senza interruzioni: cambia i domini senza perdere gli utenti

Dibyajyoti Pal

Dan Murphy

Marijn Kruisselbrink

Data di pubblicazione: 3 giugno 2026

Le app web progressive (PWA) hanno rivoluzionato il web offrendo esperienze simili a quelle delle app. Tuttavia, uno dei loro maggiori punti di forza è stato anche una sfida persistente: l'identità dell'app è strettamente legata all'origine web.

Per eseguire il rebranding o la ristrutturazione dell'architettura (ad esempio, il passaggio da www.example.com/social a social.example.com), dovevi affrontare un dilemma difficile. Non era possibile "spostare" una PWA installata. Gli utenti sono stati costretti a disinstallare manualmente la vecchia app e trovare il pulsante di installazione per quella nuova.

Il team PWA è felice di presentare la migrazione dell'origine PWA in Chrome 150. Questa nuova funzionalità della piattaforma ti consente di eseguire la transizione senza problemi delle PWA installate a una nuova origine dello stesso sito con interruzioni minime per l'utente, mantenendolo comunque sufficientemente informato.

Cosa consente la migrazione dell'origine

Puoi modificare l'architettura del tuo sito senza compromettere l'esperienza utente:

• Libertà di architettura tecnica: modifica il sottodominio o il percorso della tua applicazione.
• Correzione degli stati delle app suddivise: risolvi il problema per cui la modifica di un start_url senza un ID stabile creava accidentalmente installazioni duplicate dell'app.

Gli utenti possono eseguire la migrazione delle loro app con una semplice finestra di dialogo di aggiornamento. Vengono informati della migrazione in modo simile a un aggiornamento standard dell'app. Con un solo clic, la vecchia app viene disinstallata e la nuova app viene installata e avviata.

Come eseguire la migrazione di una PWA

Per eseguire la migrazione di una PWA, segui questi passaggi. Il resto del post entra più nel dettaglio:

1. Esegui il deployment dell'handshake:
   • Aggiungi migrate_from alla nuova app.
   • Aggiungi il campo allow_migration al file /.well-known/web-app-origin-association nell'origine precedente.
2. Scegli il comportamento:suggest (o vuoto) evita di interrompere l'utente, probabilmente utile durante l'implementazione iniziale. force blocca l'utente e richiede la migrazione se l'utente non può continuare a utilizzare i vecchi URL.
3. Mantieni aggiornata la vecchia app:se il vecchio sito reindirizza al nuovo sito, utilizza la proprietà install_url nel blocco migrate_from per assicurarti che il browser possa ancora trovare il vecchio manifest per potenziali aggiornamenti.
4. Implementa id nel manifest di destinazione: Chrome richiede che il manifest dell'app di destinazione includa un campo id. In questo modo, l'app non può commettere l'errore comune di creare app suddivise modificando start_url senza aver impostato un id.

L'handshake bidirezionale: come funziona

Per garantire la sicurezza e impedire acquisizioni ostili, la migrazione richiede un handshake sicuro tra le origini vecchie e nuove. Questo handshake garantisce che entrambi i siti siano controllati dalla stessa entità.

Passaggio 1: la nuova app dichiara il predecessore (obbligatorio)

Aggiungi un campo migrate_from al file manifest dell'app web della nuova applicazione.

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

Passaggio 2: la vecchia origine conferma la migrazione (obbligatorio)

Per impedire a un nuovo sito di appropriarsi unilateralmente di una vecchia app, l'origine precedente deve autorizzare esplicitamente la migrazione. Lo fa con un file di configurazione .well-known.

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

(Facoltativo) Passaggio 3: segnalazione proattiva

Per attivare l'aggiornamento senza attendere che l'utente visiti il nuovo sito, aggiorna il manifest dell'app precedente in modo che punti a quello nuovo.

// 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"
  }
}

(Facoltativo) Passaggio 4: gestisci i reindirizzamenti

In alternativa all'utilizzo del campo migrate_to, puoi segnalare la migrazione reindirizzando i vecchi URL dell'app alla nuova app e facendo affidamento su scope_extensions per evitare che il banner fuori ambito venga visualizzato nella vecchia app. Ciò significa che il manifest della vecchia app non verrà mai visualizzato e quindi non potrà mai essere aggiornato. Per consentire alla vecchia app di continuare ad aggiornarsi prima della migrazione dell'app, imposta install_url all'interno di migrate_from per comunicare al browser un URL da recuperare che abbia ancora il vecchio manifest allegato senza reindirizzamento.

// 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"
    }
  ]
}

È tutto. L'esperienza utente è simile a quella utilizzata per l'aggiornamento delle app, dove l'utente riceve una notifica nell'angolo in alto a destra della finestra dell'app:

Se fai clic su Rivedi aggiornamento dell'app, viene visualizzata la seguente UX (a seconda di cosa è cambiato nel manifest):

Controllare l'esperienza utente

Puoi scegliere il livello di aggressività della migrazione utilizzando il flag behavior:

1. Suggerisci (impostazione predefinita): l'utente riceve una notifica passiva (ad esempio nel menu dell'app). Possono scegliere di aggiornare o disinstallare l'app oppure ignorare la migrazione avviando la finestra di dialogo.
2. Forza:al successivo avvio dell'app, l'utente visualizza una finestra di dialogo di blocco. Deve eseguire l'aggiornamento alla nuova origine o disinstallare l'app (vedi lo screenshot seguente).

Il seguente esempio mostra come impostare questa scelta:

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

Conclusione

La funzionalità di migrazione delle PWA consente agli sviluppatori di continuare a creare architetture web moderne e flessibili senza lasciare indietro gli utenti.