@capgo/capacitor-notifications

Übersicht

@capgo/capacitor-notifications verbindet eine Capacitor App mit der nativen Notification-Pipeline von Capgo. Deine App registriert eine signierte Customer User ID bei Capgo, Capgo hält den aktuellen aktiven Gerätestatus in der Cloudflare Analytics Engine, und du kannst Notifications senden, Badges setzen, Zustellungsstatistiken prüfen und silent Capgo Live-Update-Checks über das Capgo Dashboard oder API auslösen.

Das Feature ist so ausgelegt, dass es eine High-Cardinality-Notification-Device-Tabelle in Capgo Postgres vermeidet. Postgres speichert nur Low-Cardinality-Control-Plane-Daten wie App-Einstellungen, Metadaten zu Plattform-Credentials, Kampagnen-Entwürfe, Zeitpläne und aggregierte Kampagnen-Datensätze. Aktiver Gerätestatus und Notification-Events sind Append-only-Zeilen in der Analytics Engine.

Plattformunterstützung

Plattform	Support	Notizen
iOS	Ja	APNs über Capgo
Android	Ja	FCM über Capgo
Web	Nein	Web Push separat nutzen

Was Capgo speichert

Daten	Speicherort	Warum
Metadaten der Plattform-Credentials	Capgo Postgres	Wird benötigt, um App-Setup und Berechtigungen zu verwalten.
Private Plattform-Secrets	Worker-Umgebung	Verhindert, dass private Credentials in kundenseitigen Tabellen gespeichert werden.
Kampagnenentwürfe und Einstellungen	Capgo Postgres	Control-Plane-Daten mit geringer Kardinalität.
Registrierungsstatus aktiver Geräte	Cloudflare Analytics Engine	Kostengünstiges, Append-only-Register für aktive Geräte.
Notification-Events	Cloudflare Analytics Engine	Günstige Stats für queued, sent, received, opened, failed und background Events.

Identity-Modell

Capgo verlangt weder den Upload einer Benutzerliste noch die Pflege einer Gerätetabelle.

• Dein Backend kennt die echte Customer User ID.
• Dein Backend fragt Capgo nach einem kurzlebigen identityProof.
• Die App registriert sich mit externalId und diesen Proof, nachdem deine eigene User-Authentifizierung erfolgreich war.
• Capgo leitet deterministische interne Keys für den Empfänger und die native Installation ab.
• Das Senden an denselben externalId findet die aktiven Devices des Users erneut.

Damit kannst du Geräte eines Nutzers nachschlagen, Badges setzen und Notification-Kampagnen targeten, ohne pro Gerät Notification-Zeilen in Capgo Postgres zu speichern.

Kernfunktionen

• Registriere Geräte mit einer authentifizierten externen User-ID.
• Aktualisiere Tags, Attribute, Consent und den Token-Status beim App-Start oder bei Token-Änderungen.
• Empfange Foreground-Notifications in JavaScript.
• Tracke Events für empfangene und geöffnete Notifications.
• Verarbeite Background-Data-Notifications.
• Setze, entferne und erhöhe App-Badges.
• Erstelle Android-Notification-Channels.
• Sende One-off-Notifications, Kampagnen-Notifications, Badge-Updates und Silent-Update-Checks.
• Auslösen @capgo/capacitor-updater aus einer Silent Notification.

Stats

Capgo schreibt Notification-Events in die Cloudflare Analytics Engine, damit die Dashboard-Stats kostengünstig bleiben:

• queued
• sent
• provider_accepted
• received
• opened
• failed
• permission_changed
• background_started
• background_finished

Stats sind operative Signale und kein dauerhaftes Protokoll pro Empfänger. Aufgrund der Retention der Analytics Engine müssen aktive Geräte die Registrierung regelmäßig aktualisieren.

Öffentliches API

Methode	Beschreibung
configure	Legt die Capgo App-ID, den API Host und das Verhalten der Updater-Integration fest.
register	Registriert die aktuelle Installation für eine externe Customer User ID.
setExternalId	Ändert die externe Customer User ID nach dem Login oder einem Account-Wechsel.
setTags	Ersetzt die Tags für das Audience Targeting.
setBadge	Setzt das Badge der nativen App.
clearBadge	Entfernt das Badge der nativen App.
incrementBadge	Erhöht das Badge der nativen App.
enableUpdaterIntegration	Ermöglicht das Handling von Silent-Update-Checks über @capgo/capacitor-updater.
runUpdateCheck	Führt die Updater-Integration manuell zum Testen aus.
trackReceived	Schreibt manuell ein empfangenes Event.
trackOpened	Schreibt manuell ein geöffnetes Event.
addListener('notificationReceived')	Wird ausgelöst, wenn eine Notification eingeht, während JavaScript aktiv ist.
addListener('notificationOpened')	Wird ausgelöst, wenn ein User eine Notification öffnet.
addListener('backgroundNotification')	Wird bei Background-Data-Notifications ausgelöst und stellt finish().
addListener('registrationChanged')	Wird ausgelöst, wenn sich der native Push-Token ändert.

Zustellgarantien

Native Push folgt dem At-least-once-Prinzip. Eine Kampagne kann wiederholt werden, und ein Gerät kann Duplikate erhalten, wenn die Plattform wiederholte Nachrichten akzeptiert. Nutze Collapse IDs für Update-Checks und stelle sicher, dass Hintergrundprozesse idempotent sind.

iOS-Hintergrundbenachrichtigungen sind Best-effort. Das Betriebssystem kann die Ausführung im Hintergrund basierend auf Akku, Nutzerverhalten, Force-Quit-Status und Systemrichtlinien drosseln oder überspringen. Verlasse dich nicht auf Silent Notifications für kritische Deadlines.

Weiterlesen bei @capgo/capacitor-notifications

Wenn du es nutzt @capgo/capacitor-notifications Um Push-Messaging zu planen, verbinde es mit Erste Schritte für das Setup, Debugging zur Fehlersuche, @capgo/capacitor-updater für stille Update-Checks und Capgo Plugin-Verzeichnis für andere native Plugins.