Debugging

Pakai daftar periksa ini ketika notifikasi tidak terdaftar, tidak datang, tidak ditampilkan, atau tidak diperbarui 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. Di Capgo, buka Notifikasi > Pencarian Penerima.
4. Cari berdasarkan ID pelanggan eksternal yang sama.

Anda harus melihat setidaknya satu perangkat aktif dengan:

• recipientKey
• deviceKey
• platform android atau ios
• Apakah Anda ingin menggunakan Cloudflare, Capacitor, atau GitHub?
• status izin
• versi aplikasi
• versi plugin

tag dan atribut

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

Tambahkan pemantau waktu 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

Ketika debugging bersama tim atau Capgo dukungan, kumpulkan:

• ID Aplikasi Capgo.
• ID Paket Aplikasi atau ID Paket 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 jalur yang mengulangi masalah.

Pakai Log Perangkat

Tetapkan satu perangkat nyata yang 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 dahulu pentingnya saluran notifikasi dan status izin Android 13+.

On iOS:

• Jalankan aplikasi dari Xcode pada perangkat fisik.
• Buka konsol Xcode atau Perangkat dan Simulator dan log.
• Filter berdasarkan ID paket dan CapgoNotifications.
• Konfirmasi AppDelegate.swift untuk memastikan bahwa notifikasi jarak jauh dapat dikirim dan kemampuan mode latar belakang diaktifkan.

Kirimlah satu tes notifikasi depan terlebih dahulu, kemudian satu tes latar belakang, kemudian satu tes pembaruan diam-diam. Urutan ini memisahkan masalah pendengar JavaScript dari batasan pengiriman latar belakang sistem operasi.

Masalah Pendaftaran

CLI Pengaturan Tidak Selesai

Jalankan perintah pengaturan dari folder yang berisi 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 Capgo telah mengaktifkan akses paket private-preview untuk akun npm Anda, lalu jalankan perintah tersebut lagi.

Ponsel Tidak Muncul Dalam Pencarian Penerima

Cek:

• register di panggil setelah aplikasi Anda memiliki pengguna yang telah terautentikasi.
• externalId cocok dengan ID pengguna yang Anda cari di dashboard.
• identityProof ditambahkan oleh backend Anda untuk yang sama appId dan externalId.
• appId dalam configure sesuai dengan aplikasi Capgo.
• consent tidak diatur untuk false kecuali pengguna telah menolak.
• Perangkat memiliki akses jaringan ke https://api.capgo.app.
• Token push asli telah dibuat. Gunakan registrationChanged untuk memastikan pembaruan token.

Bukti Identitas Tidak Valid

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

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

Perangkat Terdaftar Tapi Izin Ditolak

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

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

Masalah Pengiriman

Masuk Antrian Tapi Tidak Dikirim

Cek:

• Status kredential platform adalah configured di Capgo.
• Lingkungan pekerjaan berisi referensi rahasia yang tepat seperti yang ditampilkan oleh dashboard.
• Paket ID atau ID Paket di aplikasi sesuai dengan pengaturan push platform.
• Target audiens berubah menjadi setidaknya satu perangkat aktif.
• Kampanye tidak dibatasi pada tag atau segment yang perangkat tidak miliki.

Kirim Tapi Tidak Diterima

Periksa:

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

Platform push asli dapat menerima notifikasi dan masih menunda, mengurangi, menggabungkan, atau mengabaikan pengiriman nanti. Tatalah statistik yang diterima oleh penyedia sebagai “diterima untuk pengiriman”, bukan bukti bahwa perangkat menampilkan hal itu.

Diterima Tapi Tidak Ditampilkan

Cek:

• Aplikasi tidak berada di latar depan. Notifikasi latar depan biasanya dikirim ke JavaScript sehingga aplikasi dapat menentukan UI apa yang harus ditampilkan.
• Prioritas notifikasi kanal Android cukup tinggi untuk menampilkan peringatan.
• Izinkan notifikasi Android 13+.
• Pengaturan fokus, ringkasan notifikasi, atau pengaturan notifikasi per aplikasi tidak menyembunyikan notifikasi.
• Logika membersihkan badge atau membuka aplikasi tidak menghapus notifikasi yang telah dikirim selama tes.

Masalah Notifikasi Latar Belakang

Panggilan Balik Latar Belakang Tidak Berjalan

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

