Iniziare

@capgo/capacitor-notifications è il plugin di prima parte Capgo per le notifiche push native iOS e Android. È costruito per il Capgo dashboard, il pubblico API, l'analisi del motore dispositivo, le statistiche delle campagne, gli aggiornamenti dei badge e le verifiche di aggiornamento silenzioso in tempo reale.

Il pacchetto è attualmente in anteprima privata. Capgo deve abilitare l'accesso al pacchetto per il tuo npm account prima che il comando di installazione funzioni.

Requisiti

• Un'app Capacitor già aggiunta a Capgo.
• L'accesso alla scheda delle notifiche dell'app Capgo.
• Una chiave Capgo API con accesso di scrittura per la convalida del backend e le API invio.
• L'autorità di push per la piattaforma iOS e/o Android dell'app.
• @capgo/capacitor-updater Se desideri verifiche di aggiornamento push silenziose.

1. Configura le credenziali Capgo della piattaforma

Apre l'app in Capgo, quindi vai a Notifiche.

Aggiungi un'ingresso delle credenziali della piattaforma per ogni piattaforma che desideri supportare:

• Android - ID del pacchetto dell'app e i metadati del progetto di push per Android.
• IOS - ID bundle, ID team, ID chiave e il matching chiave di push per iOS.

Capgo mostra il nome esatto del segreto dell'ambiente che deve esistere nel API worker prima che la piattaforma sia segnalata come configurata. La dashboard memorizza i metadati e la referenza del segreto attesa. Il credenziale privato rimane nell'ambiente del worker.

2. Installa

Per il setup più veloce, esegui il comando Capgo CLI dal progetto dell'app:

npx @capgo/cli@latest notifications setup com.example.app

Il comando installa il pacchetto di notifica, salva la configurazione del plugin Capacitor, crea un piccolo file di aiuto e esegue Capacitor sincronizzazione. Utilizza questo percorso per nuove app a meno che non debba collegare ogni file manualmente.

Installazione manuale:

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

Se non stai utilizzando gli aggiornamenti silenziosi Capgo, puoi omettere @capgo/capacitor-updater.

3. Configura il plugin

Configura il plugin una volta che il tuo app inizia.

import { CapgoNotifications } from '@capgo/capacitor-notifications'

await CapgoNotifications.configure({
  appId: 'com.example.app',
  autoUpdater: true,
  updateInstallMode: 'next',
})

Usa updateInstallMode: 'next' To scaricare un aggiornamento e installarlo al prossimo riavvio o ciclo di background. Utilizza updateInstallMode: 'set' solo quando desideri che Capgo installi l'aggiornamento non appena l'aggiornatore può farlo in modo sicuro.

4. Crea una prova di identità

Non inserire il tuo Capgo API chiave nel mobile app. Il tuo backend dovrebbe chiedere a Capgo un identityProof dopo che la tua autenticazione utente è riuscita.

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

Restituisci identityProof al'applicazione con la tua risposta di sessione.

5. Registra il dispositivo

Registra solo dopo aver saputo quale utente cliente è connesso.

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)

Chiama register nuovamente quando:

• L'app inizia.
• Il token di push nativo cambia.
• L'utente connesso cambia.
• I tag, gli attributi o il consenso cambiano.
• L'app non ha rinfrescato la registrazione da molto tempo.

6. Aggiungi Event Listeners

Registra gli ascoltatori durante l'avvio dell'app per rendere visibili agli script JavaScript gli eventi di foreground, aperti e di background.

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()
  }
})

Chiamalo sempre finish() per le notifiche in background dopo aver completato il lavoro. Tenere il lavoro breve e idempotente.

7. Configurazione iOS

In Xcode, apri il target dell'app e abilita:

• Notifiche Push
• Modalità di background > Notifiche remote

Inoltra notifiche remote da 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)
}

E quindi esegui:

npx cap sync ios

Usa un dispositivo iOS fisico per testare le notifiche in background. I simulator sono utili per il lavoro di interfaccia utente, ma non rappresentano il comportamento di push in background di produzione.

8. Configurazione Android

Esegui:

npx cap sync android

Verifica quindi:

• Il tuo credenziale della piattaforma Android è configurato in Capgo.
• L'ID del pacchetto dell'app corrisponde all'ID del pacchetto utilizzato per la configurazione di push della piattaforma.
• La richiesta di autorizzazione per le notifiche di Android 13+ avviene prima di attendere notifiche visibili.
• L'app ha un'icona delle notifiche e una strategia di canale che corrisponde al tuo marchio.
• Testa su un dispositivo fisico o emulatore con Google Play services.

Crea un canale Android di default quando l'app inizia:

await CapgoNotifications.configure({ appId: 'com.example.app' })

await CapgoNotifications.register({
  externalId: currentUser.id,
  identityProof: currentUser.capgoNotificationProof,
  consent: true,
})

Il plugin dichiara il servizio di messaggistica push Android. Mantieni la politica di backup dell'app, l'estrazione dei dati, la sicurezza della rete e la politica degli iconi delle notifiche nel host app.

9. Invia una Notifica di Test

Usa Notifiche > Invia di test in Capgo, o chiama il pubblico API dal tuo backend:

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

Per una campagna, crea una nel pannello di controllo o chiama /notifications/campaignsPoi invia a un ID esterno, un tag, un segmento o un pubblico di broadcast.

10. Imposta le badge

await CapgoNotifications.setBadge(4)
await CapgoNotifications.incrementBadge()
await CapgoNotifications.clearBadge()

Dal tuo backend:

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. Abilita le verifiche di aggiornamento silenziose

Le verifiche di aggiornamento silenziose connettono questo plugin con @capgo/capacitor-updater.

Nell'applicazione:

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

In Capgo, abilita Invia un aggiornamento agli utenti nella sezione Impostazioni delle notifiche dell'app. Poi invia un controllo di aggiornamento dalla dashboard o 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"
  }'

La notifica è silenziosa e utilizza un ID di crollo, quindi i controlli di aggiornamento si sostituiscono a vicenda quando il sistema supporta il comportamento del crollo.

Elenco di controllo di validazione

• L'app compare in Capgo ricerca destinatario per l'atteso externalId.
• La permessi sono granted o l'utente ha accettato la permessi di notifica.
• La piattaforma registrata è android o o avviene dopo un aggiornamento del token. ios.
• registrationChanged Un test in primo piano registra
• Aprire una notifica registra notificationReceived.
• Il dashboard mostra statistiche relative agli eventi in coda e inviati, poi ricevuti/aperti quando il dispositivo li segnala. notificationOpened.
• Le verifiche di aggiornamento silenziose registrano un risultato da
• o l'integrazione dell'aggiornatore. runUpdateCheck Continua da Getting Started

Sottosezione intitolata “Continua da Getting Started”

Debugging prima di modificare l'app __CAPGO_KEEP_0__. La maggior parte delle fallite è causata da disaccordo sulla prova di identità, configurazione delle credenziali del platform, stato delle autorizzazioni del sistema, rallentamento del background, o disaccordo sull'ID dell'app/pacco. before changing app code. Most failures are caused by identity proof mismatch, platform credential setup, OS permission state, background throttling, or app/package ID mismatch.