Mulai Menggunakan

@capgo/capacitor-notifications adalah plugin pertama-tama Capgo untuk pemberitahuan push native iOS dan Android. Ini dibangun untuk Capgo’s dashboard, publik API, Mesin Analitik perangkat daftar perangkat, statistik kampanye, pembaruan badge, dan periksa live-update diam.

Persyaratan

• Aplikasi Capacitor sudah ditambahkan ke Capgo.
• Akses ke tab Pemberitahuan aplikasi Capgo.
• Aplikasi Capgo API kunci dengan akses tulis untuk bukti backend minting dan API kirim.
• Otoritas push platform iOS dan/atau Android untuk aplikasi.
• @capgo/capacitor-updater jika Anda ingin periksa pembaruan push diam.

1. Konfigurasi Capgo Platform Kredensial

Buka aplikasi di Capgo, kemudian pilih Notifications.

Tambahkan satu entri kredensial platform untuk setiap platform yang ingin Anda dukung:

• Android ID aplikasi dan metadata proyek push Android.
• Android ID aplikasi, ID tim, ID kunci, dan metadata kunci push iOS yang sesuai.

Capgo shows the exact environment secret name that must exist in the API worker before the platform is marked configured. The dashboard stores metadata and the expected secret reference. The private credential itself stays in the worker environment.

2. Instal

Untuk pengaturan yang paling cepat, jalankan Capgo CLI dari proyek aplikasi Anda:

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

Perintah menginstal paket notifikasi, menyimpan konfigurasi plugin Capacitor, membuat file bantuan kecil, dan menjalankan Capacitor sinkron. Gunakan jalur ini untuk aplikasi baru kecuali Anda perlu menghubungkan setiap file secara manual.

Penginstalan manual:

bun add @capgo/capacitor-notifications @capgo/capacitor-updater
bunx cap sync

Jika Anda tidak menggunakan periksa update Capgo diam, Anda dapat mengabaikan @capgo/capacitor-updater.

3. Konfigurasi Plugin

Konfigurasi plugin sekali ketika aplikasi Anda dimulai.

import { CapgoNotifications } from '@capgo/capacitor-notifications'

await CapgoNotifications.configure({
  appId: 'com.example.app',
  autoUpdater: true,
  updateInstallMode: 'next',
})

Menggunakan updateInstallMode: 'next' untuk mengunduh pembaruan dan menginstalnya pada siklus restart atau latar belakang berikutnya. Gunakan updateInstallMode: 'set' Hanya ketika Anda ingin Capgo untuk menginstal pembaruan segera ketika pembaruan dapat melakukannya dengan aman.

4. Membuat Bukti Identitas

Jangan meletakkan kunci Capgo API Anda di aplikasi mobile. Backend Anda harus meminta Capgo untuk sebuah identityProof setelah autentikasi pengguna Anda sendiri berhasil.

curl -X POST 'https://api.capgo.app/notifications/recipients/proof' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: CAPGO_API_KEY' \
  -d '{
    "appId": "com.example.app",
    "externalId": "customer-user-123"
  }'

Mengembalikan identityProof ke aplikasi dengan respons sesi Anda sendiri.

5. Mendaftarkan Perangkat

Daftarkan hanya setelah Anda tahu pengguna pelanggan mana yang masuk.

const registration = await CapgoNotifications.register({
  externalId: 'customer-user-123',
  identityProof,
  tags: ['paid', 'beta'],
  attributes: {
    plan: 'team',
    locale: 'en-US',
  },
  consent: true,
})

console.log(registration.recipientKey, registration.deviceKey)

Panggil register context

• Panggil lagi ketika:
• Token perubahan push asli berubah.
• Token push native berubah.
• Pengguna yang masuk berubah.
• Aplikasi belum memperbarui registrasi dalam waktu lama.

Applikasi belum memperbarui pendaftaran selama waktu lama.

Daftarkan pemangku jawab selama aplikasi startup sehingga peristiwa latar depan, dibuka, dan latar belakang dapat terlihat oleh JavaScript.

await CapgoNotifications.addListener('registrationChanged', () => {
  void CapgoNotifications.register({
    externalId: currentUser.id,
    identityProof: currentUser.capgoNotificationProof,
    tags: currentUser.notificationTags,
    consent: currentUser.pushConsent,
  })
})

await CapgoNotifications.addListener('notificationReceived', (notification) => {
  console.log('Notification received', notification)
})

await CapgoNotifications.addListener('notificationOpened', (event) => {
  console.log('Notification opened', event.notification.id)
})

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

