Pengaturan 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 harus 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 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 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 yang menghasilkan masalah.

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 notifikasi yang terlihat 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 dikirim dan kemampuan mode latar belakang diaktifkan. AppDelegate.swift Kirimlah satu tes notifikasi depan terlebih dahulu, kemudian satu tes latar belakang, kemudian satu tes pemeriksaan update-senyap. Urutan ini memisahkan masalah pendengar JavaScript dari batasan pengiriman latar belakang sistem.

Masalah Pendaftaran

Bagian berjudul “Masalah Pendaftaran”

CLI Setup Did Not Finish

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

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

If the command cannot infer your app ID, pass it explicitly as shown above. If package installation fails, confirm Capgo has enabled private-preview package access for your npm account, then rerun the command.

Aplikasi Tidak Muncul Dalam Pencarian Penerima

Cek:

• register di panggil setelah aplikasi Anda memiliki pengguna yang telah terautentikasi.
• externalId sama dengan ID pengguna yang Anda cari di dashboard.
• identityProof ditambahkan oleh backend Anda untuk aplikasi yang sama appId dan externalId.
• appId di configure sesuai dengan aplikasi Capgo.
• consent tidak diatur untuk false kecuali pengguna telah menolak.
• Perangkat memiliki akses jaringan ke https://api.capgo.app.
• Bukti 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.

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 membuat sense.

Masalah Pengiriman

Tidak Dikirim

Periksa:

• Status kunci platform adalah configured Capgo.
• Lingkungan pekerjaan berisi referensi rahasia yang tepat seperti yang ditampilkan oleh dashboard.
• ID paket atau ID bundle di aplikasi sesuai dengan pengaturan push platform.
• Audien target berubah menjadi setidaknya satu perangkat aktif.
• Kampanye tidak terbatas pada tag atau segment yang tidak dimiliki perangkat.

Dikirim Tapi Tidak Diterima

Periksa:

• Perangkat online.
• Aplikasi tidak ditutup paksa oleh pengguna.
• Izin notifikasi OS diberikan.
• Restriksi baterai Android tidak menghalangi aplikasi selama pengujian.
• Mode Energi Rendah iOS dan restriksi 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 notifikasi tersebut.

Terima 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.

Periksa:

• iOS memiliki Mode Latar Belakang > Pemberitahuan Jarak Jauh dihubungkan.
• 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 handler latar belakang memanggil finish().
• Lakukan pekerjaan 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 di 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 Datang Tapi Tidak Ada Update yang Dibuat

Periksa:

• @capgo/capacitor-updater terpasang dan terkonfigurasi.
• autoUpdater atau true atau enableUpdaterIntegration atau
• disebut.
• Pengaturan Notifikasi aplikasi memungkinkan pengecekan pembaruan push.
• The app has a newer bundle available in Capgo.
• Aplikasi memiliki paket yang lebih baru tersedia di __CAPGO_KEEP_0__. next Mode instalasi pembaruan Anda benar: set menunggu untuk restart atau siklus latar belakang berikutnya,

dipasang segera ketika pembaruan dapat dilakukan dengan aman.

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:

• 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 OS.
• Aplikasi tidak membersihkan badge secara langsung saat startup.
• Anda tidak berlari panggilan lokal setBadge terhadap pengiriman badge backend.

Masalah Statistik

Statistik Tampil Berulang

Pengiriman notifikasi setidaknya sekali. Antrian ulang dan ulang platform dapat mengulang pengiriman. Gunakan ID notifikasi 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.

Event Terbuka Hilang

Periksa:

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

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

Pemicu Umum

Gejala	Penyebab yang mungkin
Perangkat hilang dari pencarian	register tidak dipanggil, bukti tidak sesuai, persetujuan palsu, ID aplikasi tidak sesuai.
Ditolak izin	Izin OS ditolak atau belum diminta.
Antrian tapi tidak ada statistik terkirim	Kredensial platform hilang atau dinonaktifkan.
Terkirim tapi tidak ada statistik menerima	Tidak ada koneksi perangkat, 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.
Tidak pernah menjalankan latar belakang di iOS	Kemampuan hilang, AppDelegate tidak dapat di depan, aplikasi ditutup paksa, atau OS mengurangi kecepatan.
Pengecekan update tidak melakukan apa-apa	Pengintegrasian pembaruan di nonaktifkan, 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 berlari.

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.