Debugging

Memahami cloud logs

Jika Anda mendapatkan penolakan cloud code dan butuh panduan perbaikan lebih mendalam, lihat Masalah Update Umum.

Log Capgo dapat menyertakan metadata untuk event tersebut. Di dashboard, filter berdasarkan action snake_case code, lalu klik sel metadata untuk menyalin payload JSON lengkapnya. Metadata sangat berguna untuk event crash dan WebView karena dapat menyertakan pesan error, source URL, baris dan kolom, status proses, memory pressure, atau alasan spesifik platform. Log lama mungkin masih menampilkan alias camelCase lama yang tertera dalam tanda kurung.

Setiap judul bagian sesuai dengan action code yang muncul di tabel console logs, sehingga Anda bisa langsung merujuk ke sana.

Limit paket dan respons normal

Penolakan backend terkait penagihan, throttling, atau status non-error.

InvalidIp

Apa artinya

Capgo mendeteksi trafik yang terlihat berasal dari Google atau infrastruktur cloud. Update yang berusia kurang dari empat jam akan diabaikan agar trafik bot tidak terhitung sebagai perangkat berbayar.

Cara mengatasi

Abaikan ini pada pengguna asli. Coba lagi menggunakan jaringan normal dan perangkat asli, atau tunggu dan cek kembali nanti.

provider_infrastructure_request_blocked

Apa artinya

Aplikasi Anda dikonfigurasi untuk memblokir request dari rentang IP datacenter Google dan Apple yang dikenal. Proteksi ini berlaku untuk pengecekan update, stats, dan request channel-self, sehingga probe yang di-host di cloud dan provider runner bisa menerima respon ini meskipun konfigurasi aplikasi sudah valid.

Cara mengatasi

Coba lagi menggunakan perangkat fisik pada jaringan pengguna normal. Jika trafik dari provider memang disengaja, nonaktifkan sementara Blokir request infrastruktur provider di dalam aplikasi Informasi tab, lalu aktifkan kembali setelah pengujian. Aplikasi baru mengaktifkan pengaturan ini secara default; aplikasi lama tetap menggunakan pengaturan nonaktif sebelumnya sampai diubah.

needPlanUpgrade

Apa artinya

Organisasi Anda telah mencapai batas paket atau perangkat. Perangkat tidak akan menerima update sampai Anda upgrade atau siklus penagihan berikutnya mereset penggunaan.

Cara mengatasi

Upgrade paket Anda di dashboard atau tunggu siklus penagihan berikutnya.

noNew

Apa artinya

Perangkat sudah memiliki bundle terbaru untuk channel-nya. Ini adalah kondisi normal, bukan error.

rateLimited

Apa artinya

Perangkat mengirim terlalu banyak request update atau channel dalam waktu singkat.

Cara mengatasi

Jangan memanggil update API di dalam render loop. Panggil setChannel / getChannel hanya dari user action, dan set defaultChannel di capacitor.config.

Format versi

Penolakan backend akibat metadata versi native yang tidak valid.

semver_error

Apa artinya

Versi aplikasi native di config tidak ada atau bukan semver yang valid (x.y.z).

Cara mengatasi

Atur plugins.CapacitorUpdater.version agar semver valid, verifikasi di Penguji SemVer, lalu rebuild dan reinstall aplikasi native.

Target platform dan build

Penolakan backend saat kebijakan channel memblokir platform, tipe build, atau kelas perangkat.

disablePlatformIos

Apa artinya

Perangkat menjalankan iOS, tetapi update iOS dinonaktifkan untuk channel ini.

Cara mengatasi

Aktifkan iOS di channel jika ini tidak disengaja, atau arahkan build iOS ke channel khusus jika pemblokiran memang disengaja.

disablePlatformAndroid

Apa artinya

Perangkat menjalankan Android, tetapi update Android dinonaktifkan untuk channel ini.

Cara mengatasi

