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'analisi del motore dispositivo, i dati delle campagne, gli aggiornamenti della badge e le verifiche silenziose degli aggiornamenti 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 del backend e le invio 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.

Apri 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 worker API prima che la piattaforma venga 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 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:

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 la tua app 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 relativo aggiornatore può farlo in sicurezza.

4. Prova un'identità

Non inserisci 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 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)

Chiamare register context

• Chiamare nuovamente quando:
• La applicazione inizia.
• Il token di push nativo cambia.
• L'utente connesso cambia.
• Mutano le etichette, gli attributi o il consenso.

La applicazione non ha rinnovato la registrazione da molto tempo.

Registra gli ascoltatori durante l'avvio dell'applicazione affinché 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
• context: 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)
}

Quindi esegui:

npx cap sync ios

Utilizza 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:

npx cap sync android

Quindi verifica:

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

Creare un canale di notifiche Android predefinito 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 icona di notifica nel tuo 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, 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 gli Aggiornamenti Silenziosi

Gli aggiornamenti silenziosi connettono questo plugin con @capgo/capacitor-updater.

Nell'applicazione:

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

In Capgo, abilita Invia un aggiornamento ai utenti nelle 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 gli aggiornamenti ripetuti quando il sistema supporta il comportamento di crollo.

Elenco di controllo di validazione

• L'applicazione appare in Capgo ricerca dei destinatari per il previsto externalId.
• La permessione è granted o il l'utente ha accettato la richiesta di notifica.
• La piattaforma registrata è android o ios.
• registrationChanged o l'utente ha accettato la richiesta di notifica.
• La piattaforma registrata è notificationReceived.
• o notificationOpened.
• La piattaforma registrata è
• La piattaforma registrata è runUpdateCheck La piattaforma registrata è

La piattaforma registrata è

La piattaforma registrata è o l'aggiornamento del token si verifica dopo un rinnovo del token. Un test in primo piano registra Duplicazione prima di modificare l'app code. La maggior parte degli errori è causata da disaccordo sulla prova di identità, configurazione delle credenziali del sistema, stato delle autorizzazioni del sistema operativo, rallentamento del background, o disaccordo sull'ID dell'app/pacco.