Per iniziare

@capgo/capacitor-notifications è il plugin Capgo ufficiale per le notifiche push native su iOS e Android. È progettato per la dashboard di Capgo, l'API pubblico, il device registry dell'Analytics Engine, le statistiche delle campagne, l'aggiornamento dei badge e i silent check di Capgo.

Requisiti

• Un'app Capacitor già aggiunta a Capgo.
• Accesso alla scheda Notifications dell'app Capgo.
• Una chiave API Capgo con permessi di scrittura per il backend proof minting e l'invio di API.
• Autorità push per la piattaforma iOS e/o Android dell'app.
• @capgo/capacitor-updater se desideri eseguire silent push update check.

Avvio rapido

import { CapacitorNotifications } from '@capgo/capacitor-notifications';
await CapacitorNotifications.register({ customerUserId: 'signed-id' });

Errori comuni

• Usa valori customerUserId firmati dal tuo backend.
• Richiedi il permesso per le notifiche prima di registrarle.
• Verifica le credenziali Capgo nella dashboard.

1. Configura le credenziali della piattaforma Capgo

Apri l'app in Capgo, quindi vai su Notifications.

Aggiungi una voce di credenziali per ogni piattaforma che vuoi supportare:

• Android - ID del pacchetto app e metadati del progetto push Android.
• iOS - bundle ID, team ID, key ID e i relativi metadati della chiave push iOS.

Capgo mostra il nome esatto del secret di ambiente che deve esistere nel worker API prima che la piattaforma risulti configurata. La dashboard memorizza i metadati e il riferimento al secret atteso. La credenziale privata resta nell'ambiente del worker.

2. Installazione

Per la configurazione più rapida, esegui Capgo CLI dal tuo progetto app:

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

Il comando installa il pacchetto notifiche, salva la config del plugin Capacitor, crea un piccolo file helper ed esegue la sync di Capacitor. Usa questo metodo per le nuove app, a meno che tu non debba configurare ogni file manualmente.

Installazione manuale:

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

Se non utilizzi i controlli silenziosi per Capgo, puoi omettere @capgo/capacitor-updater.

3. Configura il plugin

Configura il plugin all'avvio dell'app.

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

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

Usa updateInstallMode: 'next' per scaricare un aggiornamento e installarlo al prossimo riavvio o ciclo in background. Usa updateInstallMode: 'set' solo quando vuoi che Capgo installi l'aggiornamento non appena l'updater può farlo in sicurezza.

4. Genera un Identity Proof

Non inserire la chiave Capgo API nell'app mobile. Il tuo backend dovrebbe richiedere a Capgo un identityProof dopo che l'autenticazione dell'utente è andata a buon fine.

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 all'app insieme alla tua risposta di sessione.

5. Registra il dispositivo

Registra il dispositivo solo dopo aver identificato l'utente loggato.

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 si avvia.
• Il token push nativo cambia.
• L'utente loggato cambia.
• Cambiano tag, attributi o consensi.
• L'app non aggiorna la registrazione da molto tempo.

6. Aggiungi Event Listeners

Registra i listener all'avvio dell'app per rendere visibili a JavaScript gli eventi in foreground, opened e 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()
  }
})

Chiamare sempre finish() per le notifiche in background una volta terminato il lavoro. Mantieni l'operazione breve e idempotente.

7. Configurazione iOS

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

• Notifiche push
• Modalità in background > Notifiche remote

Inoltra le 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)
}

Poi esegui:

bunx cap sync ios

Usa un dispositivo iOS fisico per testare le notifiche in background. I simulatori sono utili per la UI, ma non replicano il comportamento reale dei push in background.

8. Configurazione Android

Esegui:

bunx cap sync android

Poi verifica che:

• Le tue credenziali della piattaforma Android siano configurate in Capgo.
• L'ID del pacchetto dell'app corrisponda all'ID usato per la configurazione push della piattaforma.
• Su Android 13+ è necessario richiedere il permesso per le notifiche prima di visualizzarle.
• L'app abbia un'icona per le notifiche e una strategia di canali coerenti con il tuo brand.
• Stai testando su un dispositivo fisico o su un emulatore con Google Play services.

Crea un canale Android predefinito all'avvio dell'app:

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

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

Il plugin dichiara il servizio di push messaging Android. Mantieni nell'app host il backup dell'app, l'estrazione dei dati, la sicurezza di rete e la policy delle icone di notifica.

9. Invia una notifica di test

Usa Notifiche > Invio test in Capgo, oppure chiama la API pubblica 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, creala nella dashboard o chiama /notifications/campaigns, per poi inviarlo a un ID esterno, un tag, un segmento o un pubblico broadcast.

10. Imposta i 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 i Silent Update Check

I Silent Update Check collegano questo plugin con @capgo/capacitor-updater.

Nell'app:

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

In Capgo, abilita Push update agli utenti nelle impostazioni Notifications dell'app. Poi invia un controllo aggiornamenti dalla dashboard o da 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 usa un collapse ID, così i controlli di aggiornamento ripetuti si sovrascrivono se la piattaforma supporta il collapse behavior.

Checklist di validazione

• L'app appare nella ricerca del destinatario Capgo per l'atteso externalId.
• Il permesso è granted o l'utente ha accettato il permesso per le notifiche.
• La piattaforma registrata è android o ios.
• registrationChanged viene eseguito dopo un refresh del token.
• Un test in foreground logga notificationReceived.
• Apertura dei log delle notifiche notificationOpened.
• Le statistiche della dashboard mostrano eventi in coda e inviati, poi ricevuti/aperti quando il dispositivo li segnala.
• Silent update checks log a result from runUpdateCheck o dall'integrazione dell'updater.

Continua da Getting Started

Se la configurazione non funziona, usa Debug prima di modificare code. La maggior parte dei problemi è causata da mismatch dell'identity proof, configurazione delle credenziali della piattaforma, permessi del sistema operativo, throttling in background o mismatch dell'ID app/package.