Debugging

Pakai daftar periksa ini ketika notifikasi tidak terdaftar, tidak datang, tidak ditampilkan, 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. Panggil CapgoNotifications.register(...) context
3. Dalam Capgo, buka Pemberitahuan > Pencarian Penerima.
4. Cari berdasarkan ID Pelanggan Eksternal yang sama.

Anda seharusnya melihat setidaknya satu perangkat aktif dengan:

• recipientKey
• deviceKey
• platform android atau ios
• atau
• status izin
• versi aplikasi
• versi plugin

tag dan atribut

Jika pencarian tidak menemukan perangkat, jalur pengiriman tidak dapat menargetkan pengguna tersebut.

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 Bundle iOS.
• Platform perangkat dan versi OS.
• Versi Aplikasi dan nomor pembangunan.
• Versi Plugin.
• ID Pelanggan Eksternal.
• recipientKey dan deviceKey atau pencarian penerima.
• ID Kampanye atau ID Notifikasi.
• Apakah aplikasi berada di latar depan, latar belakang, ditutup paksa, atau baru saja diinstal.
• Log perangkat dari jalannya masalah yang diulang.

Pakai Log Perangkat

Tinggalkan satu perangkat nyata terhubung saat Anda mengirimkan notifikasi uji.

Pada Android:

• Buka Logcat Android Studio.
• Filter berdasarkan ID paket aplikasi.
• Tunggu permintaan izin notifikasi, pembaruan token native, penerimaan pesan, dan log pendengar JavaScript.
• Jika sebuah notifikasi yang dapat dilihat tidak muncul, periksa pentingnya saluran notifikasi dan status izin Android 13+ terlebih dahulu.

Di iOS:

• Jalankan aplikasi dari Xcode pada perangkat fisik.
• Buka konsol Xcode atau Perangkat dan Simulator Filter berdasarkan ID paket dan
• Konfirmasi CapgoNotifications.
• untuk memastikan bahwa notifikasi remote dikirimkan dan kemampuan mode latar belakang diaktifkan. AppDelegate.swift Kirimkan tes depan terlebih dahulu, kemudian tes latar belakang, kemudian tes pemeriksaan update-senyap. Urutan ini memisahkan masalah pendengar JavaScript dari batasan pengiriman latar belakang sistem operasi.

Masalah Pendaftaran

Bagian berjudul “Masalah Pendaftaran”

CLI Pengaturan Tidak Selesai

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

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

Jika perintah tidak dapat menduga 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

Periksa:

• register apakah disebut setelah aplikasi Anda memiliki pengguna yang terautentikasi.
• externalId cocok dengan ID pengguna yang Anda cari di dashboard.
• identityProof ditambahkan oleh backend Anda untuk yang sama. appId dan externalId.
• appId context: Halaman/area: Situs web pemasaran Capgo. Peran: Label UI singkat atau item navigasi. Dilihat di: halaman trust.astro. Kunci pesan `dan` (And). configure matches the Capgo app.
• consent cocok dengan aplikasi __CAPGO_KEEP_0__. false tidak diatur ke
• kecuali pengguna menolak. https://api.capgo.app.
• Perangkat memiliki akses jaringan ke registrationChanged Token push asli telah dibuat. Gunakan

untuk memastikan pembaruan token.

Bukti itu terkait dengan ID aplikasi Capgo dan ID eksternal. Jika salah satu nilai berubah, minta bukti baru.

Tidak perlu menyimpan bukti selamanya atau menggunakan bukti yang sama di aplikasi lain. Mint bukti dari backend Anda setelah login, kembalikan ke aplikasi, dan panggil register.

Perangkat Terdaftar Tapi Izin Ditolak

Plugin ini dapat mendaftarkan keadaan perangkat bahkan ketika pengguna menolak izin. Anda masih bisa melihat perangkat, tetapi notifikasi yang terlihat tidak akan muncul.

Pakai layar primer izin sebelum prompt OS. Jelaskan apa yang pengguna dapatkan, lalu minta izin hanya ketika aksi itu masuk akal.

Masalah Pengiriman

Masuk Antrian Tapi Belum Dikirim

Cek:

• Status kredensial platform adalah configured dalam Capgo.
• Lingkungan pekerjaan pekerjaan berisi rujukan rahasia yang tepat seperti yang ditunjukkan oleh dashboard.
• ID paket atau ID paket aplikasi sesuai dengan pengaturan push platform.
• Audien sasaran berubah menjadi perangkat aktif minimal satu.
• Kampanye tidak terbatas pada tag atau segment perangkat tidak memiliki.

Dikirim Tapi Tidak Diterima

Periksa:

• Perangkat online.
• Aplikasi tidak ditutup paksa oleh pengguna.
• Izin pemberitahuan OS diberikan.
• Pengaturan batasan baterai Android tidak menghalangi aplikasi selama pengujian.
• iOS Mode Energi Rendah dan pembatasan refresh latar belakang tidak mempengaruhi pengiriman latar belakang.
• Pemberitahuan tersebut tidak digantikan oleh pemberitahuan lain dengan ID penggabungan yang sama.

