Debugging

Gunakan checklist ini jika notifikasi tidak terdaftar, tidak sampai, tidak muncul, atau tidak memperbarui statistik Capgo.

Mulai dengan Device Record

Sebelum men-debug code native, pastikan Capgo bisa melihat perangkat itu.

1. Buka aplikasi dan login sebagai pengguna yang ingin Anda uji.
2. Panggil CapgoNotifications.register(...) setelah login.
3. Di Capgo, buka Notifikasi > Pencarian penerima.
4. Cari dengan external customer ID yang sama.

Anda harus melihat setidaknya satu perangkat aktif dengan:

• recipientKey
• deviceKey
• platform android atau ios
• permission state
• versi aplikasi
• versi plugin
• tag dan atribut

Jika lookup tidak mengembalikan perangkat, jalur pengiriman tidak bisa menargetkan user tersebut.

Tambah Listener Debug Sementara

Tambahkan listener sementara saat testing. Hapus log yang tidak perlu sebelum rilis.

await CapgoNotifications.addListener('registrationChanged', (token) => {
  console.log('[CapgoNotifications] registrationChanged', token.value.slice(0, 12))
})

await CapgoNotifications.addListener('notificationReceived', (notification) => {
  console.log('[CapgoNotifications] notificationReceived', notification.id, notification.data)
})

await CapgoNotifications.addListener('notificationOpened', (event) => {
  console.log('[CapgoNotifications] notificationOpened', event.notification.id, event.actionId)
})

await CapgoNotifications.addListener('backgroundNotification', async (event) => {
  console.log('[CapgoNotifications] backgroundNotification', event.notification.id, event.notification.data)
  await event.finish()
})

Kumpulkan Informasi Ini

Saat debugging bersama tim atau support Capgo, kumpulkan:

• App ID Capgo.
• App package ID atau iOS bundle ID.
• Platform perangkat dan versi OS.
• Versi app dan build number.
• Versi plugin.
• ID customer eksternal.
• recipientKey dan deviceKey dari registrasi atau pencarian recipient.
• Campaign ID atau notification ID.
• Status app saat itu (foreground, background, force-closed, atau baru diinstal).
• Device logs dari sesi saat issue muncul.

Gunakan Device Logs

Biarkan satu perangkat fisik tetap terhubung saat Anda mengirim notifikasi uji coba.

Di Android:

• Buka Android Studio Logcat.
• Filter berdasarkan package ID aplikasi.
• Pantau log permintaan izin notifikasi, refresh native token, penerimaan pesan, dan JavaScript listener.
• Jika notifikasi tidak muncul, periksa terlebih dahulu tingkat kepentingan notification channel dan status izin Android 13+.

Di iOS:

• Jalankan aplikasi dari Xcode di perangkat fisik.
• Buka konsol Xcode atau Perangkat dan Simulator logs.
• Filter berdasarkan bundle ID dan CapgoNotifications.
• Konfirmasi AppDelegate.swift notifikasi remote diteruskan dan capability background mode sudah aktif.

Kirim satu tes foreground terlebih dahulu, lalu satu tes background, kemudian satu tes silent update-check. Urutan ini memisahkan masalah JavaScript listener dari limit pengiriman background OS.

Masalah Registrasi

CLI Setup Belum Selesai

Jalankan perintah setup dari folder yang berisi capacitor.config.*:

npx @capgo/cli@latest notifications setup com.example.app

Jika perintah tidak dapat menyimpulkan app ID Anda, berikan secara eksplisit seperti di atas. Jika instalasi package gagal, pastikan nama package @capgo/capacitor-notificationssesuai, verifikasi registry npm Anda https://registry.npmjs.orgsudah benar, cek akses jaringan, lalu jalankan ulang perintahnya.

Perangkat Tidak Muncul di Pencarian Penerima

Cek:

• register dipanggil setelah aplikasi Anda memiliki user yang terautentikasi.
• externalId cocok dengan user ID yang Anda cari di dashboard.
• identityProof dibuat oleh backend Anda untuk ID yang sama appId dan externalId.
• appId di configure yang cocok dengan app Capgo.
• consent tidak diatur ke false kecuali jika pengguna memilih untuk opt-out.
• Perangkat memiliki akses jaringan ke https://api.capgo.app.
• Native push token telah dibuat. Gunakan registrationChanged untuk mengonfirmasi refresh token.

