Mengdebug

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

Mulai Dengan Catatan Perangkat

Sebelum memecahkan masalah native code, pastikan Capgo dapat melihat perangkat.

1. Buka aplikasi dan masuk sebagai pengguna yang ingin Anda uji.
2. Tunggu setelah masuk. CapgoNotifications.register(...) Dalam __CAPGO_KEEP_0__, buka
3. In Capgo, open Cari dengan ID pelanggan eksternal yang sama..
4. Panggil

Anda harus melihat setidaknya satu perangkat aktif dengan:

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

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

Tambahkan Pemantau Waktu 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

Ketika 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 dari pendaftaran atau pencarian penerima.
• ID Kampanye atau ID Pemberitahuan.
• Apakah aplikasi tersebut berada di latar depan, latar belakang, ditutup paksa, atau baru saja diinstal.
• Log perangkat dari jalur yang mereproduksi masalah tersebut.

Gunakan Log Perangkat

Tinggalkan satu perangkat nyata terhubung saat Anda mengirimkan pemberitahuan tes.

Pada Android:

• Buka Logcat Android Studio.
• Tampilkan berdasarkan ID paket aplikasi.
• Tonton log permintaan izin pemberitahuan, token native refresh, penerimaan pesan, dan JavaScript listener.
• Jika pemberitahuan yang terlihat tidak muncul, periksa dahulu pentingnya saluran pemberitahuan dan status izin Android 13+.

Pada iOS:

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

Kirim satu tes depan pertama, kemudian satu tes latar belakang, kemudian satu tes periksa pembaruan diam.

Pengaturan ini memisahkan masalah pendengar JavaScript dari batasan pengiriman latar belakang OS.

CLI Setup Did Not Finish

Judul bagian “__CAPGO_KEEP_0__ Setup Tidak Selesai” 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 lagi.

Perangkat Tidak Muncul Dalam Pencarian Penerima

Periksa:

• register dipanggil setelah aplikasi Anda memiliki pengguna yang terautentik.
• externalId cocok dengan ID pengguna yang Anda cari di dashboard.
• identityProof diciptakan oleh backend Anda untuk yang sama appId dan externalId.
• appId di configure cocok dengan aplikasi Capgo.
• consent tidak diatur ke 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 Sah

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 Anda setelah login, kembalikan ke aplikasi, dan panggil register.

Sudah Terdaftar Perangkat 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 didapatkan pengguna, kemudian minta izin hanya ketika aksi membuat sense.

Masalah Pengiriman

Tunggu Tetapi Belum Dikirim

Periksa:

• Status kredensial platform adalah configured in Capgo.
• ID Paket atau ID Paket Aplikasi sesuai dengan pengaturan push platform.
• Audien target berubah menjadi perangkat aktif minimal satu.
• Kampanye tidak terbatas pada tag atau segment perangkat tidak memiliki.
• Kampanye tidak terbatas pada tag atau segment perangkat tidak memiliki.

Dikirim 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 Energi Rendah iOS dan refresh latar belakang tidak mempengaruhi pengiriman latar belakang.
• Pemberitahuan tidak digantikan oleh pemberitahuan lain dengan ID penggabungan yang sama.

Platform push asli dapat menerima pemberitahuan dan masih menunda, mengurangi, menggabungkan, atau mengabaikan pengiriman kemudian. Tatalaksana statistik yang diterima oleh penyedia sebagai “diterima untuk pengiriman”, bukan bukti bahwa perangkat menampilkan pemberitahuan.

Diterima Tapi Tidak Ditampilkan

Periksa:

• Aplikasi tidak berada di latar depan. Notifikasi latar belakang biasanya dikirim ke JavaScript sehingga aplikasi dapat menentukan UI apa yang harus ditampilkan.
• Prioritas saluran notifikasi Android cukup tinggi untuk menampilkan peringatan.
• Ijin notifikasi Android 13+ telah diberikan.
• Pengaturan fokus iOS, 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

