Perilaku Update

Saat merilis update ke aplikasi Capgo Anda, Anda pasti ingin pengguna segera menerimanya. Namun, Anda juga tidak ingin mengganggu pengalaman mereka dengan memaksa mereka menunggu download atau restart aplikasi di tengah sesi.

Perilaku update Capgo dirancang untuk menyeimbangkan antara pengiriman update yang cepat dan meminimalkan gangguan bagi pengguna Anda.

Alur Update Default

Secara default, begini cara Capgo menangani update aplikasi:

1. Saat aplikasi masuk ke foreground, plugin Capgo akan mengecek apakah ada update baru. Selama aplikasi tetap terbuka, ia juga akan mengecek kembali melalui timer berulang yang dikontrol oleh periodCheckDelay (default 10 menit).

2. Jika pembaruan ditemukan, proses download akan berjalan di latar belakang sementara pengguna tetap menggunakan versi aplikasi saat ini.

3. Setelah download selesai, Capgo akan menunggu hingga pengguna memindahkan aplikasi ke background.

4. Saat pengguna membuka kembali aplikasi ke foreground, mereka akan menjalankan versi yang sudah di-update.

Flow ini memastikan pengguna selalu menjalankan versi terbaru aplikasi Anda, tanpa terganggu oleh prompt update atau dipaksa menunggu proses download.

Tips

Capgo mengecek update setiap kali aplikasi masuk ke foreground dan melalui timer berulang saat aplikasi tetap terbuka. periodCheckDelay mengatur interval tersebut (default 10 menit).

Mengapa Pendekatan Ini?

Menerapkan update saat background atau event kill memberikan beberapa manfaat utama bagi user experience:

• User tidak terganggu oleh prompt update atau dipaksa menunggu download di tengah sesi.

• Update diterapkan secara seamless di antara sesi, sehingga pengalaman saat membuka aplikasi selalu terasa baru.

• Anda dapat mengirimkan update secara berkala tanpa khawatir mengganggu user yang sedang aktif.

Kekurangan utamanya adalah jika user memindahkan aplikasi ke background lalu segera membukanya kembali, mereka mungkin kehilangan state yang belum tersimpan karena update diterapkan di antara aksi tersebut.

Untuk memitigasi hal ini, kami menyarankan:

• Simpan state secara berkala dan kembalikan (restore) secara graceful saat aplikasi resume.

• Hindari update yang terlalu sering yang mengubah bagian besar dari app state.

• Pertimbangkan menyesuaikan perilaku update untuk alur sensitif (lihat di bawah).

Mengatur Kapan Update Diterapkan

Dalam beberapa kasus, Anda mungkin butuh kontrol lebih atas kapan tepatnya sebuah update diterapkan. Misalnya, Anda ingin memastikan user menyelesaikan alur yang sedang berjalan sebelum update, atau menyelaraskan update aplikasi dengan perubahan di sisi server.

Capgo menyediakan setDelay fungsi yang memungkinkan Anda menentukan kondisi yang harus terpenuhi sebelum update diinstal:

import { CapacitorUpdater } from '@capgo/capacitor-updater';

await CapacitorUpdater.setMultiDelay({
  delayConditions: [
    {
      kind: 'date',
      value: '2023-06-01T00:00:00.000Z',
    },
    {
      kind: 'background',
      value: '60000',
    },
  ],
});

Contoh ini akan menunda instalasi update hingga setelah 1 Juni 2023 DAN aplikasi sudah berada di background selama minimal 60 detik.

Kondisi delay yang tersedia:

• date: Tunggu hingga melewati tanggal/waktu tertentu untuk menerapkan update.
• background: Tunggu durasi minimum setelah aplikasi masuk ke background untuk menerapkan update.
• nativeVersion: Tunggu instalasi binary native dengan versi minimum sebelum menerapkan update.
• kill: Tunggu sampai event app kill berikutnya untuk menerapkan update.

Anda bisa mencampur berbagai kondisi ini untuk mengontrol kapan update diinstal secara presisi.

Bahaya