Selalu panggil finish() untuk peringatan latar belakang setelah pekerjaan Anda selesai. Jaga pekerjaan singkat dan idempoten.

7. Pengaturan iOS

Dalam Xcode, buka target aplikasi dan aktifkan:

• Pemberitahuan Push
• Mode Latar Belakang > Notifikasi Jarak Jauh

Teruskan pemberitahuan jarak jauh dari ios/App/App/AppDelegate.swift:

func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable: Any], fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
    NotificationCenter.default.post(name: Notification.Name("CapgoNotificationsRemoteNotification"), object: userInfo)
    completionHandler(.newData)
}

Lalu jalankan:

bunx cap sync ios

Pilih perangkat iOS fisik ketika menguji notifikasi latar belakang. Simulator berguna untuk pekerjaan UI tetapi tidak merepresentasikan perilaku push produksi latar belakang.

8. Pengaturan Android

Jalankan:

bunx cap sync android

Lalu verifikasi:

• Kredensial platform Android Anda telah dikonfigurasi di Capgo.
• ID paket aplikasi sesuai dengan ID paket yang digunakan untuk pengaturan push platform.
• Ijin notifikasi Android 13+ diminta sebelum menunggu notifikasi yang dapat dilihat.
• Aplikasi memiliki ikon notifikasi dan strategi saluran yang sesuai dengan merek Anda.
• Anda melakukan pengujian pada perangkat fisik atau emulator dengan Google Play services.

Buat saluran Android default ketika aplikasi Anda dimulai:

await CapgoNotifications.configure({ appId: 'com.example.app' })

await CapgoNotifications.register({
  externalId: currentUser.id,
  identityProof: currentUser.capgoNotificationProof,
  consent: true,
})

Plugin ini mengumumkan layanan pesan push Android. Simpan cadangan aplikasi, ekstraksi data, keamanan jaringan, dan kebijakan ikon notifikasi di aplikasi host.

9. Kirim Notifikasi Uji

Pilih Notifikasi > Kirim uji di Capgo, atau panggil API publik dari backend Anda:

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": "Hello from Capgo",
      "body": "This is a test notification.",
      "data": { "screen": "inbox" }
    }
  }'

Untuk sebuah kampanye, buatlah di dashboard atau panggil /notifications/campaignslalu kirim ke ID eksternal, tag, segment, atau audiens siaran.

10. Atur Badge

await CapgoNotifications.setBadge(4)
await CapgoNotifications.incrementBadge()
await CapgoNotifications.clearBadge()

Dari backend Anda:

curl -X POST 'https://api.capgo.app/notifications/badge' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: CAPGO_API_KEY' \
  -d '{
    "appId": "com.example.app",
    "target": { "externalId": "customer-user-123" },
    "badge": 4
  }'

11. Aktifkan Periksa Pembaruan Diam

Pemeriksaan pembaruan diam menghubungkan plugin ini dengan @capgo/capacitor-updater.

Dalam aplikasi:

await CapgoNotifications.enableUpdaterIntegration({
  enabled: true,
  installMode: 'next',
})

Dalam Capgo, aktifkan Push update ke pengguna di pengaturan Notifikasi aplikasi. Kemudian kirimkan periksa update dari dashboard atau API:

curl -X POST 'https://api.capgo.app/notifications/update-check' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: CAPGO_API_KEY' \
  -d '{
    "appId": "com.example.app",
    "target": { "externalId": "customer-user-123" },
    "installMode": "next"
  }'

Pemberitahuan ini diam dan menggunakan ID collapse sehingga periksa update berulang menggantikan satu sama lain ketika platform mendukung perilaku collapse.

Daftar Pengecekan Validasi

• Aplikasi muncul dalam Capgo pencarian penerima untuk yang diharapkan externalId.
• Izin adalah granted atau pengguna telah menerima izin pemberitahuan.
• Platform yang terdaftar adalah android atau ios.
• registrationChanged Platform yang terdaftar adalah atau
• mengalami pembaruan token. notificationReceived.
• Aplikasi uji di depan mengalami notificationOpened.
• Statistik dashboard menampilkan event yang antri dan dikirim, kemudian diterima/buka ketika perangkat melaporkannya.
• Periksa update diam log sebuah hasil dari runUpdateCheck Pengecekan pembaruan diam mengalami

atau integrasi pembaruan.

Bagian berjudul “Teruskan dari Getting Started” Debugging before changing app code. Most failures are caused by identity proof mismatch, platform credential setup, OS permission state, background throttling, or app/package ID mismatch.