Debugging

Gunakan daftar periksa ini ketika notifikasi tidak terdaftar, tidak datang, tidak muncul, atau tidak memperbarui Capgo statistik.

Mulai Dengan Catatan Perangkat

Sebelum melakukan debug native code, pastikan Capgo dapat melihat perangkat.

1. Buka aplikasi dan masuk sebagai pengguna yang ingin Anda uji.
2. Call CapgoNotifications.register(...) Dalam __CAPGO_KEEP_0__, buka
3. Buka Capgo Pemberitahuan > Pencarian Penerima.
4. Anda harus melihat setidaknya satu perangkat aktif dengan:

Andai Anda melihat setidaknya satu perangkat aktif dengan:

• recipientKey
• deviceKey
• atau android or ios
• permission state
• versi aplikasi
• Versi plugin
• Tag dan atribut

If lookup returns no device, the send path cannot target that user.

Tambahkan Pemantau Sementara

Tambahkan pemantau sementara saat tes. Hapus log berisik sebelum mengirim.

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 Capgo dukungan, kumpulkan:

• ID aplikasi Capgo.
• ID paket aplikasi atau ID paket iOS.
• Platform perangkat dan versi sistem operasi.
• Versi aplikasi dan nomor pembangunan.
• Versi plugin.
• ID pelanggan eksternal.
• recipientKey dan deviceKey Dari pendaftaran atau pencarian penerima.
• dari pendaftaran atau pencarian penerima.
• Apakah aplikasi berada di latar depan, latar belakang, ditutup paksa, atau baru diinstal.
• Catatan perangkat dari jalankan yang mengulangi masalah tersebut.

Gunakan Log Perangkat

Tetapkan satu perangkat nyata terhubung saat Anda mengirimkan pemberitahuan uji coba.

Di Android:

• Pilih Logcat Android Studio.
• Tampilkan filter berdasarkan ID paket aplikasi.
• Perhatikan log permintaan izin notifikasi, pembaruan token native, penerimaan pesan, dan pengguna JavaScript.
• Jika notifikasi yang terlihat tidak muncul, periksa dahulu pentingnya saluran notifikasi dan status izin Android 13+.

Di iOS:

• Jalankan aplikasi dari Xcode pada perangkat fisik.
• Buka konsol Xcode atau Perangkat dan Simulator log.
• Tampilkan filter berdasarkan ID paket aplikasi dan CapgoNotifications.
• Konfirmasi AppDelegate.swift untuk mengirimkan pemberitahuan jarak jauh dan kemampuan mode latar belakang diaktifkan.

Kirimlah satu tes di depan, kemudian satu tes latar belakang, kemudian satu tes pemeriksaan update diam. Urutan ini memisahkan masalah pendengar JavaScript dari batasan pengiriman latar belakang sistem operasi.

Masalah Pendaftaran

Pengaturan CLI Tidak Selesai

Jalankan perintah pengaturan dari folder yang mengandung capacitor.config.*:

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

Jika perintah tidak dapat mengetahui ID aplikasi Anda, masukkan secara eksplisit seperti yang ditunjukkan di atas. Jika instalasi paket gagal, pastikan nama paket adalah @capgo/capacitor-notificationsverifikasi registri npm Anda adalah https://registry.npmjs.orgperiksa akses jaringan, kemudian jalankan perintah lagi.

Perangkat Tidak Muncul Dalam Pencarian Penerima

Cek:

• register bernama disebut setelah aplikasi Anda memiliki pengguna yang terautentik.
• externalId cocok dengan ID pengguna yang Anda cari di dashboard.
• identityProof ditambah oleh backend Anda untuk yang sama appId dan externalId.
• appId in configure cocok dengan aplikasi Capgo.
• consent cocok dengan aplikasi __CAPGO_KEEP_0__. false kecuali pengguna telah memilih keluar.
• kecuali pengguna telah menolak. https://api.capgo.app.
• Token Push Asli Dibuat. Gunakan registrationChanged untuk memastikan pembaruan token.