Perlu dicatat bahwa kill kondisi saat ini memicu update setelah kill event pertama, bukan event background berikutnya seperti kondisi lainnya. Inkonsistensi ini akan diperbaiki pada rilis mendatang.

Menerapkan Update Secara Instan

Untuk update kritikal atau aplikasi dengan state yang sangat simpel, Anda mungkin ingin menerapkan update segera setelah diunduh, tanpa menunggu event background atau kill. Capgo mendukung ini melalui autoUpdate policy di dalam konfigurasi Capacitor Anda.

Wajib untuk instant apply: --delta, autoSplashscreen, dan SplashScreen

"atInstall", "onLaunch", dan "always" menerapkan update saat pengguna sedang menunggu. Gunakan Update Delta agar hanya file yang berubah yang diunduh. Upload zip penuh akan memperlambat pengalaman pengguna.

Mode ini juga memerlukan @capacitor/splash-screen dan autoSplashscreen: true dengan SplashScreen.launchAutoHide: false. Tanpa plugin splash, pengguna mungkin melihat flicker atau UI yang tidak diperbarui saat proses update sedang berjalan.

Saat autoUpdate disetel ke "atInstall", "onLaunch", atau "always" di file capacitor.config, CLI akan mendeteksinya. Di lingkungan non-interaktif, ia mengirim Delta update secara otomatis, sedangkan di lingkungan interaktif, ia akan meminta konfirmasi sebelum upload. Konfigurasi directUpdate lama masih terdeteksi. Gunakan --no-delta untuk memaksa full bundle upload.

npx @capgo/cli@latest bundle upload --delta

autoUpdate diatur di file capacitor.config.ts Anda, bukan di JavaScript code. Ini mendukung nilai berikut:

• false atau 'off': Nonaktifkan pengecekan update otomatis
• true atau 'atBackground' (default): Cek dan download otomatis setiap kali aplikasi masuk foreground, lalu terapkan update saat aplikasi pindah ke background
• 'atInstall': Terapkan segera hanya setelah fresh install atau update native app store; jika tidak, gunakan "atBackground" perilaku
• 'onLaunch': Hanya diterapkan segera saat aplikasi dibuka dari kondisi mati (cold start). Setelah pengecekan pertama, beralih ke "atBackground" perilaku
• 'always': Cek setiap kali aplikasi masuk ke foreground dan terapkan segera jika ada update tersedia
• 'onlyDownload': Cek dan download otomatis, kirim updateAvailable, dan jangan pernah mengatur bundle berikutnya atau menerapkan update secara otomatis

Tes Native Build Tanpa Live Updates

Lihat Uji Native Build Tanpa Live Updates untuk pengamanan konfigurasi native-version, channel-policy, dan CI.

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'always', // or 'atInstall' for updates only on app install/update
      autoSplashscreen: true,
      keepUrlPathAfterReload: true,
    },
    SplashScreen: {
      launchAutoHide: false, // Required for instant apply with autoSplashscreen
    },
  },
};

export default config;

Catatan

Penting: mode instant apply hanya menerapkan update saat plugin benar-benar memeriksanya. Secara default, pengecekan berjalan saat aplikasi masuk foreground dan dengan timer berulang selama aplikasi tetap terbuka. periodCheckDelay mengatur interval tersebut (default 10 menit).

Dengan autoUpdate: 'always', Capgo memeriksa pada setiap transisi foreground dan langsung menerapkan update begitu download selesai dalam pengecekan tersebut, bahkan jika pengguna sedang aktif menggunakan aplikasi. Pengecekan berkala yang dikontrol oleh periodCheckDelay dapat memicu perilaku immediate apply yang sama selama aplikasi tetap terbuka.

Perlu dicatat bahwa karena autoUpdate adalah konfigurasi native, mode instant apply memerlukan penanganan tambahan di JavaScript code Anda.

Peringatan

Mode apply instan memerlukan @capacitor/splash-screen dan autoSplashscreen: true. Atur launchAutoHide: false pada konfigurasi SplashScreen (seperti di atas) agar splash screen tetap muncul sampai update selesai.

Download Otomatis Tanpa Menerapkan