Aktifkan Android di channel ini jika terjadi kesalahan, atau arahkan build Android ke channel khusus jika pemblokiran memang disengaja.

disablePlatformElectron

Apa artinya

Perangkat menjalankan Electron, tetapi update Electron dinonaktifkan untuk channel ini.

Cara mengatasi

Aktifkan Electron di channel ini jika terjadi kesalahan, atau arahkan build Electron ke channel khusus jika pemblokiran memang disengaja.

disableDevBuild

Apa artinya

Perangkat adalah dev build, tetapi dev build diblokir untuk channel ini.

Cara mengatasi

Izinkan dev build di channel test, atau jadikan channel ini khusus release dan pindahkan perangkat dev ke tempat lain.

disableProdBuild

Apa artinya

Build produksi bernama /updates, tetapi update produksi diblokir untuk channel ini.

Cara mengatasi

Izinkan update produksi di channel ini jika terjadi kesalahan, atau arahkan build produksi ke channel yang benar.

disableDevice

Apa artinya

Perangkat ponsel atau tablet asli diblokir karena channel ini memblokir perangkat asli.

Cara mengatasi

Aktifkan update perangkat fisik jika terjadi kesalahan, atau pertahankan pembatasan dan arahkan perangkat fisik ke channel lain.

disableEmulator

Apa artinya

Perangkat adalah emulator, tetapi update emulator dinonaktifkan untuk channel ini.

Cara mengatasi

Aktifkan emulator update di test channel, atau biarkan channel ini emulator-blocked dan gunakan channel lain untuk validasi emulator.

Aturan kompatibilitas auto-update

Penolakan backend saat aturan semver atau metadata memblokir target bundle.

disableAutoUpdate

Apa artinya

Auto-update dinonaktifkan oleh kebijakan kompatibilitas channel. Metadata mencakup auto_update dengan aturan yang cocok seperti major, minor, patch, metadata, atau none.

Cara mengatasi

Ubah kebijakan auto-update channel untuk mengizinkan rollout yang Anda inginkan.

disableAutoUpdateUnderNative

Apa artinya

Channel memiliki bundle yang lebih lama dari baseline device dan memblokir pengiriman update di bawah versi native.

Cara mengatasi

Publish bundle pada atau di atas baseline native, atau nonaktifkan proteksi under-native di channel tersebut.

disableAutoUpdateMetadata

Apa artinya

Channel membutuhkan min_update_version, tetapi versi native device berada di bawah ambang batas tersebut.

Cara mengatasi

Atur min_update_version pada bundle atau rilis target dari versi native yang lebih baru.

disableAutoUpdateToMajor

Apa artinya

Channel ini memblokir lompatan versi major, contohnya 1.x.x ke 2.x.x.

Cara mengatasi

Sesuaikan strategi channel dengan rencana rollout major Anda, atau izinkan lompatan major untuk track ini. Lihat Masalah Update Umum.

disableAutoUpdateToMinor

Apa artinya

Channel ini memblokir lompatan versi minor terhadap baseline native perangkat (version_build), contohnya 1.2.3 ke 1.3.0.

Cara mengatasi

Sesuaikan strategi channel dengan rencana minor rollout Anda, atau izinkan minor jumps untuk track ini.

disableAutoUpdateToPatch

Apa artinya

Channel ini memblokir perubahan level patch namun tetap mempertahankan MAJOR.MINOR.PATCH prefix yang sama; hanya perubahan suffix yang diizinkan.

Cara mengatasi

Sesuaikan cadence rilis dengan kebijakan channel, atau izinkan patch jumps untuk track ini.

Konfigurasi channel

Penolakan backend disebabkan oleh konfigurasi channel yang hilang atau tidak kompatibel.

cannotUpdateViaPrivateChannel

Apa artinya

Perangkat mencoba melakukan self-associate dengan private channel yang tidak mengizinkan device self-assignment (allow_device_self_set adalah false) dan channel tersebut tidak bersifat publik.

Cara mengatasi

