Getting Started

@capgo/capacitor-notifications ist das erste Plugin von Capgo für native iOS- und Android-Benachrichtigungen. Es wurde für Capgo’s Dashboard, öffentliche API, Analytics Engine Geräteverzeichnis, Kampagnenstatistiken, Badge-Updates und stille Live-Update-Überprüfungen erstellt.

Der Paket ist derzeit in privater Vorabansicht. Capgo muss die Paketzugriff für Ihr npm-Konto aktivieren, bevor der Installationsbefehl funktioniert.

Anforderungen

• Ein Capacitor-App, die bereits in Capgo hinzugefügt wurde.
• Zugriff auf die Capgo-App-Benachrichtigungsoption.
• Ein Capgo- API-Schlüssel mit Schreibzugriff für den Hintergrundbeweis und API-Sendungen.
• iOS- und/oder Android-Plattform-Benachrichtigungsbefugnis für die App.
• @capgo/capacitor-updater Wenn Sie stille Benachrichtigungsoberprüfungen wünschen.

1. Konfigurieren Sie Capgo-Plattformzertifikate

Öffnen Sie die App in Capgo, dann gehen Sie zu Benachrichtigungen.

Fügen Sie ein Plattformzertifikatseingabe für jede Plattform hinzu, die Sie unterstützen möchten:

• Android - App-Paket-ID und Android-Push-Projektmetadaten.
• iOS - Bundle-ID, Team-ID, Schlüssel-ID und das entsprechende iOS-Push-Schlüsselmetadaten.

Capgo zeigt den genauen Umgebungsgeheimnissnamen an, der in der API-Arbeitsumgebung vor der Plattformmarkierung als konfiguriert existieren muss. Die Dashboard speichert Metadaten und die erwartete Geheimnissreferenz. Das private Zertifikat bleibt in der Arbeitsumgebung.

2. Installieren

Für die schnellste Einrichtung führen Sie den Capgo CLI in Ihrem App-Projekt aus:

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

Die Kommandozeile installiert das Benachrichtigungspaket, speichert die Capacitor-Plugin-Konfiguration, erstellt eine kleine Hilfsdatei und führt Capacitor-Sync durch. Verwenden Sie diesen Pfad für neue Apps, es sei denn, Sie müssen jede Datei manuell verdrahten.

Manuelles Installieren:

npm install @capgo/capacitor-notifications @capgo/capacitor-updater
npx cap sync

Wenn Sie keine stummen Capgo-Update-Überprüfungen verwenden, können Sie den Teil @capgo/capacitor-updater.

3. Die Plugin-Konfiguration

Konfigurieren Sie das Plugin einmal, wenn Ihre App startet.

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

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

Verwenden updateInstallMode: 'next' um ein Update herunterzuladen und es bei der nächsten Neustart- oder Hintergrundwiederholung zu installieren. Verwenden Sie updateInstallMode: 'set' nur, wenn Sie möchten, dass Capgo das Update so schnell wie möglich installiert, wenn der Updater es sicher tun kann.

4. Eine Identitätsbeweis erstellen

Legen Sie Ihr Capgo API-Schlüssel nicht in der mobilen App ein. Ihr Backend sollte sich bei Capgo nach einem identityProof nachdem Ihre 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"
  }'

Zurückgeben identityProof zurück zur App mit Ihrer eigenen Sitzungsnachricht.

5. Das Gerät registrieren

Registrieren Sie sich nur, wenn Sie wissen, welcher Kundenbenutzer 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)

Anrufen register wiederholen Sie dies, wenn:

• Die App startet.
• Der native Push-Token ändert sich.
• Der angemeldete Benutzer ändert sich.
• Tags, Attribute oder der Zustimmung ändern sich.
• Die App hat sich seit einer langen Zeit nicht neu registriert.

6. Ereignis-Listener hinzufügen

Registrieren Sie Listener während der App-Start, damit Vordergrund-, geöffnete und Hintergrundereignisse 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 Hintergrundbenachrichtigungen, nachdem Ihre Arbeit erledigt ist. Halten Sie die Arbeit kurz und idempotent.

7. iOS-Einrichtung

In Xcode öffnen Sie das App-Ziel und aktivieren Sie:

• Push-Benachrichtigungen
• Hintergrundmodi > Remote-Benachrichtigungen

Richten Sie Remote-Benachrichtigungen 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)
}

Dann ausführen:

npx cap sync ios

Verwenden Sie bei der Testung von Hintergrundbenachrichtigungen ein physisches iOS-Gerät. Simulatoren sind für die UI-Arbeit nützlich, stellen aber die Produktionshintergrundpush-Verhaltens nicht dar.

8. Android-Einrichtung

Run:

npx cap sync android

Dann überprüfen Sie:

• Ihre Android-Plattformkredenziale sind in Capgo. konfiguriert.
• Die App-Paket-ID entspricht der Paket-ID, die für die Plattform-Push-Einrichtung verwendet wird.
• Bei Android 13+ wird vor der Erwartung sichtbarer Benachrichtigungen die Benachrichtigungs-Erlaubnis angefordert.
• Die App verfügt über eine Benachrichtigungsikon- und Kanalstrategie, die Ihren Markenwert widerspiegelt.
• You testen auf einem physischen Gerät oder einem Emulator mit Google Play-Diensten.

Erstelle eine Standardkanal für Android, 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-Meldungsdienst. Halte die App-Backup, Datenextraktion, Netzwerksicherheit und Benachrichtigungs-Icon-Politik im Host-App.

9. Eine Testbenachrichtigung senden

Verwende Benachrichtigungen > Test senden auf Capgo oder rufe die öffentliche API von deinem Backend 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" }
    }
  }'

Für eine Kampagne erstelle sie im Dashboard oder rufe sie auf /notifications/campaigns Dann senden Sie es an einen externen ID, Tag, Segment oder Broadcast-Zielgruppe.

10. Abzeichen einrichten

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

Von Ihrem 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. Stille Aktualisierungsprüfungen aktivieren

Stille Aktualisierungsprüfungen verbinden dieses Plugin mit @capgo/capacitor-updater.

Im App:

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

In Capgo, aktivieren Sie Push-Update an die Benutzer im Benachrichtigungs-Settings des Apps. Dann senden Sie einen Update-Check von der Konsole 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 stumm und verwendet eine Collapse-ID, sodass wiederholte Update-Checks sich gegenseitig ersetzen, wenn die Plattform Collapse-Verhalten unterstützt.

Validierung-Checkliste

• Die App erscheint in Capgo Empfänger-Überprüfung für die erwartete externalId.
• Die Berechtigung ist granted oder der Benutzer hat die Benachrichtigungs-Berechtigung akzeptiert.
• Die registrierte Plattform ist android oder nach einem Token-Refresh ausgelöst wird. ios.
• registrationChanged Ein Hintergrundtest protokolliert
• Ein Benachrichtigungs-Test protokolliert notificationReceived.
• Die Dashboard-Statistiken zeigen an, welche Ereignisse in der Warteschleife sind und welche gesendet wurden, dann erhalten/eröffnet, wenn das Gerät sie meldet. notificationOpened.
• Stille Aktualisierungsprüfungen protokollieren einen Ergebnis von
• oder die Updater-Integration. runUpdateCheck Weitermachen von Getting Started

Abschnitt mit dem Titel “Weitermachen von Getting Started”

Fehlersuche Bevor Sie die App __CAPGO_KEEP_0__ ändern, führen Sie before changing app code. Most failures are caused by identity proof mismatch, platform credential setup, OS permission state, background throttling, or app/package ID mismatch.