Identity Proof Tidak Valid

Proof terikat ke Capgo app ID dan external ID. Jika salah satu nilai berubah, buat proof baru.

Jangan simpan satu proof selamanya atau gunakan kembali proof di berbagai aplikasi. Buatlah dari backend Anda setelah login, kembalikan ke aplikasi, lalu panggil register.

Perangkat Terdaftar Tapi Izin Ditolak

Plugin dapat mencatat status perangkat meskipun pengguna menolak izin. Anda tetap bisa melihat perangkatnya, tetapi notifikasi yang terlihat tidak akan muncul.

Gunakan layar primer izin sebelum prompt OS muncul. Jelaskan manfaat yang didapat pengguna, lalu minta izin hanya saat tindakan tersebut relevan.

Masalah Pengiriman

Antrean Tapi Belum Terkirim

Cek:

• Status kredensial platform adalah configured di Capgo.
• Lingkungan worker berisi referensi secret yang sama dengan yang ditampilkan di dashboard.
• Package ID atau bundle ID di aplikasi sesuai dengan setup push platform.
• Target audiens terhubung ke setidaknya satu perangkat aktif.
• Kampanye tidak dibatasi oleh tag atau segmen yang tidak dimiliki perangkat.

Terkirim Tapi Tidak Diterima

Cek:

• Perangkat dalam kondisi online.
• Aplikasi tidak dihentikan paksa oleh user.
• Izin notifikasi OS sudah diberikan.
• Pembatasan baterai Android tidak memblokir aplikasi saat pengujian.
• Low Power Mode iOS dan pembatasan background refresh tidak memengaruhi pengiriman background.
• Notifikasi tidak digantikan oleh notifikasi lain dengan collapse ID yang sama.

Platform push native dapat menerima notifikasi namun tetap menunda, membatasi, menggabungkan, atau membatalkan pengiriman nantinya. Anggap statistik provider yang diterima sebagai “diterima untuk pengiriman”, bukan bukti bahwa perangkat telah menampilkannya.

Diterima Tapi Tidak Ditampilkan

Cek:

• Aplikasi tidak berada di foreground. Notifikasi foreground biasanya dikirim ke JavaScript supaya aplikasi bisa menentukan UI apa yang ditampilkan.
• Importance channel notifikasi Android sudah cukup tinggi untuk menampilkan alert.
• Izin notifikasi Android 13+ sudah diberikan.
• Fitur Focus, notification summary, atau pengaturan notifikasi per-app di iOS tidak menyembunyikan notifikasi.
• Logika penghapusan badge atau app-open tidak menghapus notifikasi yang sudah diterima selama pengujian.

Masalah Notifikasi Background

Background Callback Tidak Berjalan

Notifikasi background bersifat best-effort. OS bisa saja melewatkannya.

Cek:

• iOS telah Background Modes > Remote notifications diaktifkan.
• iOS AppDelegate.swift meneruskan remote notification ke CapgoNotificationsRemoteNotification.
• Anda menguji perilaku background iOS pada perangkat fisik.
• Aplikasi tidak dihentikan paksa oleh pengguna.
• Background handler memanggil finish().
• Proses di dalam callback harus singkat, aman untuk jaringan, dan bersifat idempotent.

Pada iOS, background push mungkin dibatasi jika Anda mengirim terlalu banyak, menggunakan terlalu banyak waktu, atau pengguna jarang membuka aplikasi. Ini adalah perilaku platform yang wajar.

Background Dimulai Tapi Tidak Selesai

Jika statistik menunjukkan background_started tanpa background_finished, kemungkinan handler JavaScript mengalami error, timeout, atau tidak memanggil finish().

Bungkus handler di dalam try/finally:

await CapgoNotifications.addListener('backgroundNotification', async (event) => {
  try {
    await doShortBackgroundWork(event.notification.data)
  } finally {
    await event.finish()
  }
})

Masalah Silent Update Check

Notifikasi Update Check Muncul Tapi Update Tidak Terinstal

Cek:

• @capgo/capacitor-updater sudah terinstal dan dikonfigurasi.
• autoUpdater adalah true atau enableUpdaterIntegration telah dipanggil.
• Pengaturan Notifikasi aplikasi memungkinkan pengecekan update push.
• Perangkat target sesuai dengan channel yang diharapkan.
• Aplikasi memiliki bundle yang lebih baru di Capgo.
• Mode instalasi update Anda sudah benar: next antre untuk restart berikutnya atau siklus background, set langsung diinstal saat updater bisa melakukannya dengan aman.

Jalankan pengecekan manual saat aplikasi sedang terbuka:

const result = await CapgoNotifications.runUpdateCheck({
  enabled: true,
  installMode: 'next',
})

console.log(result)

Jika pengecekan manual menghasilkan unavailable, periksa dulu konfigurasi plugin updater Anda.

Masalah Badge

Cek:

• Target ter-resolve ke perangkat yang tepat dalam pencarian penerima.
• Platform mendukung app badge untuk launcher atau home screen yang sedang diuji.
• Pengguna belum menonaktifkan badge di pengaturan notifikasi OS.
• Aplikasi tidak langsung menghapus badge saat startup.
• Anda tidak membuat panggilan lokal berlomba dengan setBadge pengiriman badge dari backend.

Masalah Stats

Stats Terlihat Duplikat

Pengiriman notifikasi bersifat at-least-once. Retry queue dan retry platform bisa membuat pengiriman ganda. Gunakan notification ID dan collapse ID saat aksi aplikasi Anda harus idempotent.

Stats Hilang pada Perangkat Lama

Registry Analytics Engine ditujukan untuk perangkat aktif, bukan database permanen. Plugin harus me-refresh registrasi saat app start, token refresh, perubahan external ID, dan secara berkala sebelum jendela retensi perangkat aktif berakhir.

Open Events Hilang

Cek:

• Notifikasi menyertakan sebuah nilai stabil id.
• notificationOpened listener didaftarkan saat aplikasi startup.
• Aplikasi tidak mengganti native open flow dengan custom code sebelum plugin melihatnya.
• Pengguna benar-benar mengetuk notifikasi, bukan membuka aplikasi secara manual.

API Command Debug

Cari penerima:

curl -X POST 'https://api.capgo.app/notifications/recipients/lookup' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: CAPGO_API_KEY' \
  -d '{
    "appId": "com.example.app",
    "externalId": "customer-user-123"
  }'

Baca statistik:

curl 'https://api.capgo.app/notifications/stats?app_id=com.example.app&days=7' \
  -H 'x-api-key: CAPGO_API_KEY'

Kirim tes foreground:

curl -X POST 'https://api.capgo.app/notifications/send' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: CAPGO_API_KEY' \
  -d '{
    "appId": "com.example.app",
    "target": { "externalId": "customer-user-123" },
    "payload": {
      "title": "Capgo test",
      "body": "Open this notification to test events.",
      "data": { "debug": "true" }
    }
  }'

Akar Masalah yang Umum

Gejala	Kemungkinan penyebab
Perangkat tidak ditemukan saat lookup	register tidak dipanggil, mismatch proof, consent false, app ID mismatch.
Izin ditolak	Prompt OS ditolak atau belum diminta.
Antrean ada tapi tidak ada statistik terkirim	Kredensial platform hilang atau dinonaktifkan.
Terkirim tapi tidak ada statistik diterima	Perangkat offline, OS throttling, app force-stopped, atau token tidak valid.
Log notifikasi foreground ada tapi banner tidak muncul	Aplikasi sedang di foreground dan harus menampilkan UI in-app sendiri.
Background tidak pernah berjalan di iOS	Capabilities kurang, AppDelegate forwarding tidak ada, aplikasi di-force-quit, atau throttling OS.
Pengecekan update tidak membuahkan hasil	Integrasi updater nonaktif, tidak ada bundle baru, channel salah, atau salah paham mode instalasi.
Badge ter-reset	Startup aplikasi code menghapus badge atau terjadi race condition saat penulisan badge lokal dan backend.

Lanjutkan dari Debugging

Setelah perangkat terdaftar dan notifikasi tes berhasil, gunakan Panduan Memulai untuk menghubungkan badge, targeting campaign, dan silent update check ke aplikasi produksi Anda.