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

• Eine Capacitor-App, die bereits in Capgo hinzugefügt wurde.
• Zugriff auf die Capgo-App-Benachrichtigungsseite.
• Eine 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 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 Worker vor der Plattform als konfiguriert markiert werden muss. Das Dashboard speichert Metadaten und den erwarteten Geheimnissverweis. Das private Konto bleibt sich in der Worker-Umgebung.

2. Installieren

Für die schnellste Einrichtung führen Sie bitte 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-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 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 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"
  }'

Rückgabe des 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-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 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:

• 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 Folgendes 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 jedoch die Produktionshintergrundpush-Verhaltens nicht dar.

8. Android-Einrichtung

Dann führen Sie Folgendes 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-Erlaubnis für Android 13+ wird vor der Erwartung sichtbarer Benachrichtigungen angefordert.
• Die App verfügt über eine Benachrichtigungs-Icon- und Kanalstrategie, 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,
})

Das Plugin deklariert die Android-Push-Nachrichtendienste. Halten Sie die App-Backup, Datenextraktion, Netzwerksicherheit und Benachrichtigungs-Icon-Politik im Host-App.

9. Eine Testbenachrichtigung senden

Verwenden Sie Benachrichtigungen > Test senden im 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 eine externe ID, ein Etikett, ein Segment oder eine Broadcast-Zielgruppe.

10. 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 diese 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, damit 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 die Benutzer haben die Benachrichtigungs-Erlaubnis angenommen.
• Die registrierte Plattform ist android oder ios.
• registrationChanged Nach einer Token-Refresh wird das Ereignis ausgelöst.
• Ein Hintergrundtest protokolliert notificationReceived.
• Ein Benachrichtigung öffnen protokolliert notificationOpened.
• Das Dashboard zeigt die angehaltenen und gesendeten Ereignisse, dann die erhaltenen/eröffneten, wenn das Gerät sie meldet.
• Stille Updates überprüfen protokollieren einen Ergebnis von runUpdateCheck oder die Updater-Integration.

Weitermachen Sie von Getting Started

Wenn die Einrichtung nicht funktioniert, verwenden Sie Fehlersuche Bevor Sie die code-Anwendung ändern. Die meisten Fehler werden durch Identitätsnachweismissmatch, Plattformzertifikatskonfiguration, Betriebssystemrechte, Hintergrunddrosselung oder App/Paket-ID-Missmatch verursacht.