Aktifkan allow_device_self_set pada channel tersebut atau pindahkan perangkat ke public channel atau channel yang diizinkan.

channelMisconfigured

Apa artinya

Channel menggunakan disable_auto_update: "version_number" tetapi bundle min_update_version adalah null, sehingga Capgo tidak bisa menentukan perangkat mana yang harus update.

Cara mengatasi

Lengkapi konfigurasi yang kurang untuk aturan tersebut atau beralih ke mode auto-update yang lebih simpel.

NoChannelOrOverride

Apa artinya

Tidak ada channel default yang dikonfigurasi dan perangkat tidak memiliki channel override.

Cara mengatasi

Atur channel default di dashboard atau konfigurasi defaultChannel pada build.

Pengiriman dan enkripsi bundle

Penolakan backend saat Capgo tidak dapat menyajikan atau mendekripsi bundle.

cannotGetBundle

Apa artinya

Capgo gagal membuat URL download bertanda tangan yang valid dan tidak ada fallback manifest yang tersedia.

Cara mengatasi

Upload ulang bundle, buat ulang manifest, dan periksa pengaturan R2 atau bundle publik.

missingBundle

Apa artinya

Bundle yang ditetapkan ke channel tidak memiliki konten yang dapat diunduh: tidak ada external_url, tidak ada r2_path, bukan versi bawaan, dan tidak ada entri manifest.

Cara mengatasi

Build ulang dan upload ulang versinya, lalu pastikan bundle benar-benar berisi konten file.

keyMismatch

Apa artinya

Public key enkripsi perangkat tidak cocok dengan kunci yang digunakan untuk mengenkripsi bundle. Metadata dapat berisi device_key_id, bundle_key_id, dan version.

Cara mengatasi

Bandingkan ID kunci perangkat dan bundle di konsol. Publish dengan kunci yang sama dan versi CLI/plugin yang cocok.

Konfigurasi aplikasi dan klien lama

Penolakan backend yang disebabkan oleh konfigurasi aplikasi atau versi updater yang tidak didukung.

customIdBlocked

Apa artinya

Aplikasi mengirimkan custom device ID, tetapi aplikasi ini tidak menerima custom ID, sehingga ID tersebut diabaikan.

Cara mengatasi

Berhenti mengirim custom ID, atau aktifkan custom ID hanya saat workflow Anda membutuhkannya.

blocked_by_server_url

Apa artinya

server.url diatur di konfigurasi Capacitor, sehingga WebView memuat URL remote alih-alih file bundle lokal. Capgo live updates memerlukan file lokal dan server.url tidak disarankan untuk produksi.

Cara mengatasi

Hapus atau bersihkan server.url untuk build produksi dan simpan payload update secara lokal. code ini bisa muncul sebagai penolakan backend atau sebagai status di sisi perangkat.

backend_refusal

Apa artinya

Plugin updater adalah v4, yang sudah tidak diterima lagi oleh backend.

Cara mengatasi

Upgrade plugin dan CLI ke v5+ (disarankan v8) dengan Capacitor v5+, rebuild, lalu publish ulang metadata bundle.

Lifecycle update

Event di sisi device untuk alur update normal, aktivasi, dan rollback.

ping

Apa artinya

Action test internal untuk memverifikasi stats pipeline.

get

Apa artinya

Capgo mengirimkan informasi download versi baru ke device.

set

Apa artinya

Bundle diaktifkan di perangkat.

set_fail

Apa artinya

Bundle gagal diaktifkan di perangkat.

Cara mengatasi

Cek native logs dengan npx @capgo/cli@latest app debug dan verifikasi integritas bundle, path, serta notifyAppReady alur.

reset

Apa artinya

Perangkat di-reset ke bundle bawaan.

delete

Apa artinya

Satu bundle telah dihapus di perangkat.

Kegagalan download dan instalasi

Event di sisi perangkat untuk progres download, validasi arsip, dan error instalasi.

download_0

Apa artinya