Cek:

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

On iOS, push notifikasi di latar belakang mungkin dibatasi jika Anda mengirim terlalu banyak, menggunakan waktu yang 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 kesalahan, waktu habis, atau tidak memanggil finish().

Langkapi handler dengan try/finally:

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

Masalah Periksa Update Tanpa Suara

Pemberitahuan Periksa Update Tiba Tapi Tidak Ada Update Terpasang

Periksa:

• @capgo/capacitor-updater terpasang dan terkonfigurasi.
• autoUpdater adalah true atau enableUpdaterIntegration context: Alternatif CTA Pertanyaan. Halaman/Areas: Halaman perbandingan alternatif Capgo. Peran: Paragraf pemasaran atau hukum panjang. Dilihat di: halaman alternatives.astro. Simpan Capgo produk/merek dan istilah pengembang secara tepat.
• adalah
• context: Pertanyaan CTA Appflow. Halaman/Areas: Halaman perbandingan/migrasi pemasaran Appflow. Peran: Paragraf pemasaran atau hukum panjang. Dilihat di: halaman ionic-appflow.astro. Simpan Capgo produk/merek dan istilah pengembang secara tepat.
• The app has a newer bundle available in Capgo.
• context: Pertanyaan CTA Capwesome. Halaman/Areas: Halaman perbandingan Capwesome. Peran: Paragraf pemasaran atau hukum panjang. Dilihat di: halaman capwesome.astro. Simpan Capgo produk/merek dan istilah pengembang secara tepat. next context: Subjudul FAQ Konsultasi. Halaman/Areas: Halaman layanan konsultasi. Peran: Subjudul atau tagline. Dilihat di: halaman consulting.astro. Simpan Capgo produk/merek dan istilah pengembang secara tepat. set context: Appflow Plugins Atau. Halaman/Areas: Halaman perbandingan/migrasi pemasaran Appflow, halaman plugin Ionic Enterprise, halaman solusi plugin Ionic Enterprise. Peran: Label UI singkat atau item navigasi. Dilihat di: halaman ionic-appflow.astro, halaman ionic-enterprise-plugins.astro, halaman solusi/ionic-enterprise-plugins.astro. Simpan Capgo produk/merek dan istilah pengembang secara tepat.

disebutkan sebagai.

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

Periksa:

• Tujuan resolusi menuju perangkat yang benar dalam pencarian penerima.
• Platform mendukung badge aplikasi untuk launcher atau layar utama yang sedang diuji.
• Pengguna belum menonaktifkan badge di pengaturan notifikasi OS.
• Aplikasi tidak membersihkan badge secara langsung saat startup.
• Anda tidak berlari panggilan lokal setBadge terhadap pengiriman badge backend.

Masalah Statistik

Statistik Tampil Duplicat

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

Statistik Hilang Untuk Perangkat Lama

Mesin Analitik registry adalah untuk perangkat aktif, bukan database selamanya. Plugin harus memperbarui registrasi pada mulai aplikasi, refresh token, perubahan ID eksternal, dan secara berkala sebelum jendela retensi perangkat aktif.

Pemberitahuan Acak Tidak Tampil

Cek:

• Pemberitahuan termasuk stabil id.
• notificationOpened Pengaturan pendengar terdaftar selama aplikasi startup.
• Aplikasi tidak mengganti aliran buka native dengan code sebelum plugin melihatnya.
• Pengguna benar-benar mengetuk notifikasi 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'

Kirim uji 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.
Ditolak izin	Prompt OS ditolak atau belum diminta.
Antrian tapi tidak ada statistik terkirim	Kredensial platform hilang atau dinonaktifkan.
Telah dikirim tapi tidak ada statistik yang diterima	Perangkat offline, OS mengurangi kecepatan, aplikasi ditutup paksa, atau token tidak valid.
Log notifikasi di depan tapi tidak banner	Aplikasi harus menampilkan UI dalam aplikasi sendiri karena aplikasi berada di 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 tidak dipahami.
Jumlah badge direset	Aplikasi startup code menghapus badge atau menulis badge lokal dan backend bersaing.

Teruskan dari Debugging

Setelah perangkat mendaftar dan sebuah notifikasi uji berhasil, gunakan Mulai untuk menghubungkan tombol bintang, target kampanye, dan pengecekan pembaruan diam ke dalam aplikasi produksi Anda.