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, il pubblico API, l'engine di analisi dispositivo, i dati delle campagne, gli aggiornamenti della badge e le verifiche di aggiornamento live silenziose.

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 invio di API.
• L'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 del 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 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 sync. 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 rinnovatore può farlo in modo sicuro.

4. Crea un Prova di Identità

Non mettere il tuo Capgo API chiave nella 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'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

• Chiamare
• ancora quando:
• L'applicazione si avvia.
• Il token di push nativo cambia.
• L'utente connesso cambia.

Mutano tag, attributi o consenso.

Registra gli ascoltatori durante l'avvio dell'applicazione, in modo che gli eventi in primo piano, 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
• contexto: Pagina/area: Sito web di marketing Capgo. Ruolo: Etichetta di navigazione breve o elemento UI. Chiave del messaggio `push_notifications` (Notifiche Push).

Modalità di background > Notifiche remote 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 attendersi notifiche visibili.
• La tua app ha un'icona e una strategia di canale di notifiche che corrispondono al tuo marchio.
• Testa l'app su un dispositivo fisico o su un emulatore con Google Play services.

Creare un canale di notifiche Android predefinito 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 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 prova

Usa Notifiche > Invia una notifica di prova 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, crearla nel pannello di controllo o chiamala /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.

Nell'applicazione:

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

In Capgo, abilita Invia un aggiornamento ai utenti nella sezione Impostazioni delle notifiche dell'applicazione. Poi invia un controllo degli aggiornamenti 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'applicazione appare nel Capgo ricerca destinatari per l'atteso externalId.
• La permesssione è granted o il l'utente ha accettato la permesssione delle notifiche.
• La piattaforma registrata è android o ios.
• registrationChanged o
• si attiva dopo un aggiornamento del token. notificationReceived.
• Un test in primo piano registra notificationOpened.
• L'apertura di una notifica registra
• I dati del dashboard mostrano eventi in coda e inviati, poi ricevuti/aperti quando il dispositivo li segnala. runUpdateCheck Le verifiche di aggiornamento silenziose registrano un risultato da

o l'integrazione dell'aggiornatore.

Se la configurazione non funziona, utilizza Debugging prima di modificare l'app code. La maggior parte degli errori è causata da disaccordo di identità, configurazione delle credenziali del sistema, stato delle autorizzazioni del sistema operativo, rallentamento del background, o disaccordo dell'ID dell'app/pacco.