Erste Schritte

@capgo/capacitor-notifications ist das First-Party-Plugin Capgo für native Push-Benachrichtigungen unter iOS und Android. Es ist für das Capgo-Dashboard, die öffentliche API, die Device Registry der Analytics Engine, Kampagnen-Stats, Badge-Updates und Silent-Live-Update-Checks gebaut.

Anforderungen

• Eine Capacitor App wurde bereits zu Capgo hinzugefügt.
• Zugriff auf den Notifications-Tab der Capgo-App.
• Ein Capgo API-Key mit Schreibzugriff für Backend-Proof-Minting und Sends über API.
• Push-Berechtigung für die App auf iOS und/oder Android.
• @capgo/capacitor-updater falls du Silent-Push-Update-Checks nutzen möchtest.

Quickstart

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

Häufige Stolperfallen

• Verwende signierte customerUserId-Werte von deinem Backend.
• Fordere die Benachrichtigungsberechtigung vor der Registrierung an.
• Überprüfe die Capgo Credentials im Dashboard.

1. Capgo Plattform-Credentials konfigurieren

Öffne die App in Capgo und gehe dann zu Benachrichtigungen.

Füge für jede zu unterstützende Plattform einen Credential-Eintrag hinzu:

• Android - App-Package-ID und Android-Push-Projektmetadaten.
• iOS - Bundle ID, Team ID, Key ID und die passenden iOS Push-Key-Metadaten.

Capgo zeigt den exakten Namen des Environment Secrets an, der im API Worker existieren muss, bevor die Plattform als konfiguriert gilt. Das Dashboard speichert die Metadaten und den erwarteten Secret-Referenzwert. Das private Credential selbst verbleibt in der Worker-Umgebung.

2. Installieren

Für das schnellste Setup führe den Capgo CLI in deinem App-Projekt aus:

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

Der Befehl installiert das Notification-Package, speichert die Capacitor Plugin-Config, erstellt eine kleine Helper-Datei und führt Capacitor sync aus. Nutze diesen Weg für neue Apps, außer du musst jede Datei manuell verknüpfen.

Manuelle Installation:

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

Wenn du keine Silent Capgo Update-Checks nutzt, kannst du diesen Schritt überspringen, @capgo/capacitor-updater.

3. Plugin konfigurieren

Konfiguriere das Plugin einmalig beim App-Start.

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

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

Nutzt updateInstallMode: 'next' um ein Update herunterzuladen und beim nächsten Neustart oder Background-Cycle zu installieren. Nutze dies updateInstallMode: 'set' nur wenn Capgo das Update sofort nach der sicheren Installation durch den Updater durchführen soll.

4. Identity Proof erstellen

Speichere deinen Capgo API Key niemals in der mobilen App. Dein Backend sollte Capgo nach einem identityProof sobald deine eigene Benutzerauthentifizierung erfolgreich war.

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"
  }'

Gib den identityProof zusammen mit deiner eigenen Session-Response an die App zurück.

5. Device registrieren

Registriere das Gerät erst, wenn feststeht, welcher Kunden-User angemeldet ist.

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)

Rufe register erneut, wenn:

• Die App startet.
• Der native Push-Token sich ändert.
• Der angemeldete User wechselt.
• Tags, Attribute oder Consent sich ändern.
• Die App die Registrierung lange nicht aktualisiert hat.

6. Event Listener hinzufügen

Registriere Listener beim App-Start, damit Foreground-, Opened- und Background-Events für JavaScript sichtbar sind.

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

Immer aufrufen finish() für Background-Notifications, nachdem deine Arbeit erledigt ist. Halte die Arbeit kurz und idempotent.

7. iOS-Setup

Öffne in Xcode das App-Target und aktiviere:

• Push-Benachrichtigungen
• Background-Modi > Remote-Benachrichtigungen

Remote-Benachrichtigungen weiterleiten von 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)
}

Führe dann aus:

bunx cap sync ios

Nutze für Tests von Background-Notifications ein physisches iOS-Gerät. Simulatoren sind für UI-Arbeit nützlich, bilden aber das Background-Push-Verhalten in Produktion nicht ab.

8. Android-Setup

Führe aus:

bunx cap sync android

Überprüfe anschließend:

• Deine Android-Plattform-Credentials sind in Capgo konfiguriert.
• Die App-Package-ID stimmt mit der Package-ID überein, die für das Plattform-Push-Setup verwendet wird.
• Die Benachrichtigungsberechtigung für Android 13+ wird angefordert, bevor sichtbare Benachrichtigungen erwartet werden können.
• Die App hat ein Benachrichtigungssymbol und eine Channel-Strategie, die zu deinem Branding passen.
• Du testest auf einem echten Gerät oder einem Emulator mit Google Play Services.

Erstelle einen Standard-Android-Channel, wenn deine App startet:

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

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

Das Plugin deklariert den Android Push-Messaging-Service. App-Backup, Datenextraktion, Netzwerksicherheit und Notification-Icon-Policy gehören weiterhin in die Host-App.

9. Test-Notification senden

Nutzt Benachrichtigungen > Testversand in Capgo, oder rufe die öffentliche API von deinem Backend aus auf:

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" }
    }
  }'

Erstelle eine Kampagne im Dashboard oder rufe /notifications/campaigns, und sende sie dann an eine externe ID, ein Tag, ein Segment oder eine Broadcast-Audience.

10. Badges setzen

await CapgoNotifications.setBadge(4)
await CapgoNotifications.incrementBadge()
await CapgoNotifications.clearBadge()

Von deinem Backend aus:

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. Silent Update Checks aktivieren

Silent Update Checks verbinden dieses Plugin mit @capgo/capacitor-updater.

In der App:

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

Aktiviere in Capgo Push-Updates an Nutzer senden in den Notifications-Einstellungen der App. Sende dann einen Update-Check über das Dashboard oder 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"
  }'

Die Benachrichtigung ist lautlos und nutzt eine Collapse-ID, sodass sich wiederholte Update-Checks gegenseitig ersetzen, sofern die Plattform Collapse-Verhalten unterstützt.

Validierungs-Checkliste

• Die App erscheint in der Capgo Empfänger-Suche für den erwarteten externalId.
• Berechtigung ist granted oder der Nutzer hat die Benachrichtigungsberechtigung akzeptiert.
• Die registrierte Plattform ist android oder ios.
• registrationChanged wird nach einem Token-Refresh ausgelöst.
• Ein Foreground-Test loggt notificationReceived.
• Notification-Logs öffnen notificationOpened.
• Dashboard-Stats zeigen wartende und gesendete Events, sowie empfangene/geöffnete, sobald das Gerät diese meldet.
• Silent Update Checks loggen Ergebnisse von runUpdateCheck oder der Updater-Integration.

Weiter geht's nach Getting Started

Falls das Setup nicht funktioniert, nutze Debugging bevor du die App code änderst. Die meisten Fehler entstehen durch Identity-Proof-Mismatch, Plattform-Credentials, OS-Berechtigungen, Background-Throttling oder App/Package-ID-Mismatch.