@capgo/capacitor-notifications

Ikhtisar

@capgo/capacitor-notifications menghubungkan aplikasi Capacitor ke pipeline notifikasi native Capgo. Aplikasi Anda mendaftarkan signed customer user ID ke Capgo, Capgo menyimpan status perangkat aktif terbaru di Cloudflare Analytics Engine, dan Anda dapat mengirim notifikasi, mengatur badge, memeriksa statistik pengiriman, serta memicu silent Capgo live-update check dari dashboard Capgo atau API.

Fitur ini dirancang untuk menghindari tabel perangkat notifikasi dengan high-cardinality di Capgo Postgres. Postgres hanya menyimpan data control plane low-cardinality seperti pengaturan aplikasi, metadata kredensial platform, draf kampanye, jadwal, dan rekam agregat kampanye. Status perangkat aktif dan event notifikasi disimpan sebagai baris append-only di Analytics Engine.

Dukungan platform

Platform	Dukungan	Catatan
iOS	Ya	APNs melalui Capgo
Android	Ya	FCM via Capgo
Web	Tidak	Gunakan web push secara terpisah

Apa yang Disimpan Capgo

Data	Lokasi penyimpanan	Mengapa
Metadata kredensial platform	Capgo Postgres	Dibutuhkan untuk mengelola setup dan izin aplikasi.
Secret platform privat	Lingkungan Worker	Menghindari penyimpanan kredensial privat di tabel publik.
Draft dan pengaturan kampanye	Capgo Postgres	Data control plane dengan kardinalitas rendah.
Status registrasi perangkat aktif	Cloudflare Analytics Engine	Registry perangkat aktif append-only yang murah.
Event notifikasi	Mesin Analitik Cloudflare	Statistik hemat untuk event antrean, terkirim, diterima, dibuka, gagal, dan background.

Model Identitas

Capgo tidak meminta Anda mengunggah daftar user atau mengelola tabel device.

• Backend Anda sudah mengetahui user ID pelanggan yang sebenarnya.
• Backend Anda meminta Capgo untuk token berdurasi pendek identityProof.
• Aplikasi mendaftar dengan externalId dan bukti tersebut setelah autentikasi user Anda berhasil.
• Capgo menghasilkan internal key deterministik untuk penerima dan native install.
• Mengirim ke yang sama externalId menemukan kembali device aktif milik user tersebut.

Fitur ini memungkinkan Anda mencari perangkat pengguna, mengatur badge, dan menargetkan kampanye notifikasi tanpa perlu menyimpan baris notifikasi per perangkat di Capgo Postgres.

Kemampuan Utama

• Daftarkan perangkat dengan ID pengguna eksternal yang terautentikasi.
• Segarkan tag, atribut, persetujuan, dan status token saat aplikasi dimulai atau saat ada perubahan token.
• Terima notifikasi foreground di JavaScript.
• Lacak event notifikasi saat diterima dan dibuka.
• Tangani notifikasi data di background.
• Atur, hapus, dan tambah jumlah badge aplikasi.
• Buat Android notification channels.
• Kirim notifikasi sekali jalan, notifikasi kampanye, pembaruan badge, dan pengecekan silent update.
• Trigger @capgo/capacitor-updater dari silent notification.

Statistik

Capgo menulis event notifikasi ke Cloudflare Analytics Engine agar statistik dashboard tetap hemat biaya:

• queued
• sent
• provider_accepted
• received
• opened
• failed
• permission_changed
• background_started
• background_finished

Stats adalah sinyal operasional, bukan buku besar permanen per-penerima. Retensi Analytics Engine berarti perangkat aktif harus melakukan refresh registrasi secara berkala.

API Publik

Metode	Deskripsi
configure	Mengatur Capgo app ID, API host, dan perilaku integrasi updater.
register	Mendaftarkan instalasi saat ini untuk external customer user ID.
setExternalId	Mengubah external customer user ID setelah login atau ganti akun.
setTags	Mengganti tag yang digunakan untuk targeting audiens.
setBadge	Mengatur badge pada aplikasi native.
clearBadge	Menghapus badge pada aplikasi native.
incrementBadge	Menambah jumlah badge pada aplikasi native.
enableUpdaterIntegration	Mengaktifkan penanganan silent update-check melalui @capgo/capacitor-updater.
runUpdateCheck	Menjalankan integrasi updater secara manual untuk testing.
trackReceived	Menulis event 'received' secara manual.
trackOpened	Menulis event 'opened' secara manual.
addListener('notificationReceived')	Dipicu saat notifikasi diterima ketika JavaScript sedang aktif.
addListener('notificationOpened')	Dipicu saat user membuka notifikasi.
addListener('backgroundNotification')	Dipicu untuk notifikasi data di background dan mengekspos finish().
addListener('registrationChanged')	Dipicu saat native push token berubah.

Jaminan Pengiriman

Push native menggunakan sistem at-least-once. Sebuah campaign dapat dicoba ulang, dan perangkat bisa menerima duplikat jika platform menerima pesan berulang. Gunakan collapse ID untuk pengecekan update dan pastikan background work bersifat idempotent.

Notifikasi background iOS bersifat best-effort. OS dapat membatasi atau melewatkan eksekusi background berdasarkan baterai, perilaku pengguna, status force-quit, dan kebijakan sistem. Jangan mengandalkan silent notification untuk deadline yang ketat.

Lanjutkan dari @capgo/capacitor-notifications

Jika Anda menggunakan @capgo/capacitor-notifications untuk merencanakan push messaging, hubungkan dengan Panduan Memulai untuk setup, Debugging untuk troubleshooting, @capgo/capacitor-updater untuk pengecekan silent update, dan Direktori Plugin Capgo untuk plugin native lainnya.