Mulai Dari Awal

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

Paket saat ini dalam pratinjau pribadi. Capgo harus mengaktifkan akses paket untuk akun npm Anda sebelum perintah instalasi berfungsi.

Persyaratan

• Aplikasi Capacitor sudah ditambahkan ke Capgo.
• Akses ke tab Pemberitahuan aplikasi Capgo.
• A Capgo API kunci dengan akses tulis untuk pembuatan bukti backend dan API mengirim.
• Otoritas push platform iOS dan/atau Android untuk aplikasi.
• @capgo/capacitor-updater jika Anda ingin periksa pembaruan push 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 dikonfigurasi. Dashboard menyimpan metadata dan referensi rahasia yang diharapkan. Kredensial pribadi sendiri tetap di lingkungan pekerjaan.

2. Pasang

Untuk setup 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:

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

Gunakan updateInstallMode: 'next' untuk mengunduh pembaruan dan menginstalnya pada siklus restart atau latar belakang berikutnya. Gunakan updateInstallMode: 'set' hanya ketika Anda ingin Capgo menginstal pembaruan segera setelah pembaruan dapat melakukannya 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"
  }'

Kembali ke identityProof ke aplikasi dengan respons sesi Anda sendiri.

5. Mendaftarkan Perangkat

Daftar setelah Anda mengetahui pengguna pelanggan yang sudah 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)

Tunggu panggilan register lagi ketika:

• Aplikasi mulai.
• Token push asli berubah.
• Pengguna yang sudah masuk berubah.
• Tag, atribut, atau persetujuan berubah.
• Aplikasi belum memperbarui pendaftaran selama waktu lama.

6. Tambahkan Pengguna Event

Daftarkan pengguna event selama aplikasi startup sehingga event 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 notifikasi latar belakang setelah pekerjaan Anda selesai. Jaga pekerjaan singkat dan idempoten.

7. Pengaturan iOS

Dalam Xcode, buka target aplikasi dan aktifkan:

• Notifikasi Push
• Modus Latar Belakang > Notifikasi Jarak Jauh

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

npx cap sync ios

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

8. Pengaturan Android

Jalankan:

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.
• Ijin pemberitahuan Android 13+ diminta sebelum menunggu pemberitahuan yang dapat dilihat.
• Aplikasi memiliki ikon pemberitahuan dan strategi saluran yang sesuai dengan merek Anda.
• Andai Anda ingin menguji aplikasi di perangkat fisik atau emulator dengan Google Play services.

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 mengumumkan 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 kampanye, buat di dashboard atau panggil __CAPGO_KEEP_0__ dari backend Anda: /notifications/campaignsMaka, kemudian kirimkan ke ID, tag, segment, atau audiens siaran luar.

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

Dalam Capgo, aktifkan Sampaikan 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 collapse sehingga periksa pembaruan yang berulang digantikan oleh yang lain ketika platform mendukung perilaku collapse.

Daftar Pemeriksaan Validasi

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

Teruskan dari Getting Started

Jika setup tidak berhasil, gunakan Mengatasi Masalah sebelum mengubah aplikasi code. Banyak kegagalan disebabkan oleh kesalahan bukti identitas, pengaturan kredensial platform, status izin OS, pengurangan latar belakang, atau kesalahan ID aplikasi/paket.