Platform push native dapat menerima pemberitahuan dan masih menunda, mengurangi, menggabungkan, atau menghilangkan pengiriman nanti. Tatalaksana statistik yang diterima sebagai “diterima untuk pengiriman”, bukan bukti bahwa perangkat menampilkan itu.

Diterima Tapi Tidak Ditampilkan

Periksa:

• Aplikasi tidak di foreground. Pemberitahuan foreground biasanya dikirimkan ke JavaScript sehingga aplikasi dapat menentukan UI apa yang harus ditampilkan.
• Prioritas saluran pemberitahuan Android cukup tinggi untuk menampilkan peringatan.
• Ijin pemberitahuan Android 13+ diberikan.
• Pengaturan fokus iOS, ringkasan pemberitahuan, atau pengaturan pemberitahuan per aplikasi tidak menyembunyikan pemberitahuan.
• Logika membersihkan badge atau membuka aplikasi tidak menghilangkan pemberitahuan yang sudah dikirimkan selama tes.

Masalah Pemberitahuan Latar Belakang

Panggilan Balik Latar Belakang Tidak Berjalan

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

Periksa:

• iOS memiliki Mode Latar Belakang > Notifikasi jarak jauh dinyalakan.
• iOS AppDelegate.swift mengalihkan notifikasi jarak jauh ke CapgoNotificationsRemoteNotification.
• Anda menguji perilaku latar belakang iOS pada perangkat fisik.
• Aplikasi tidak ditutup paksa oleh pengguna.
• Pemanggil tugas latar belakang memanggil finish().
• Kerja di dalam callback singkat, aman jaringan, dan idempoten.

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

Mulai Latar Belakang Tapi Belum Selesai

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

Bungkus handler di try/finally:

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

Masalah Periksa Update Diam

Pemberitahuan Periksa Update Tiba Tapi Tidak Menginstal Update

Cek:

• @capgo/capacitor-updater terpasang dan dikonfigurasi.
• autoUpdater atau true atau enableUpdaterIntegration atau
• Pemberitahuan Periksa Update Tiba Tapi Tidak Menginstal Update
• Diinstal dan Dikatakan:
• The app has a newer bundle available in Capgo.
• Apk Anda memiliki versi yang lebih baru di __CAPGO_KEEP_0__. next Pemberitahuan Instalasi Update Anda Benar: set terpasang segera ketika pembarui dapat melakukannya dengan aman.

Lakukan pengecekan manual saat aplikasi terbuka:

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

console.log(result)

Jika pengecekan manual mengembalikan unavailable, periksa terlebih dahulu pengaturan plugin pembarui.

Masalah Badge

Periksa:

• Target berakhir pada perangkat yang tepat dalam pencarian penerima.
• Platform mendukung badge aplikasi untuk launcher atau layar utama yang sedang diuji.
• Pengguna belum mematikan badge di pengaturan notifikasi sistem.
• Aplikasi tidak membersihkan badge secara langsung saat startup.
• Kamu tidak melakukan panggilan lokal setBadge Panggilan tidak terkirim ke backend.

Masalah Statistik

Statistik Tampil Berulang

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

Statistik Tidak Tampil untuk Perangkat Lama

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

Penggunaan Acak Tidak Tampil

Periksa:

• Pemberitahuan tersebut termasuk sebuah id.
• notificationOpened pengaturan pendengar stabil terdaftar selama aplikasi startup.
• Aplikasi tidak mengganti aliran buka native dengan code sebelum plugin melihatnya.
• Pengguna memang mengetuk pemberitahuan bukan membuka aplikasi secara manual.

API Debug Commands

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 di 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 sesuai, persetujuan palsu, ID aplikasi tidak sesuai.
Ijin ditolak	Prompt OS ditolak atau belum diminta.
Statistik antrian tapi tidak dikirim	Kredensial platform hilang atau dinonaktifkan.
Statistik dikirim tapi tidak diterima	Perangkat offline, OS mengurangi kecepatan, aplikasi ditutup paksa, atau token tidak valid.
Log notifikasi latar belakang tapi tidak banner	Aplikasi harus menampilkan UI dalam aplikasi sendiri karena aplikasi berada di latar depan.
Background tidak pernah berjalan di iOS	Kemampuan hilang, AppDelegate forwarding hilang, aplikasi ditutup paksa, atau OS mengurangi kecepatan.
Pengecekan update tidak melakukan apa-apa	Pengintegrasian updater dinonaktifkan, tidak ada bundle yang lebih baru, saluran salah, atau mode instalasi salah paham.
Jumlah badge direset	Aplikasi startup code menghapus badge atau menulis badge lokal dan backend bersaing.

Lanjutkan dari Debugging

Setelah perangkat terdaftar dan notifikasi uji berhasil, gunakan Mulai untuk menghubungkan badge, target kampanye, dan pengecekan pembaruan diam ke aplikasi produksi Anda.