Migrasi origin PWA yang lancar: Mengubah domain tanpa kehilangan pengguna

Dibyajyoti Pal

Dan Murphy

Marijn Kruisselbrink

Dipublikasikan: 3 Juni 2026

Progressive Web App (PWA) telah merevolusi web dengan menawarkan pengalaman seperti aplikasi. Namun, salah satu kekuatan terbesar mereka juga menjadi tantangan yang terus-menerus: identitas aplikasi sangat terkait dengan origin web.

Untuk melakukan rebranding atau merestrukturisasi arsitektur (misalnya, beralih dari www.example.com/social ke social.example.com), Anda menghadapi dilema yang menyulitkan. Tidak ada cara untuk "memindahkan" PWA yang diinstal. Pengguna dipaksa meng-uninstal aplikasi lama secara manual dan menemukan tombol instal untuk aplikasi baru.

Tim PWA dengan senang hati memperkenalkan Migrasi Origin PWA di Chrome 150. Fitur platform baru ini memungkinkan Anda mentransisikan PWA yang diinstal dengan lancar ke origin situs yang sama yang baru dengan gangguan minimal bagi pengguna, sekaligus tetap memastikan pengguna mendapatkan informasi yang memadai.

Yang dapat dilakukan migrasi origin

Anda dapat mengubah arsitektur situs tanpa merusak pengalaman pengguna:

• Kebebasan arsitektur teknis: Ubah subdomain atau jalur aplikasi Anda.
• Memperbaiki status aplikasi terpisah: Mengatasi masalah saat mengubah start_url tanpa ID stabil secara tidak sengaja membuat penginstalan aplikasi duplikat.

Pengguna dapat memigrasikan aplikasi mereka dengan dialog update sederhana. Pengguna diberi tahu tentang migrasi dengan cara yang serupa dengan update aplikasi standar. Dengan satu klik, aplikasi lama akan di-uninstal dan aplikasi baru akan diinstal serta diluncurkan.

Cara memigrasikan PWA

Untuk memigrasikan PWA, ikuti langkah-langkah berikut. Bagian selanjutnya dalam postingan ini akan membahasnya secara lebih mendetail:

1. Deploy handshake:
   • Tambahkan migrate_from ke aplikasi baru.
   • Tambahkan kolom allow_migration ke file /.well-known/web-app-origin-association di origin lama.
2. Pilih perilaku: suggest (atau kosong) menghindari gangguan terhadap pengguna, dan kemungkinan berguna selama peluncuran awal. force memblokir pengguna dan memerlukan migrasi, jika pengguna tidak dapat terus menggunakan URL lama.
3. Memastikan aplikasi lama tetap diupdate: Jika situs lama mengalihkan ke situs baru, gunakan properti install_url di blok migrate_from untuk memastikan browser tetap dapat menemukan manifes lama untuk kemungkinan update.
4. Terapkan id dalam manifes tujuan: Chrome mewajibkan manifes aplikasi tujuan untuk menyertakan kolom id. Hal ini memastikan aplikasi tidak melakukan kesalahan umum membuat aplikasi terpisah dengan mengubah start_url tanpa menetapkan id.

Proses verifikasi dua arah: Cara kerjanya

Untuk memastikan keamanan dan mencegah pengambilalihan yang tidak sah, migrasi memerlukan handshake yang aman antara origin lama dan baru. Handshake ini memastikan bahwa kedua situs dikontrol oleh entitas yang sama.

Langkah 1: Aplikasi baru mendeklarasikan pendahulunya (wajib)

Tambahkan kolom migrate_from ke manifes aplikasi web dari aplikasi baru.

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

Langkah 2: Origin lama mengonfirmasi migrasi (wajib)

Untuk mencegah situs baru membajak aplikasi lama secara sepihak, origin lama harus memberikan otorisasi migrasi secara eksplisit. Hal ini dilakukan dengan file konfigurasi .well-known.

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

Langkah 3: Pemberian sinyal proaktif (opsional)

Untuk memicu update tanpa menunggu pengguna mengunjungi situs baru, update manifes aplikasi lama agar mengarah ke aplikasi baru.

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

Langkah 4: Menangani pengalihan (opsional)

Sebagai alternatif untuk menggunakan kolom migrate_to, Anda dapat menandai migrasi dengan mengalihkan URL aplikasi lama ke aplikasi baru, dan mengandalkan scope_extensions agar banner di luar cakupan tidak ditampilkan di aplikasi lama. Artinya, manifes aplikasi lama tidak akan pernah terlihat, sehingga tidak akan pernah diperbarui. Agar aplikasi lama dapat terus diupdate sebelum migrasi aplikasi terjadi, tetapkan install_url di dalam migrate_from untuk memberi tahu browser tentang URL yang akan diambil yang masih memiliki manifes lama tanpa pengalihan.

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

Selesai! UX ini mirip dengan yang digunakan untuk update aplikasi, dengan pengguna diberi tahu di sudut kanan atas jendela aplikasi:

Mengklik Tinjau update aplikasi akan menampilkan UX berikut (bergantung pada apa yang telah berubah dalam manifes):

Mengontrol pengalaman pengguna

Anda dapat memilih seberapa agresif migrasi menggunakan tanda behavior:

1. Sarankan (default): Pengguna menerima notifikasi pasif (misalnya, di menu aplikasi). Mereka dapat memilih untuk mengupdate, meng-uninstal aplikasi, atau mengabaikan migrasi dengan meluncurkan dialog.
2. Wajib: Saat peluncuran aplikasi berikutnya, pengguna akan melihat dialog pemblokiran. Pengguna harus mengupdate ke origin baru atau meng-uninstal aplikasi (lihat screenshot berikut).

Contoh berikut menunjukkan cara menyetel pilihan ini,

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

Kesimpulan

Fitur Migrasi PWA memungkinkan developer terus membangun arsitektur web modern yang fleksibel tanpa mengabaikan pengguna.