Urutan download dimulai dengan progres 0%.

download_10

Apa artinya

Bundle baru telah didownload — progres menunjukkan 10%.

download_20

Apa artinya

Bundle baru telah diunduh — progres menunjukkan 20%.

download_30

Apa artinya

Bundle baru telah diunduh — progres menunjukkan 30%.

download_40

Apa artinya

Bundle baru telah diunduh — progres menunjukkan 40%.

download_50

Apa artinya

Bundle baru telah diunduh — progres menunjukkan 50%.

download_60

Apa artinya

Bundle baru telah diunduh — progres menunjukkan 60%.

download_70

Apa artinya

Bundle baru telah diunduh — progres menunjukkan 70%.

download_80

Apa artinya

Bundle baru telah diunduh — progres menunjukkan 80%.

download_90

Apa artinya

Bundle baru telah diunduh — progres menunjukkan 90%.

download_complete

Apa artinya

Download bundle berhasil diselesaikan.

download_manifest_start

Apa artinya

Perangkat mulai mengunduh manifest update.

download_manifest_complete

Apa artinya

Perangkat selesai mengunduh manifest update.

download_zip_start

Apa artinya

Perangkat mulai mengunduh arsip bundle.

download_zip_complete

Apa artinya

Perangkat selesai mengunduh arsip bundle.

download_manifest_file_fail

Apa artinya

Satu entri manifest gagal diunduh. version_name menggunakan version:fileName untuk mengidentifikasi aset tersebut.

Cara mengatasi

Perbaiki aset yang hilang atau terblokir, buat ulang manifest, lalu upload kembali bundle-nya.

download_manifest_checksum_fail

Apa artinya

File manifest gagal dalam validasi checksum.

Cara mengatasi

Upload ulang bundle dengan versi CLI terbaru dan verifikasi checksum manifest.

download_manifest_brotli_fail

Apa artinya

File manifest gagal didekompresi dengan Brotli.

Cara mengatasi

Verifikasi pengaturan kompresi dan upload ulang aset yang terdampak.

download_fail

Apa artinya

Bundle gagal di-download.

Cara mengatasi

Cek koneksi jaringan, masa berlaku signed URL, aksesibilitas CDN, dan penyimpanan perangkat.

update_fail

Apa artinya

Bundle terinstal tapi app tidak pernah memanggil notifyAppReady, jadi Capgo melakukan rollback.

Cara mengatasi

Panggil notifyAppReady() setelah app selesai bootstrapping. Teks log native notifyAppReady was not called, roll back current bundle merujuk ke code ini.

checksum_fail

Apa artinya

Bundle yang diunduh gagal validasi checksum. Penyebab umum: mismatch CRC32 vs SHA256 dari upload CLI lama, atau mismatch encryption key pada plugin lama yang memunculkan kegagalan dekripsi sebagai kegagalan checksum.

Cara mengatasi

Upload ulang dengan CLI/plugin terbaru (SHA256). Jika menggunakan enkripsi, pastikan public key aplikasi cocok dengan upload key, atau upgrade ke plugin 8.3.0+ untuk pesan keyMismatch errors.

decrypt_fail

Apa artinya

Bundle yang diunduh gagal didekripsi.

Cara mengatasi

Verifikasi encryption keys dan upload ulang bundle dengan pasangan key yang cocok.

windows_path_fail

Apa artinya

File zip berisi path bergaya Windows yang tidak valid.

Cara mengatasi

Build ulang bundle menggunakan path Unix atau bersihkan path archive sebelum upload.

canonical_path_fail

Apa artinya

Path file di dalam zip tidak bersifat canonical.

Cara mengatasi

Perbaiki pembuatan path archive sebelum upload.

directory_path_fail

Apa artinya

Zip berisi path direktori yang tidak valid.

Cara mengatasi

Perbaiki struktur archive sebelum upload.

unzip_fail

Apa artinya

Perangkat gagal mengekstrak bundle yang diunduh.

