Inizia a utilizzare

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

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 di backend e invio di API.
• Autorità 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 del Capgo della piattaforma.

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

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

• Android - ID del pacchetto dell'app e i metadati del progetto di push di Android.
• iOS - ID della bundle, ID del team, ID della chiave e i metadati della chiave di push iOS corrispondenti.

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

2. Installa

Per una configurazione più veloce, esegui il Capgo CLI dal progetto del tuo'applicazione:

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 Capgo silenziosi, puoi omettere @capgo/capacitor-updater.

3. Configura Il Plugin

Configura il plugin una volta che il tuo'applicazione si avvia.

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 alla prossima riavvio o ciclo di background. Usa updateInstallMode: 'set' solo quando desideri Capgo installare l'aggiornamento non appena il sincronizzatore può farlo in modo sicuro.

4. Crea un Prova di Identità

Non inserire il tuo Capgo API chiave nel mobile app. 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'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)

Chiamata register context

• Chiamalo di nuovo quando:
• L'applicazione si avvia.
• Il token di push nativo cambia.
• L'utente connesso cambia.
• Mutano i tag, gli attributi o il consenso.

L'applicazione non ha rinnovato la registrazione da molto tempo. 6. Aggiungi Eventi di Ascolto

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

Esegui quindi:

npx cap sync ios

Utilizza 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 su Android 13+ avviene prima di attendere notifiche visibili.
• La tua app ha un'icona e una strategia di canale di notifiche che corrisponde al tuo marchio.
• Testa l'app su un dispositivo fisico o su un emulatore con Google Play services.

Creare un canale di notifiche Android di default quando l'app si avvia:

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 di Android. Mantieni la politica di backup dell'app, l'estrazione dei dati, la sicurezza della rete e la politica dell'icona di notifica nel'app host.

9. Invia una Notifica di Test

Usa Notifiche > Invia una notifica 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 un nuovo elemento nel pannello di controllo o chiamalo /notifications/campaigns, quindi invia a un ID esterno, un tag, un segmento o un pubblico di messaggi 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

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

In l'applicazione:

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

Abilita in Capgo Invia un aggiornamento ai utenti in le impostazioni delle notifiche dell'applicazione. Poi invia un controllo degli aggiornamenti dal pannello di controllo 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 le ripetute verifiche degli aggiornamenti quando il sistema supporta il comportamento di crollo.

Elenco di controllo di validazione

• L'applicazione appare in Capgo per la ricerca dei destinatari previsti. externalId.
• La permessione è granted o il l'utente ha accettato la permesssione delle notifiche.
• La piattaforma registrata è android o ios.
• registrationChanged o il dispositivo ha accettato la permesssione delle notifiche.
• Le alternative per l'aggiornamento in tempo reale di Capacitor sono notificationReceived.
• Si verifica dopo un aggiornamento del token. notificationOpened.
• Un test in primo piano registra
• L'apertura di una notifica registra runUpdateCheck I dati del dashboard mostrano gli eventi in coda e inviati, poi ricevuti/aperti quando il dispositivo li segnala.

Le verifiche di aggiornamento silenziose registrano un risultato da

Continua da qui per Iniziare a utilizzare Capgo. Debugging prima di modificare l'app code. La maggior parte degli errori è causata da disaccordo di identità, configurazione delle credenziali della piattaforma, stato delle autorizzazioni del sistema, rallentamento del background, o disaccordo dell'ID dell'app/pacco.