Mulai Menggunakan

@capgo/capacitor-notifications adalah plugin pertama-tama Capgo untuk pemberitahuan push native iOS dan Android. Ini dibangun untuk Capgo’s dashboard, API publik, 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 pembuatan bukti backend 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 Credentials

Terbuka aplikasi di Capgo, kemudian pilih Notifications.

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

• Android ID aplikasi paket dan metadata proyek push Android.
• iOS ID paket, 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 ini menginstal paket notifikasi, menyimpan konfigurasi plugin Capacitor, membuat file bantuan kecil, dan menjalankan Capacitor sinkronisasi. Gunakan jalur ini untuk aplikasi baru kecuali Anda perlu menghubungkan setiap file secara manual.

Pemasangan 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',
})

Pilih 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 masukkan kunci Capgo API Anda ke dalam aplikasi mobile. Backend Anda harus meminta Capgo untuk 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"
  }'

Kembali dengan identityProof ke aplikasi dengan respons sesi Anda sendiri.

5. Mendaftarkan Perangkat

Daftarlah setelah Anda mengetahui pengguna pelanggan 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 perangkat push asli berubah.
• Token push native berubah.
• Pengguna yang masuk berubah.
• Aplikasi ini belum memperbarui registrasi dalam waktu lama.

Applikasi belum memperbarui pendaftaran dalam waktu lama.

Daftarkan pemangku jawab selama aplikasi startup sehingga event foreground, 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 pemberitahuan 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

Mengirimkan 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

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

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.
• Izin 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 layanan Google Play.

Buatkan 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 Coba

Gunakan Notifikasi > Kirim Uji Coba di Capgo, atau panggil fungsi publik API 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, 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 Perbarui Diam

Periksa perbarui diam menghubungkan plugin ini dengan @capgo/capacitor-updater.

Dalam aplikasi:

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

In Capgo, aktifkan Mengirimkan pembaruan ke pengguna di pengaturan Notifikasi aplikasi. Kemudian, lakukan periksa pembaruan 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 penggabungan sehingga periksa pembaruan yang berulang diganti dengan yang lain ketika platform mendukung perilaku penggabungan.

Daftar Periksa Validasi

• Aplikasi muncul di Capgo pencarian penerima untuk yang diharapkan externalId.
• Izin adalah granted atau pengguna telah menerima izin pemberitahuan.
• Platform yang terdaftar adalah android atau ios.
• registrationChanged terjadi setelah token diperbarui.
• Sebuah tes latar depan merekam notificationReceived.
• Membuka sebuah peringatan merekam notificationOpened.
• Statistik dashboard menampilkan event yang antri dan dikirim, kemudian diterima/buka ketika perangkat melaporkannya.
• Periksa pembaruan diam log hasil dari runUpdateCheck atau integrasi pembarui.

Teruskan dari Getting Started

Jika pengaturan tidak berfungsi, gunakan Pengembangan sebelum mengubah aplikasi code. Banyak kegagalan disebabkan oleh kesalahan bukti identitas, pengaturan kredensial platform, status izin sistem, pengurangan latar belakang, atau kesalahan ID aplikasi/paket.