Cara mengatasi

Verifikasi integritas arsip dan kompresi yang didukung.

low_mem_fail

Apa artinya

Unduhan gagal karena perangkat kehabisan memori.

Cara mengatasi

Perkecil ukuran bundle atau coba lagi di perangkat dengan memori lebih besar.

Kesehatan App dan event WebView

Diagnostik crash, memori, dan WebView di sisi perangkat. Selalu periksa metadata JSON di dashboard.

app_moved_to_background

Apa artinya

Aplikasi masuk ke background.

app_moved_to_foreground

Apa artinya

Aplikasi masuk ke foreground.

app_crash

Apa artinya

Crash pada layer JavaScript atau Capacitor. Metadata dapat mencakup message, stack, source, dan konteks bundle yang aktif.

Cara mengatasi

Periksa metadata dan native logs. Gabungkan pelaporan error JS dan native (misalnya Sentry) untuk menemukan path code yang bermasalah.

app_crash_native

Apa artinya

Crash pada platform Native. Metadata dapat mencakup detail platform, alasan, stack, dan proses.

Cara mengatasi

Gunakan crash logs dari Xcode atau Logcat dan cocokkan dengan bundle yang aktif dari metadata.

app_anr

Apa artinya

Event Android Application Not Responding.

Cara mengatasi

Periksa trace ANR di Logcat dan kurangi beban kerja main-thread setelah update.

app_killed_low_memory

Apa artinya

OS menghentikan paksa aplikasi karena tekanan memori.

Cara mengatasi

Kurangi penggunaan memori setelah aktivasi update dan periksa metadata untuk sinyal memori yang tersedia.

app_killed_excessive_resource_usage

Apa artinya

OS menghentikan paksa aplikasi karena penggunaan sumber daya berlebih.

Cara mengatasi

Periksa metadata untuk melihat tipe resource atau alasan dari platform.

app_initialization_failure

Apa artinya

Updater atau startup gagal sebelum runtime normal siap.

Cara mengatasi

Periksa metadata untuk melihat langkah yang gagal dan pesan errornya.

app_memory_warning

Apa artinya

Peringatan memori iOS.

Cara mengatasi

Periksa konteks memori di metadata dan kurangi penggunaan puncak setelah update.

webview_javascript_error

Apa artinya

Error JavaScript tidak tertangkap di WebView. Metadata dapat mencakup pesan, URL sumber, baris, kolom, dan stack.

Cara mengatasi

Pasang error reporting di layer JS dan native untuk menangkap baris error yang tepat di produksi.

webview_unhandled_rejection

Apa artinya

Unhandled promise rejection di WebView.

Cara mengatasi

Tangkap kegagalan async dengan pelaporan error JS dan native.

webview_resource_error

Apa artinya

Resource WebView gagal dimuat.

Cara mengatasi

Gunakan URL metadata dan detail status untuk memperbaiki asset atau aturan network yang rusak.

webview_security_policy_violation

Apa artinya

Content security policy memblokir sebuah resource.

Cara mengatasi

Sesuaikan CSP menggunakan metadata directive dan detail URI yang diblokir.

webview_unclean_restart

Apa artinya

Sesi WebView sebelumnya tidak tertutup dengan bersih, yang bisa mengindikasikan adanya crash loop setelah update.

Cara mengatasi

Korelasikan dengan event crash dan error WebView sebelum dan sesudah restart.

webview_render_process_gone

Apa artinya

Proses renderer WebView Android berhenti.

Cara mengatasi

Periksa sinyal crash renderer di metadata dan native logs.

webview_content_process_terminated

Apa artinya

Proses konten WebView iOS terhenti.

Cara mengatasi

Inspeksi bundle aktif dan URL halaman dari metadata.

Konteks environment dan channel

Event konteks di sisi device untuk membantu korelasi perilaku update dengan OS, versi native, atau perubahan channel.

os_version_changed

Apa artinya

Versi OS device berubah di antara pengecekan.

