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 perangkat registry, 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 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 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 sync. Gunakan jalur ini untuk aplikasi baru kecuali Anda perlu menghubungkan setiap file secara manual.

Penginstalan manual:

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

Jika Anda tidak menggunakan periksa pembaruan Capgo secara diam-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 mendownload pembaruan dan menginstalnya pada siklus restart atau latar belakang berikutnya. Gunakan updateInstallMode: 'set' hanya ketika Anda ingin Capgo menginstal pembaruan segera setelah pembaruan dapat dilakukan dengan aman.

4. Membuat Bukti Identitas

Jangan memasukkan 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"
  }'

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:", Page/area: Perbandingan dan migrasi Appflow / iklan pemasaran. Peran: Kalimat website. Dilihat di: halaman ionic-appflow.astro. Simpan Capgo produk/merek dan istilah pengembang secara tepat. Kunci pesan `appflow_migration_step2` (Appflow Migration Step2).

• Panggil kembali ketika:
• Aplikasi dimulai.
• Token push native berubah.
• Pengguna yang masuk berubah.
• Tag, atribut, atau persetujuan berubah.

Aplikasi belum memperbarui registrasi selama waktu lama.

Daftarkan pemangku peristiwa 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. Pastikan pekerjaan singkat dan idempoten.

7. Pengaturan iOS

Dalam Xcode, buka target aplikasi dan aktifkan:

• Pemberitahuan Push
• context

Page/area: Situs web pemasaran Capgo. Peran: Label UI singkat atau item navigasi. Pesan kunci `push_notifications` (Pemberitahuan Push). 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 saat 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 notifikasi 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 di Capgo, atau panggil API yang terbuka 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.

Di aplikasi:

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

Di 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 diulang menggantikan satu sama lain ketika platform mendukung perilaku penggabungan.

Daftar Periksa Validasi

• Aplikasi tersebut muncul di Capgo pencarian penerima untuk yang diharapkan externalId.
• Izin yang diperlukan granted atau pengguna telah menerima izin pemberitahuan.
• The registered platform is android atau ios.
• registrationChanged atau pengguna telah menerima izin pemberitahuan.
• fires setelah refresh token. notificationReceived.
• A foreground test logs notificationOpened.
• Membuka pemberitahuan logs
• Dashboard statistik menampilkan event yang antri dan dikirim, kemudian diterima/buka ketika perangkat melaporkannya. runUpdateCheck Silent update checks log hasil dari

atau integrasi pembaruan.

Bagian berjudul “Teruskan dari Getting Started” Debugging sebelum mengubah aplikasi code. Banyak kegagalan disebabkan oleh kesalahan identitas, pengaturan kredensial platform, status izin sistem, pengurangan kecepatan latar, atau kesalahan ID aplikasi/paket.