Jika ingin Capgo mengecek dan download update otomatis tapi tidak pernah meng-apply-nya otomatis, gunakan autoUpdate: 'onlyDownload':

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'onlyDownload',
    },
  },
};

Dalam mode ini, plugin akan memancarkan updateAvailable setelah bundle selesai di-download. Aplikasi Anda kemudian bisa memutuskan kapan memanggil CapacitorUpdater.set() atau menampilkan update prompt sendiri.

Penanganan Splashscreen Otomatis

Mode penerapan instan ("atInstall", "onLaunch", "always") memerlukan autoSplashscreen dan @capacitor/splash-screen (tersedia sejak versi 7.6.0). Instal plugin, lalu biarkan splash tetap terlihat sampai Capgo menyembunyikannya:

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'always', // or 'atInstall'
      autoSplashscreen: true, // Automatically hide splashscreen
      keepUrlPathAfterReload: true,
    },
    SplashScreen: {
      launchAutoHide: false,
    },
  },
};

Saat autoSplashscreen diaktifkan:

• Plugin secara otomatis menyembunyikan splashscreen saat update diterapkan
• Plugin otomatis menyembunyikan splashscreen saat tidak ada update yang diperlukan
• Anda tidak perlu secara manual mendengarkan appReady event atau memanggil SplashScreen.hide()

Kerja ekstra setelah splash hilang

Pertahankan autoSplashscreen: true. Jika Anda butuh logika tambahan setelah update siap, dengarkan appReady juga. Jangan lewatkan splash plugin atau autoSplashscreen untuk ini:

import { CapacitorUpdater } from '@capgo/capacitor-updater';

CapacitorUpdater.addListener('appReady', () => {
  // Update is applied. autoSplashscreen already hid the splash.
});

CapacitorUpdater.notifyAppReady();

Panduan appReady event dipicu setelah app selesai inisialisasi dan menerapkan semua update yang tertunda.

Atur keepUrlPathAfterReload ke true saat menggunakan mode instant apply. Ini menjaga path URL saat ini ketika app dimuat ulang karena adanya update.

Mode instant apply berguna untuk mengirimkan perbaikan bug kritis atau patch keamanan, namun ada beberapa konsekuensinya:

• User mungkin melihat flicker singkat atau loading saat update diterapkan jika @capacitor/splash-screen hilang atau autoSplashscreen tidak diaktifkan.
• Jika update mengubah state app atau UI, user mungkin melihat perubahan yang mengganggu di tengah sesi.
• Posisi user di dalam app bisa hilang jika keepUrlPathAfterReload tidak diatur, yang berpotensi membuat mereka bingung.
• Anda perlu menangani proses simpan dan restore state dengan teliti untuk memastikan transisi yang mulus.

Jika Anda mengaktifkan instant apply, kami menyarankan:

• Upload menggunakan npx @capgo/cli@latest bundle upload --delta agar proses download tidak memperlambat user experience.
• Instal @capacitor/splash-screen dan mengatur autoSplashscreen: true dengan launchAutoHide: false.
• Pengaturan keepUrlPathAfterReload ke true untuk mempertahankan posisi pengguna di dalam aplikasi.
• Menyimpan dan memulihkan state aplikasi sesuai kebutuhan agar progres pengguna tidak hilang.
• Uji coba secara menyeluruh perilaku update aplikasi Anda untuk memastikan tidak ada transisi yang mengganggu, kehilangan state, atau perubahan lokasi yang membingungkan.

Dalam kebanyakan kasus, perilaku update default memberikan keseimbangan terbaik antara pengiriman update yang cepat dan minimalisasi gangguan. Namun untuk aplikasi dengan kebutuhan khusus, Capgo memberikan fleksibilitas untuk menyesuaikan kapan dan bagaimana update diterapkan.

Lanjutkan dari Update Behavior

Jika Anda menggunakan Perilaku Update untuk merencanakan pengiriman live update, hubungkan dengan Capgo Live Updates untuk alur kerja produk di Capgo Live Updates, Ikhtisar untuk detail implementasi di Overview, Fitur untuk detail implementasi di Features, Tipe Update untuk detail implementasi di Update Types, dan Panduan Memulai untuk detail implementasi di Getting Started.