native_app_version_changed

Apa artinya

Versi app store native berubah, membantu membedakan perubahan native vs web bundle.

getChannel

Apa artinya

Perangkat melakukan query channel saat ini.

setChannel

Apa artinya

Channel berhasil diatur untuk perangkat.

uninstall

Apa artinya

Aplikasi di-uninstall atau data Capgo dihapus.

Status bundle

• SUCCESS: install bundle selesai
• ERROR: install atau download gagal
• PENDING: Download selesai, menunggu rilis
• DELETED: Bundle dihapus, tetap ditampilkan untuk statistik
• DOWNLOADING: Sedang mendownload bundle

Memahami device logs

Perintah debug

Tersedia perintah debug untuk pengguna cloud Capgo.

npx @capgo/cli@latest app debug

Ini memungkinkan Anda mengecek semua event yang terjadi di app dan mencari solusi jika update tidak berjalan.

log native iOS

untuk menemukan log Anda di Xcode

Mendapatkan Device Log di Xcode

Log native Android

untuk menemukan log Anda di Android Studio

Lihat log dengan Logcat

Pemetaan frasa log native

• Failed to download from dipetakan ke download_fail
• notifyAppReady was not called, roll back current bundle dipetakan ke update_fail

Menemukan bundle yang diunduh di perangkat

iOS

Untuk debug di iOS, Anda perlu mengambil file app ke komputer, caranya sebagai berikut:

Xcode memiliki fitur bawaan untuk memeriksa file system dari app yang diinstal via developer pada perangkat iOS.

Untuk mencapainya:

• Hubungkan perangkat ke Mac Anda dan pilih Window > Devices pada menubar Xcode.
• Pilih perangkat Anda di panel kiri pada bagian Devices.
• Ini akan menampilkan daftar app yang diinstal via developer untuk perangkat tersebut.
• Pilih app yang ingin Anda periksa, lalu klik ikon 3 titik di dekat bagian bawah layar.
• Di sini Anda dapat melihat file system saat ini dengan mengunduh snapshot-nya.

Memilih Download Container… akan mengunduh dan mengekspor snapshot file system sebagai file .xcappdata yang bisa Anda telusuri.

Klik kanan pada file ini dan pilih Show Package Contents untuk membuka folder.

Buka folder App Data, dan Anda akan melihat beberapa folder seperti Documents, Library, tmp, dll.

Kemudian Anda akan menemukan versi di dalam 2 folder:

library/NoCloud/ionic_built_snapshots diperlukan setelah app reboot

dan documents/versions untuk hot reload

Android

Untuk debug di Android, Anda perlu mengakses perangkat melalui Android Studio:

• Klik View > Tool Windows > Device File Explorer atau klik tombol Device File Explorer pada bar tool window untuk membuka Device File Explorer.
• Pilih perangkat dari daftar dropdown.
• Open the path data/data/APP_NAME/ di mana APP_NAME adalah app ID Anda.

Kemudian cari versions folder untuk melihat semua versi

Tahukah Anda?

Di Android, semua versi disimpan dalam satu folder, tidak seperti iOS yang harus diduplikasi di dua lokasi.

Memahami crash log produksi iOS

Cara meninjau crash logs aplikasi Anda

Lanjutkan dari Debugging

Jika Anda menggunakan Debugging untuk merencanakan pekerjaan plugin native, hubungkan dengan Menggunakan @capgo/capacitor-updater untuk fitur native di bagian Menggunakan @capgo/capacitor-updater, Direktori Plugin Capgo untuk alur kerja produk di Direktori Plugin Capgo, Plugin Capacitor oleh Capgo untuk detail implementasi pada Capacitor Plugins oleh Capgo Menambahkan atau Memperbarui Plugin untuk detail implementasi di Menambahkan atau Memperbarui Plugin, dan Alternatif Plugin Ionic Enterprise untuk alur kerja produk dalam Alternatif Plugin Ionic Enterprise.