Einführung

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

Anforderungen

• Ein Capacitor-App, die bereits in Capgo hinzugefügt wurde.
• Zugriff auf die Capgo-App-Benachrichtigungsseite.
• Ein Capgo- API-Schlüssel mit Schreibzugriff für die Hintergrundbeweis-Prüfung und API-Sendungen.
• iOS- und/oder Android-Plattform-Benachrichtigungsbehörde für die App.
• @capgo/capacitor-updater Wenn Sie stille Push-Update-Überprüfungen wünschen.

1. Konfigurieren Sie Capgo Plattformkredenziale.

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

Fügen Sie eine Plattformkredenzial-Eintrag für jede Plattform hinzu, die Sie unterstützen möchten:

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

Capgo zeigt den genauen Umgebungsgeheimnissnamen an, der in der API-Arbeitsumgebung vor der Plattform als konfiguriert markiert werden muss. Die Dashboard speichert Metadaten und den erwarteten Geheimnissverweis. Das private Konto 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

Der Befehl installiert das Benachrichtigungs-Paket, speichert die Capacitor-Einstellungen des Plugins, 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 anbinden.

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 ignorieren @capgo/capacitor-updater.

3. Die Plugin-Konfiguration konfigurieren

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 Sie updateInstallMode: 'next' um ein Update herunterzuladen und es auf dem nächsten Neustart oder Hintergrundzyklus 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. Identitätsnachweis erstellen

Stellen Sie Ihr Capgo API-Sicherheitszertifikat 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"
  }'

Geben Sie den identityProof zurück zur App mit Ihrer eigenen Sitzungsnachricht.

5. Registrieren Sie das Gerät

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)

Aufrufen register erst wieder, wenn:

• Die App startet.
• Der native Push-Token ändert sich.
• Der angemeldete Benutzer ändert sich.
• Die Tags, Attribute oder der Zustimmung ändern sich.
• Die App hat die Registrierung seit langer Zeit nicht aktualisiert.

6. Hinzufügen von Ereignis-Listen

Registrieren Sie die Listener während der Anwendungsstart, 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()
  }
})

Rufen Sie immer nach der Arbeit an finish() für Hintergrundbenachrichtigungen auf, nachdem Ihre Arbeit abgeschlossen ist. Halten Sie die Arbeit kurz und idempotent.

7. iOS-Einstellungen

In Xcode öffnen Sie das Anwendungsziel und aktivieren Sie:

• Push-Benachrichtigungen
• Hintergrundmodi > Remote-Benachrichtigungen

Senden 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 führen Sie aus:

npx cap sync ios

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

8. Android-Einrichtung

Dann führen Sie aus:

npx cap sync android

Dann überprüfen Sie:

• Ihre Android-Plattformkredenzial sind in Capgo konfiguriert.
• Die App-Paket-ID entspricht der Paket-ID, die für die Plattformpush-Einrichtung verwendet wird.
• Die Benachrichtigungs-Erweiterung für Android 13+ stellt die Benachrichtigungs-Erlaubnis vor der Erwartung sichtbarer Benachrichtigungen an.
• Die App verfügt über eine Benachrichtigungs-Icon-Strategie und einen Kanal, der Ihren Marken-Design entspricht.
• Sie testen auf einem physischen Gerät oder einem Emulator mit Google Play-Diensten.

Erstellen Sie einen Standard-Android-Kanal, wenn Ihre App startet:

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

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

Die Erweiterung deklariert die Android-Push-Messaging-Dienst. Halten Sie die App-Backup, Daten-Extraktion, Netzwerksicherheit und Benachrichtigungs-Icon-Politik im Host-App.

9. Eine Testbenachrichtigung senden

Verwenden Sie Benachrichtigungen > Test senden in Capgo, oder rufen Sie die öffentliche API von Ihrem 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 erstellen Sie sie entweder im Dashboard oder rufen sie auf /notifications/campaigns, dann senden Sie sie an einen externen ID, Tag, Segment oder Broadcast-Zielgruppe.

10. Anzeigen von Badges 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 Update-Überprüfungen aktivieren

Stille Update-Überprüfungen verbinden dieses Plugin mit @capgo/capacitor-updater.

In der App:

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

In Capgo, aktivieren Sie Push-Update an die Benutzer senden in den Benachrichtigungs-Einstellungen der App. 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 Collaps-ID, sodass wiederholte Update-Checks sich gegenseitig ersetzen, wenn die Plattform das Collaps-Verhalten unterstützt.

Validierungscheckliste

• Die App erscheint in Capgo-Empfänger-Überprüfung für das erwartete externalId.
• Die Berechtigung ist granted oder der Benutzer hat die Benachrichtigungs-Erlaubnis angenommen.
• Die registrierte Plattform ist android oder ios.
• registrationChanged Nach einer Token-Refresh-Aktion wird das Ereignis ausgelöst.
• Ein Hintergrundtest protokolliert notificationReceived.
• Ein Benachrichtigungs-Öffnen protokolliert notificationOpened.
• Die Dashboard-Statistiken zeigen an, wie viele Ereignisse in der Warteschleife sind und wie viele gesendet wurden, und dann, wenn das Gerät sie meldet, wie viele erhalten und geöffnet wurden.
• Stille Update-Überprüfungen protokollieren einen Ergebnis von runUpdateCheck oder der Updater-Integration.

Fahren Sie mit dem

Wenn die Einrichtung nicht funktioniert, verwenden Sie Fehlersuche Bevor Sie die App code ändern, sollten Sie sich über die häufigsten Fehlerquellen im Klaren sein. Die meisten Fehler werden durch Identitätsprüfungsmängel, Plattformzertifikatskonfiguration, Betriebssystemrechte, Hintergrundthrottling oder App-ID-Mängel verursacht.