Getting Started

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

Anforderungen

• Eine Capacitor-App ist bereits in Capgo hinzugefügt.
• 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-Benachrichtigungsbehörde für die App.
• @capgo/capacitor-updater Wenn Sie stille Push-Update-Überprüfungen wünschen.

1. Konfigurieren Sie Capgo-Plattform-Zertifikate

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

Fügen Sie eine Plattform-Zugangsdaten-Eintrag 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 die zugehörige iOS-Push-Schlüsselmetadaten.

Capgo shows the exact environment secret name that must exist in the API worker before the platform is marked configured. The dashboard stores metadata and the expected secret reference. The private credential itself stays in the worker environment.

2. Installieren

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

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

Die Kommandozeile installiert die Benachrichtigungs-Paket, speichert die Capacitor-Einstellungen des Plugins, erstellt eine kleine Hilfsdatei und führt Capacitor synchron. Verwenden Sie diesen Pfad für neue Apps, es sei denn, Sie müssen jede Datei manuell verdrahten.

Manuelle Installation:

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

Wenn Sie keine stummen Capgo-Updateprüfungen verwenden, können Sie diesen Teil auslassen @capgo/capacitor-updater.

3. Das Plugin 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 updateInstallMode: 'next' ein Update herunterladen und es auf dem nächsten Neustart oder im Hintergrund zyklus installieren. updateInstallMode: 'set' nur dann, 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

Stellen Sie Ihr Capgo API-Schlüssel nicht in der mobilen App ein. Ihr Backend sollte sich bei Capgo für einen 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 an identityProof zurück zur App mit Ihrer eigenen Sitzungsnachricht.

5. 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)

Aufrufen register wieder, wenn:

• Wiederholen Sie dies, wenn:
• Der native Push-Token ändert sich.
• Der native Push-Token ändert sich.
• Der angemeldete Benutzer ändert sich.
• Die Tags, Attribute oder der Zustimmung ändern sich.

6. Ereignis-Listener hinzufügen

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

Stets aufrufen finish() für Hintergrundbenachrichtigungen nach Abschluss Ihrer Arbeit. Halten Sie die Arbeit kurz und idempotent.

7. iOS-Einrichtung

In Xcode öffnen Sie das Anwendungsziel und aktivieren Sie:

• Push-Benachrichtigungen
• Hintergrundmodi > Remote-Benachrichtigungen

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:

bunx cap sync ios

Verwenden Sie einen physischen iOS-Gerät, wenn Sie Hintergrundbenachrichtigungen testen. Simulatoren sind für UI-Arbeiten nützlich, stellen jedoch die Produktionshintergrundpush-Verhaltens nicht dar.

9. Android-Einrichtung

Laufen Sie:

bunx cap sync android

Dann überprüfen Sie:

• Ihr Android-Plattformkonto ist in Capgo konfiguriert.
• Die App-Paket-ID entspricht der Paket-ID, die für die Plattformpush-Einrichtung verwendet wird.
• Bei Android 13+ wird die Benachrichtigungs-Erlaubnis vor der Erwartung sichtbarer Benachrichtigungen angefordert.
• Die App verfügt über eine Benachrichtigungsikon- und Kanalstrategie, die Ihren Markenanspruch entspricht.
• Sie testen auf einem physischen Gerät oder einem Emulator mit Google Play-Diensten.

Erstellen Sie einen Standardkanal für Android, 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 den Android-Push-Messaging-Dienst. Behalten Sie die App-Backup-, Datenextraktion-, Netzwerksicherheits- und Benachrichtigungs-Icon-Politik im Host-App.

9. Eine Testbenachrichtigung senden

Use 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 es im Dashboard oder rufen Sie /notifications/campaigns, senden Sie dann an ein externes ID, Tag, Segment oder Broadcast-Publikum.

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 dieses Plugin mit @capgo/capacitor-updater.

In der App:

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

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

Überprüfungshinweis

• Die App erscheint im Capgo-Empfänger-Verzeichnis für den erwarteten externalId.
• Die Berechtigung ist granted oder der Benutzer hat die Benachrichtigungs-Berechtigung akzeptiert.
• Die registrierte Plattform ist android oder ios.
• registrationChanged nach einem Token-Refresh ausgelöst wird.
• Eine Vordergrund-Test-Protokollierung notificationReceived.
• Eine Benachrichtigung öffnen protokolliert notificationOpened.
• Dashboard stats show queued and sent events, then received/opened when the device reports them.
• Stille Aktualisierungsprüfungen loggen ein Ergebnis von runUpdateCheck oder die Updater-Integration.

Fortsetzen Sie von Getting Started

Wenn die Einrichtung nicht funktioniert, verwenden Sie Debugging bevor Sie die App code ändern. Die meisten Fehler werden durch Identitätsnachweismissverständnisse, Plattformzertifikatskonfiguration, Betriebssystemberechtigungen, Hintergrunddrosselung oder App/Paket-ID-Missverständnisse verursacht.