Getting Started

@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 registri perangkat, statistik kampanye, pembaruan badge, dan periksa update hidup diam.

Persyaratan

• Aplikasi Capacitor sudah ditambahkan ke Capgo.
• Akses ke tab Pemberitahuan aplikasi Capgo.
• Aplikasi Capgo API 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 memeriksa pembaruan push secara diam-diam.

1. Konfigurasi Capgo Kredensial Platform

Buka aplikasi di Capgo, kemudian pilih Pemberitahuan.

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

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

Capgo menampilkan nama rahasia lingkungan yang tepat yang harus ada di pekerjaan API sebelum platform ditandai sebagai terkonfigurasi. Dashboard menyimpan metadata dan referensi rahasia yang diharapkan. Kredensial pribadi sendiri tetap berada di lingkungan pekerjaan.

2. Pasang

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.

Instal manual:

npm install @capgo/capacitor-notifications @capgo/capacitor-updater
npx cap sync

Jika Anda tidak menggunakan periksa pembaruan 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',
})

Pakai updateInstallMode: 'next' untuk mendownload pembaruan dan menginstalnya pada siklus latar belakang atau siklus restart berikutnya. Pakai updateInstallMode: 'set' hanya ketika Anda ingin Capgo menginstal pembaruan segera setelah pembaruan dapat dilakukan dengan aman.

4. Membuat Bukti Identitas

Jangan masukkan Capgo API kunci 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"
  }'

Kembalikan identityProof ke aplikasi dengan respons sesi Anda sendiri.

5. Daftarkan 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 kembali ketika:
• Applikasi dimulai.
• Token push native berubah.
• Pengguna yang masuk berubah.
• Tag, atribut, atau persetujuan berubah.

Applikasi belum memperbarui registrasi selama waktu lama.

Daftarkan pemangku peristiwa selama aplikasi startup agar peristiwa latar depan, dibuka, dan latar belakang 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 notifikasi latar belakang setelah pekerjaan Anda selesai. Pastikan pekerjaan singkat dan idempoten.

7. Pengaturan iOS

Dalam Xcode, buka target aplikasi dan aktifkan:

• Pemberitahuan Push
• context: Halaman/area: Situs web pemasaran Capgo. Peran: Label UI singkat atau item navigasi. Kunci pesan `push_notifications` (Pemberitahuan Push).

Latar Belakang > Pemberitahuan Jarak Jauh 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:

npx cap sync ios

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

8. Pengaturan Android

Lalu verifikasi:

npx 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 Anda memiliki ikon notifikasi dan strategi saluran yang sesuai dengan merek Anda.
• Anda melakukan pengujian pada perangkat fisik atau emulator dengan layanan Google Play.

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 menyatakan layanan pesan push Android. Simpan cadangan aplikasi, ekstraksi data, keamanan jaringan, dan kebijakan ikon notifikasi di aplikasi host.

9. Kirim Notifikasi Uji

Gunakan Notifikasi > Kirim Uji dalam 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/campaigns, kemudian 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.

Aplikasi ini:

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 ini muncul dalam Capgo pencarian penerima untuk yang diharapkan externalId.
• Izin adalah granted atau pengguna telah menerima izin notifikasi.
• The registered platform is android atau ios.
• registrationChanged atau pengguna telah menerima izin notifikasi.
• Perangkat lunak yang terdaftar adalah notificationReceived.
• atau notificationOpened.
• atau pengguna telah menerima izin notifikasi.
• Perangkat lunak yang terdaftar adalah runUpdateCheck atau pengguna telah menerima izin notifikasi.

Perangkat lunak yang terdaftar adalah

Perangkat lunak yang terdaftar adalah untuk memeriksa pembaruan secara diam-diam dan merekam hasilnya dari Mengembangkan sebelum mengubah aplikasi code. Banyak kesalahan disebabkan oleh kesalahan identitas, pengaturan kredensial platform, status izin sistem, pengurangan kecepatan latar belakang, atau kesalahan ID aplikasi/paket.