Identitas Tidak Sah

Identitas terikat dengan ID aplikasi Capgo dan ID eksternal. Jika salah satu nilai berubah, minta identitas baru.

Tidak perlu menyimpan satu identitas selamanya atau menggunakan identitas yang sama di aplikasi lain. Mintakan identitas dari backend setelah login, kembalikan ke aplikasi, dan panggil register.

Perangkat Terdaftar Tapi Izin Ditolak

Plugin dapat mendaftarkan status perangkat bahkan ketika pengguna menolak izin. Anda masih bisa melihat perangkat, tapi notifikasi yang terlihat tidak akan ditampilkan.

Gunakan layar primer izin sebelum meminta izin OS. Jelaskan apa yang pengguna dapatkan, lalu minta izin hanya ketika aksi membuat sense.

Masalah Pengiriman

Masuk Antrian Tapi Belum Dikirim

Cek:

• Status kunci platform adalah configured dalam Capgo.
• Lingkungan pekerjaan berisi referensi rahasia yang tepat seperti yang ditunjukkan oleh dashboard.
• ID paket atau ID paket aplikasi sesuai dengan pengaturan push platform.
• Target audiens berubah menjadi setidaknya satu perangkat aktif.
• Kampanye ini tidak terbatas pada tag atau segment yang tidak ada di perangkat.

Dikirim Tapi Belum Diterima

Cek:

• Perangkat online.
• Aplikasi tidak ditutup paksa oleh pengguna.
• Ijin notifikasi OS telah diberikan.
• Penghematan baterai Android tidak menghalangi aplikasi selama pengujian.
• Mode Energi Rendah iOS dan pengaturan refresh latar belakang tidak mempengaruhi pengiriman latar belakang.
• Pemberitahuan tidak digantikan oleh pemberitahuan lain dengan ID penggumpalan yang sama.

Native push platforms can accept a notification and still delay, throttle, coalesce, or drop delivery later. Treat provider accepted stats as “accepted for delivery”, not proof that the device displayed it.

Judul bagian “Diterima Tapi Tidak Ditampilkan”

Check:

• Aplikasi tidak berada di depan. Pemberitahuan latar depan biasanya dikirim ke JavaScript sehingga aplikasi dapat menentukan apa yang harus ditampilkan dalam UI.
• Peringatan Android channel memiliki prioritas tinggi untuk menampilkan peringatan.
• Perizinan pemberitahuan Android 13+ telah diberikan.
• Pengaturan fokus, ringkasan pemberitahuan, atau pengaturan pemberitahuan per aplikasi iOS tidak menyembunyikan pemberitahuan.
• Logika membersihkan badge atau membuka aplikasi tidak menghapus pemberitahuan yang telah terkirim selama tes.

Pengaturan Pemberitahuan Latar Belakang

Panggilan Balik Latar Belakang Tidak Berjalan

Pemberitahuan latar belakang merupakan upaya terbaik. Sistem operasi dapat melewatinya.

Tinjau:

• iOS memiliki Pengaturan Latar Belakang > Pemberitahuan Jarak Jauh diaktifkan.
• iOS AppDelegate.swift mengalihkan pemberitahuan remote ke CapgoNotificationsRemoteNotification.
• Anda menguji perilaku latar belakang iOS pada perangkat fisik.
• Applikasi tidak ditutup paksa oleh pengguna.
• Panggilan latar belakang memanggil finish().
• Kerja di dalam callback singkat, aman jaringan, dan idempoten.

Pada iOS, pemberitahuan latar belakang mungkin dikurangi jika Anda mengirim terlalu banyak, menggunakan waktu terlalu lama, atau pengguna jarang membuka aplikasi. Ini adalah perilaku platform yang diharapkan.

Latar Belakang Dimulai Tapi Belum Selesai

