Getting Started

@capgo/capacitor-notifications è il plugin di prima parte Capgo per le notifiche push native iOS e Android. È costruito per Capgo's dashboard, pubblica API, motore di analisi dispositivo, statistiche campagna, aggiornamenti di badge e controlli di live-update silenziosi.

Requisiti

• Un'app Capacitor già aggiunta a Capgo.
• Accesso alla scheda Notifiche dell'app Capgo.
• Una chiave Capgo API con accesso di scrittura per la convalida back-end e le invio API.
• Autorevolezza di push per la piattaforma iOS e/o Android dell'app.
• @capgo/capacitor-updater Se desideri controlli di aggiornamento push silenziosi.

1. Configura le credenziali di piattaforma Capgo

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

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

• Android - ID pacchetto dell'app e 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 di ambiente che deve esistere nel worker API prima che la piattaforma sia segnalata come configurata. Il dashboard memorizza i metadati e la riferenza al segreto attesa. Il credenziale privato rimane nell'ambiente del worker.

2. Installa

Per la configurazione più veloce, esegui il comando Capgo CLI dal tuo progetto di 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:

bun add @capgo/capacitor-notifications @capgo/capacitor-updater
bunx cap sync

Se non stai utilizzando gli aggiornamenti Capgo silenziosi, 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' Scaricare un aggiornamento e installarlo alla prossima riavvio o ciclo di background. Utilizza updateInstallMode: 'set' Usa solo quando desideri che Capgo installi l'aggiornamento non appena l'aggiornatore può farlo in sicurezza.

4. Crea un Prova di Identità

Non inserisci il tuo Capgo API chiave nel'app mobile. Il tuo backend dovrebbe chiedere 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 il identityProof al'app con la tua risposta di sessione.

5. Registra il Dispositivo

Registrati 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)

Chiamare register context

• di nuovo quando:
• La applicazione inizia.
• Il token di push nativo cambia.
• Cambiamenti di tag, attributi o consenso.
• L'app non ha rinnovato la registrazione da molto tempo.

Aggiungi Ascoltatori di Eventi

Registra gli ascoltatori durante l'avvio dell'applicazione in modo che gli eventi di foreground, aperti e di background siano visibili al 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()
  }
})

Chiamalo sempre finish() per le notifiche in background dopo aver completato il lavoro. Mantieni 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)
}

Esegui quindi:

bunx cap sync ios

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

8. Configurazione Android

Esegui:

bunx cap sync android

Poi verifica:

• La tua credenziale di piattaforma Android è configurata in Capgo.
• The app package ID matches the package ID used for platform push setup.
• La richiesta di autorizzazione per le notifiche Android 13+ avviene prima di aspettarsi notifiche visibili.
• L'app ha un'icona delle notifiche e una strategia di canale che corrisponde al tuo marchio.
• Testa sul dispositivo fisico o emulatore con Google Play services.

Crea un canale Android di default quando il tuo 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, estrazione dei dati, sicurezza della rete e politica dei notifiche nel host app.

9. Invia una Notifica di Test

Usa Notifiche > Invia 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 il in dashboard o chiama /notifications/campaignsPoi invia a un pubblico esterno ID, tag, segmento o messaggio in onda.

10. Imposta le Badges

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

Aggiornamenti silenziosi di controllo collegano questo plugin a @capgo/capacitor-updater.

Nell'app:

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

In Capgo, abilita Invia un aggiornamento agli utenti in 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 per sostituire gli aggiornamenti ripetuti quando il sistema supporta il comportamento del crollo.

Elenco di controllo di validazione

• L'app compare nell'elenco dei destinatari di Capgo per l'aspettativa externalId.
• La permessione è granted o l'utente ha accettato la permessione delle notifiche.
• Il registro del sistema è android o ios.
• registrationChanged si si avviene un aggiornamento del token.
• Un test in primo piano registra notificationReceived.
• La registrazione di una notifica apre notificationOpened.
• Il dashboard mostra statistiche sulle eventi in coda e inviati, poi ricevuti/aperti quando il dispositivo li segnala.
• Silent update checks registrano un risultato da runUpdateCheck o l'integrazione dell'aggiornamento.

Keep going from Getting Started

Se la configurazione non funziona, utilizza Debugging prima di modificare l'app code. La maggior parte delle fallite è causata da disaccordo di prova di identità, configurazione di credenziali di piattaforma, stato di autorizzazione OS, rallentamento di background, o disaccordo di ID app/pacco.