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 pengecekan pembaruan 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 proyek 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.

Penginstalan 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 meletakkan kunci Capgo API Anda di aplikasi seluler. 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: HTML fragment teks dari string Capgo UI yang lebih panjang (kunci induk `appflow_migration_step2`). Halaman/area: Perbandingan/migrasi pemasaran Capflow / Appflow. Peran: Kalimat website. Dilihat di: halaman ionic-appflow.astro. Simpan Capgo produk/merek dan istilah pengembang secara tepat. Kunci pesan `appflow_migration_step2` (Langkah 2 Migrasi Appflow).

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

Aplikasi belum memperbarui pendaftaran 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 pemberitahuan 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. Kunci pesan `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)
}

Kemudian 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

Jalankan:

npx cap sync android

Kemudian verifikasi:

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

Buat saluran pemberitahuan 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 pemberitahuan Android push. Tahan cadangan aplikasi, ekstraksi data, keamanan jaringan, dan kebijakan ikon pemberitahuan di aplikasi host.

9. Kirim Pemberitahuan Uji

Pakai Pemberitahuan > 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/campaignskemudian 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:

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

Dalam Capgo, aktifkan Push update ke pengguna dalam pengaturan Notifikasi aplikasi. Kemudian, lakukan 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 penggabungan sehingga periksa update berulang menggantikan satu sama lain ketika platform mendukung perilaku penggabungan.

Daftar Pengecekan Validasi

• Aplikasi tersebut muncul dalam Capgo pencarian penerima untuk yang diharapkan externalId.
• Izin adalah granted atau pengguna telah menerima izin notifikasi.
• Platform yang terdaftar adalah android atau ios.
• registrationChanged atau pengguna telah menerima izin notifikasi.
• Platform yang terdaftar adalah notificationReceived.
• atau notificationOpened.
• atau pengguna telah menerima izin notifikasi.
• Platform yang terdaftar adalah runUpdateCheck atau

Event ini terjadi setelah token diperbarui.

Aplikasi latar belakang melakukan tes notifikasi pembukaan. Pengembangan sebelum mengubah aplikasi code. Banyak kesalahan disebabkan oleh kesalahan identitas, pengaturan kredensial platform, status izin sistem operasi, pengurangan kecepatan latar belakang, atau kesalahan ID aplikasi/paket.