Jika statistik menunjukkan background_started tanpa background_finished, handler JavaScript mungkin melempar, waktu habis, atau tidak memanggil finish().

Pasang handler di try/finally:

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

Masalah Pengecekan Perbarui Diam

Pemberitahuan Perbarui Tiba Tetapi Tidak Ada Perbarui Terpasang

Cek:

• @capgo/capacitor-updater terpasang dan terkonfigurasi.
• autoUpdater atau true atau enableUpdaterIntegration atau
• Pengaturan Notifikasi aplikasi memungkinkan pengecekan pembaruan push.
• Perangkat target milik saluran yang Anda harapkan.
• Applikasi memiliki paket yang lebih baru tersedia di Capgo.
• Pengaturan update Anda benar: next menunggu untuk restart atau siklus latar belakang berikutnya, set menginstal segera ketika pembaruan dapat melakukannya dengan aman.

Jalankan periksa manual saat aplikasi terbuka:

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

console.log(result)

Jika periksa manual mengembalikan unavailable, periksa terlebih dahulu pengaturan plugin pembaruan.

Masalah Badge

Cek:

• Target ini berakhir di perangkat yang tepat dalam pencarian penerima.
• Platform ini mendukung ikon aplikasi untuk launcher atau layar utama yang sedang diuji.
• Pengguna belum mematikan ikon di pengaturan notifikasi sistem.
• Aplikasi tidak membersihkan ikon secara langsung saat startup.
• Anda tidak berlari lokal setBadge terhadap panggilan backend ikon.

Masalah Statistik

Statistik Tampil Duplicat

Pengiriman notifikasi setidaknya sekali. Queue retry dan platform retry dapat duplikat pengiriman. Gunakan ID notifikasi dan ID penggabungan ketika aksi aplikasi harus idempoten.

Statistik Hilang Untuk Perangkat Lama

Mesin Analitik Registry adalah untuk perangkat aktif, bukan database selamanya. Plugin harus memperbarui pendaftaran pada saat aplikasi mulai, token diperbarui, ID eksternal berubah, dan secara berkala sebelum jendela retensi perangkat aktif.

Event Terbuka Hilang

Periksa:

• Pemberitahuan tersebut termasuk stabil id.
• notificationOpened pengguna daftar pendengar terdaftar selama aplikasi dimulai.
• Aplikasi tidak mengganti aliran terbuka native dengan code kustom sebelum plugin melihatnya.
• Pengguna memang mengetuk pemberitahuan daripada membuka aplikasi secara manual.

Perintah Debug API

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'

Kirimkan tes latar depan:

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

Penyebab Umum

Gejala	Penyebab yang mungkin
Perangkat hilang dari pencarian	register tidak dipanggil, bukti tidak cocok, persetujuan palsu, ID aplikasi tidak cocok.
Di tolak izin	Prompt OS ditolak atau belum diminta.
Antrian tetapi tidak ada statistik terkirim	Kredensial platform hilang atau dinonaktifkan.
Terkirim tetapi tidak ada statistik diterima.	Perangkat offline, OS menghambat, aplikasi dihentikan paksa, atau token tidak valid.
Log notifikasi latar belakang tetapi tidak ada banner	Aplikasi berada di depan dan harus menampilkan UI internalnya.
Background tidak pernah berjalan di iOS	Kemampuan hilang, AppDelegate forwarding hilang, aplikasi dihentikan paksa, atau OS menghambat.
Periksa update tidak melakukan apa-apa	Integrasi Updater dinonaktifkan, tidak ada bundle yang lebih baru, saluran yang salah, atau mode instalasi salah paham.
Resetkan badge	Aplikasi startup code menghapus badge atau menulis badge lokal dan backend secara bersaing.

Teruskan dari Debugging

Setelah perangkat mendaftar dan sebuah notifikasi uji berhasil, gunakan Mulai Menggunakan untuk menghubungkan badge, target kampanye, dan periksa update diam ke dalam aplikasi produksi Anda.