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.

Anforderungen

• Eine Capacitor-App, die bereits in Capgo hinzugefügt wurde.
• Zugriff auf die Capgo-App-Benachrichtigungsoption.
• Eine Capgo- API-Schlüssel mit Schreibzugriff für den Hintergrundbeweis und API-Sendungen.
• iOS- und/oder Android-Plattform-Benachrichtigungsberechtigung 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 dem entsprechenden iOS-Push-Schlüssel-Metadaten.

Capgo zeigt den genauen Umgebungsgeheimnissnamen an, der in der API-Arbeitsumgebung vor der Plattform als konfiguriert markiert existieren 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 die Capgo CLI in Ihrem App-Projekt aus:

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

Der Befehl installiert die Benachrichtigungs-Paket, 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 dies auslassen @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 eine Aktualisierung herunterzuladen und sie auf dem nächsten Neustart oder Hintergrundzyklus zu installieren. Verwenden Sie updateInstallMode: 'set' nur, wenn Sie möchten, dass Capgo die Aktualisierung 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 an die 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:

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

6. Hinzufügen von Ereignis-Listenern

Registrieren Sie die Listener während der App-Startzeit, 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-Einrichtung

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

• Benachrichtigungen
• Bereich > 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 die UI-Arbeit, stellen aber die Produktionshintergrundpush-Verhaltensweise nicht dar.

8. Android-Einrichtung

Dann führen Sie aus:

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 Plattformpush-Einrichtung verwendet wird.
• Android 13+ Benachrichtigungsberechtigung wird vor der Erwartung sichtbarer Benachrichtigungen angefordert.
• Die App verfügt über eine Benachrichtigungssymbolik und einen Kanal-Strategie, die Ihrem Markenbild 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,
})

Der Plugin deklariert die Android-Push-Nachrichtendienste. Halten Sie die App-Backup, Datenextraktion, Netzwerksicherheit und Benachrichtigungssymbolik in der 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 sie auf /notifications/campaigns, senden Sie dann an einen externen ID, Tag, Segment oder eine Broadcast-Zielgruppe.

10. Abzeichen setzen

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 diese Erweiterung 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, damit wiederholte Update-Checks sich gegenseitig ersetzen, wenn die Plattform das Collaps-Verhalten unterstützt.

Validierungscheckliste

• Die App erscheint in Capgo Empfänger-Übersicht 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 Die Registrierung der Plattform ist erforderlich.
• Die Appflow-Registrierung ist erforderlich. notificationReceived.
• Die Capawesome-Registrierung ist erforderlich. notificationOpened.
• Die Registrierung ist erforderlich.
• Nach einer Token-Refresh-Aktion wird dieser Ereignis-Typ ausgelöst. runUpdateCheck Eine Vordergrund-Test-Log-Ereignis wird ausgelöst.

Eine Benachrichtigung-Öffnen-Log-Ereignis wird ausgelöst.

Ein stummer Update-Check logt einen Ergebnis von Fehlersuche Bevor Sie die Anwendung code ändern, stellen Sie sicher, dass die meisten Fehler durch Identitätsnachweismissmatch, Plattformzertifikatskonfiguration, Betriebssystemrechte, Hintergrunddrosselung oder Anwendungs-/Paket-ID-Missmatch verursacht werden.