Notifikasi latar belakang merupakan upaya terbaik. Sistem operasi dapat melewatkan mereka.

Periksa:

• iOS memiliki Mode Latar Belakang > Pemberitahuan Jarak Jauh dihubungkan.
• iOS AppDelegate.swift mengirimkan 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.

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

Dibuka di Latar Belakang Tapi Belum Selesai

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

Bungkus handler dengan try/finally:

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

Masalah Periksa Pembaruan Tanpa Suara

Pemberitahuan Periksa Pembaruan Tiba Tapi Tidak Ada Pembaruan Terpasang

Periksa:

• @capgo/capacitor-updater terpasang dan terkonfigurasi.
• autoUpdater terpasang dan terkonfigurasi. true atau disebutkan. enableUpdaterIntegration Pengaturan Notifikasi aplikasi memungkinkan pengecekan pembaruan push.
• Perangkat target milik saluran yang Anda harapkan.
• Aplikasi Anda memiliki bundle yang lebih baru di __CAPGO_KEEP_0__.
• The app has a newer bundle available in Capgo.
• antrian untuk siklus restart atau siklus latar belakang berikutnya. next dipasang segera ketika pembarui dapat melakukannya dengan aman. set Lakukan pengecekan manual sambil aplikasi terbuka:

Salin ke clipboard

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

console.log(result)

, periksa terlebih dahulu pengaturan plugin pembarui. unavailableSalin ke clipboard

Masalah Badge

Check:

• Targetnya mengarah ke perangkat yang benar dalam pencarian penerima.
• Platform ini mendukung badge aplikasi untuk launcher atau layar utama yang sedang diuji.
• Pengguna belum mematikan badge di pengaturan notifikasi OS.
• Aplikasi tidak menghapus badge secara langsung saat startup.
• Anda tidak melakukan tes lokal setBadge panggilan terhadap pengiriman badge backend.

Masalah Statistik

Masalah Statistik Tampilan Duplicat

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

Stat Tidak Tampil Untuk Perangkat Lama

Registri Engine Analitik 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.

Event Terbuka Tidak Tampil

Periksa:

• Notifikasi termasuk stabil id.
• notificationOpened Pengaturan listener terdaftar pada saat mulai aplikasi.
• Aplikasi tidak mengganti aliran buka native dengan custom code sebelum plugin melihatnya.
• Pengguna memang mengetuk notifikasi bukan 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 belakang:

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

Pemicu Umum

Gejala	Penyebab yang mungkin
Perangkat hilang dari pencarian	register tidak dipanggil, bukti tidak sesuai, persetujuan palsu, ID aplikasi tidak sesuai.
Ditolak akses	Prompt OS ditolak atau belum diminta.
Ditangguhkan tapi tidak ada statistik terkirim	Kredensial platform hilang atau dinonaktifkan.
Terkirim tapi tidak ada statistik diterima	Perangkat offline, OS menghambat, aplikasi dihentikan paksa, atau token tidak valid.
Log notifikasi latar belakang tapi tidak ada banner	Aplikasi berada di latar depan dan harus menampilkan UI dalam aplikasi sendiri.
Latar belakang tidak pernah menjalankan pada iOS	Kemampuan hilang, AppDelegate forwarding hilang, aplikasi dipaksa keluar, atau pengurangan OS.
Periksa update tidak melakukan apa-apa	Integrasi pembaruan dimatikan, tidak ada bundle yang lebih baru, saluran salah, atau mode instalasi salah paham.
Lambang reset	Mulai aplikasi code menghapus lambang atau tulisan lambang lokal dan backend bersaing.

Lanjutkan dari Debugging

Setelah perangkat mendaftar dan sebuah notifikasi uji berhasil, gunakan Getting Started untuk menghubungkan lambang, target kampanye, dan periksa update diam ke dalam aplikasi produksi.