Panduan Memulai

@capgo/capacitor-notifications adalah plugin Capgo resmi untuk push notifications native iOS dan Android. Plugin ini dibuat khusus untuk dashboard Capgo, API publik, registry device Analytics Engine, statistik campaign, update badge, dan silent live-update checks.

Persyaratan

• Aplikasi Capacitor yang sudah ditambahkan ke Capgo.
• Akses ke tab Notifications pada aplikasi Capgo.
• Key API Capgo dengan akses write untuk backend proof minting dan pengiriman API.
• Otoritas push platform iOS dan/atau Android untuk aplikasi tersebut.
• @capgo/capacitor-updater jika Anda ingin melakukan silent push update checks.

Mulai cepat

import { CapacitorNotifications } from '@capgo/capacitor-notifications';
await CapacitorNotifications.register({ customerUserId: 'signed-id' });

Kesalahan umum

• Gunakan nilai customerUserId yang sudah ditandatangani dari backend Anda.
• Minta izin notifikasi sebelum melakukan registrasi.
• Verifikasi kredensial Capgo di dashboard.

1. Konfigurasi Kredensial Platform Capgo

Buka aplikasi di Capgo, lalu buka Notifikasi.

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

• Android - app package ID dan metadata proyek push Android.
• iOS - bundle ID, team ID, key ID, dan metadata key push iOS yang cocok.

Capgo menunjukkan nama persis secret environment yang harus ada di worker API sebelum platform ditandai terkonfigurasi. Dashboard menyimpan metadata dan referensi secret yang diharapkan. Kredensial privat itu sendiri tetap berada di environment worker.

2. Instal

Untuk setup tercepat, jalankan Capgo CLI dari proyek aplikasi Anda:

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

Perintah ini menginstal package notification, menyimpan konfigurasi plugin Capacitor, membuat file helper kecil, dan menjalankan Capacitor sync. Gunakan jalur ini untuk aplikasi baru kecuali Anda perlu menyambungkan setiap file secara manual.

Instalasi manual:

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

Jika Anda tidak memakai pengecekan update Capgo secara silent, Anda bisa melewati @capgo/capacitor-updater.

3. Konfigurasi Plugin

Konfigurasikan plugin sekali saat aplikasi Anda mulai.

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

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

Gunakan updateInstallMode: 'next' untuk mengunduh update dan menginstalnya pada restart atau siklus background berikutnya. Gunakan updateInstallMode: 'set' hanya jika Anda ingin Capgo menginstal update segera setelah updater bisa melakukannya dengan aman.

4. Buat Identity Proof

Jangan masukkan Capgo API key Anda ke dalam aplikasi mobile. Backend Anda harus meminta Capgo untuk identityProof setelah autentikasi user Anda 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"
  }'

Kembalikan identityProof ke aplikasi bersama dengan response session Anda.

5. Daftarkan Perangkat

Lakukan registrasi hanya setelah Anda tahu user mana yang sedang login.

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 lagi saat:

• Aplikasi dimulai.
• Native push token berubah.
• User yang login berubah.
• Tags, atribut, atau consent berubah.
• Aplikasi sudah lama tidak refresh registrasi.

6. Tambahkan Event Listeners

Daftarkan listener saat startup aplikasi agar event foreground, opened, dan background dapat diakses 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 notifikasi background setelah pekerjaan selesai. Pastikan prosesnya singkat dan idempotent.

7. Setup iOS

Di Xcode, buka target aplikasi dan aktifkan:

• Notifikasi Push
• Background Modes > Remote notifications

Teruskan notifikasi remote 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

Gunakan perangkat iOS fisik saat menguji notifikasi background. Simulator berguna untuk pekerjaan UI, tetapi tidak menggambarkan perilaku push background di produksi.

8. Setup Android

Jalankan:

bunx cap sync android

Kemudian verifikasi:

• Kredensial platform Android Anda sudah dikonfigurasi di Capgo.
• Package ID aplikasi sesuai dengan package ID yang digunakan untuk setup push platform.
• Izin notifikasi Android 13+ diminta sebelum mengharapkan notifikasi muncul.
• Aplikasi memiliki ikon notifikasi dan strategi channel yang sesuai dengan brand Anda.
• Anda melakukan pengujian pada perangkat fisik atau emulator dengan Google Play services.

Buat default Android channel saat aplikasi Anda dimulai:

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

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

Plugin ini mendeklarasikan layanan push messaging Android. Pastikan kebijakan backup app, ekstraksi data, keamanan jaringan, dan ikon notifikasi tetap ada di host app.

9. Kirim Notifikasi Tes

Gunakan Notifikasi > Tes kirim 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 kampanye, buat di dashboard atau panggil /notifications/campaigns, lalu kirim ke ID eksternal, tag, segmen, atau broadcast audience.

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 Silent Update Checks

Silent update checks menghubungkan plugin ini dengan @capgo/capacitor-updater.

Di dalam aplikasi:

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

Di Capgo, aktifkan Push update ke pengguna di pengaturan Notifications aplikasi. Lalu kirim update check 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"
  }'

Notifikasi ini bersifat senyap dan menggunakan collapse ID, sehingga pengecekan update yang berulang akan saling menggantikan jika platform mendukung perilaku collapse tersebut.

Checklist Validasi

• App muncul di Capgo lookup penerima yang diharapkan externalId.
• Izin adalah granted atau user telah menyetujui izin notifikasi.
• Platform yang terdaftar adalah android atau ios.
• registrationChanged terpicu setelah token refresh.
• Log test foreground notificationReceived.
• Membuka log notifikasi notificationOpened.
• Statistik dashboard menampilkan event yang antre dan terkirim, lalu diterima/dibuka saat perangkat melaporkannya.
• Log pengecekan silent update menunjukkan hasil dari runUpdateCheck atau integrasi updater.

Lanjutkan dari Getting Started

Jika setup tidak berhasil, gunakan Debugging sebelum mengubah code aplikasi. Kebanyakan kegagalan disebabkan oleh ketidakcocokan identity proof, setup kredensial platform, status izin OS, background throttling, atau ketidakcocokan app/package ID.