Debugging

Nutze diese Checkliste, wenn eine Benachrichtigung nicht registriert wird, nicht ankommt, nicht angezeigt wird oder die Capgo Stats nicht aktualisiert.

Mit dem Device Record beginnen

Bevor du natives code debuggst, stelle sicher, dass Capgo das Gerät sehen kann.

1. Öffne die App und melde dich als der zu testende User an.
2. Rufe CapgoNotifications.register(...) nach dem Login.
3. Öffne in Capgo Benachrichtigungen > Empfänger-Lookup.
4. Suche nach derselben externen Customer ID.

Du solltest mindestens ein aktives Gerät sehen mit:

• recipientKey
• deviceKey
• Plattform android oder ios
• Berechtigungsstatus
• App-Version
• Plugin-Version
• Tags und Attribute

Wenn der Lookup kein Gerät findet, kann der Send-Pfad diesen Nutzer nicht anvisieren.

Temporäre Debug-Listener hinzufügen

Füge während des Testens temporäre Listener hinzu. Entferne unnötige Logs vor dem Release.

await CapgoNotifications.addListener('registrationChanged', (token) => {
  console.log('[CapgoNotifications] registrationChanged', token.value.slice(0, 12))
})

await CapgoNotifications.addListener('notificationReceived', (notification) => {
  console.log('[CapgoNotifications] notificationReceived', notification.id, notification.data)
})

await CapgoNotifications.addListener('notificationOpened', (event) => {
  console.log('[CapgoNotifications] notificationOpened', event.notification.id, event.actionId)
})

await CapgoNotifications.addListener('backgroundNotification', async (event) => {
  console.log('[CapgoNotifications] backgroundNotification', event.notification.id, event.notification.data)
  await event.finish()
})

Diese Informationen sammeln

Sammle bei der Fehlersuche mit deinem Team oder dem Capgo Support folgendes:

• Die Capgo App ID.
• App Package ID oder iOS Bundle ID.
• Geräteplattform und OS-Version.
• App-Version und Build-Nummer.
• Plugin-Version.
• Externe Kunden-ID.
• recipientKey und deviceKey Aus der Registrierung oder dem Recipient-Lookup.
• Campaign ID oder Notification ID.
• Ob die App im Foreground, Background, force-closed oder frisch installiert war.
• Device Logs aus dem Run, der den Fehler reproduziert hat.

Device Logs verwenden

Lass ein echtes Gerät verbunden, während du eine Test-Benachrichtigung sendest.

Unter Android:

• Öffne Logcat in Android Studio.
• Filtere nach der App-Package-ID.
• Achte auf Logs zur Notification-Berechtigung, zum nativen Token-Refresh, zum Empfang von Nachrichten und zu den JavaScript-Listenern.
• Falls keine sichtbare Benachrichtigung erscheint, prüfe zuerst die Importance des Notification Channel und den Berechtigungsstatus unter Android 13+.

Unter iOS:

• Starte die App aus Xcode auf einem physischen Gerät.
• Öffne die Xcode-Konsole oder Geräte und Simulatoren Logs.
• Nach der Bundle-ID filtern und CapgoNotifications.
• Bestätigen AppDelegate.swift Remote-Notifications weiterleitet und dass die Background-Mode-Capability aktiviert ist.

Sende zuerst einen Foreground-Test, dann einen Background-Test und danach einen Silent-Update-Check-Test. Diese Reihenfolge trennt JavaScript-Listener-Probleme von den OS-Limits bei der Background-Zustellung.

Registrierungsprobleme

CLI Setup wurde nicht abgeschlossen

Führe den Setup-Befehl in dem Ordner aus, der Folgendes enthält capacitor.config.*:

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

Falls der Befehl deine App-ID nicht automatisch erkennt, gib sie wie oben gezeigt explizit an. Wenn die Paketinstallation fehlschlägt, prüfe, ob der Paketname @capgo/capacitor-notifications, überprüfe, ob dein npm Registry korrekt ist https://registry.npmjs.org, prüfe den Netzwerkzugriff und führe den Befehl erneut aus.

Device erscheint nicht in der Empfänger-Suche

Prüfen:

• register wird aufgerufen, nachdem deine App einen authentifizierten User hat.
• externalId stimmt mit der User-ID überein, die du im Dashboard suchst.
• identityProof wurde von deinem Backend für denselben appId und externalId.
• appId in configure stimmt mit der Capgo App überein.
• consent ist nicht gesetzt auf false es sei denn, der User hat sich abgemeldet.
• Das Gerät hat Netzwerkzugriff auf https://api.capgo.app.
• Der native Push-Token wurde erstellt. Nutze registrationChanged um den Token-Refresh zu bestätigen.

Ungültiger Identity Proof

Der Proof ist an die Capgo App-ID und die externe ID gebunden. Wenn sich einer der Werte ändert, erstelle einen neuen Proof.

Cache niemals einen Proof dauerhaft oder verwende denselben Proof für mehrere Apps. Erstelle ihn über dein Backend nach dem Login, gib ihn an die App zurück und rufe register.

Device registriert, aber Berechtigung verweigert

Das Plugin kann den Gerätestatus auch dann registrieren, wenn der User die Berechtigung verweigert hat. Das Gerät ist weiterhin sichtbar, aber es werden keine Benachrichtigungen angezeigt.

Verwende einen Permission Primer Screen vor dem OS-Prompt. Erkläre dem Nutzer den Vorteil, bevor du die Berechtigung erst dann anfragst, wenn die Aktion auch sinnvoll ist.

Zustellungsprobleme

In Warteschlange, aber nicht gesendet

Prüfen:

• Der Status der Plattform-Credentials ist configured in Capgo.
• Die Worker-Umgebung enthält exakt die Secret-Referenz, die im Dashboard angezeigt wird.
• Die Package ID oder Bundle ID der App stimmt mit dem Plattform-Push-Setup überein.
• Die Zielgruppe lässt sich auf mindestens ein aktives Gerät auflösen.
• Die Kampagne ist nicht auf ein Tag oder Segment beschränkt, das das Gerät nicht besitzt.

Gesendet, aber nicht empfangen

Prüfen:

• Das Gerät ist online.
• Die App wurde nicht vom Nutzer zwangsgestoppt.
• Die OS-Benachrichtigungsberechtigung wurde erteilt.
• Android-Akkubeschränkungen blockieren die App beim Testen nicht.
• iOS Low Power Mode und Hintergrundaktualisierungen beeinträchtigen die Zustellung nicht.
• Die Benachrichtigung wurde nicht durch eine andere mit derselben Collapse ID ersetzt.

Native Push-Plattformen können eine Benachrichtigung annehmen und die Zustellung später verzögern, drosseln, zusammenfassen oder verwerfen. Betrachte Provider-Stats als „zur Zustellung angenommen“, nicht als Beweis für die Anzeige auf dem Gerät.

Empfangen, aber nicht angezeigt

Prüfen:

• Die App war nicht im Vordergrund. Foreground-Notifications werden normalerweise an JavaScript ausgeliefert, damit deine App entscheiden kann, welche UI sie anzeigt.
• Die Wichtigkeit des Android-Notification-Channels ist hoch genug, um einen Alert anzuzeigen.
• Die Notification-Permission für Android 13+ ist erteilt.
• iOS-Fokus, Notification Summary oder App-spezifische Notification-Einstellungen verbergen die Notification nicht.
• Badge-Clearing oder App-Open-Logik entfernt zugestellte Notifications während des Tests nicht.

Probleme mit Hintergrund-Benachrichtigungen

Background Callback wird nicht ausgeführt

Background Notifications erfolgen nach dem Best-Effort-Prinzip. Das OS kann sie überspringen.

Prüfen:

• iOS hat Background-Modi > Remote-Benachrichtigungen aktiviert.
• iOS AppDelegate.swift leitet Remote Notifications weiter an CapgoNotificationsRemoteNotification.
• Testen Sie das iOS-Background-Verhalten auf einem echten Gerät.
• Die App wurde vom Nutzer nicht zwangsbeendet.
• Der Background-Handler ruft finish().
• Die Arbeit im Callback ist kurz, netzwerksicher und idempotent.

Unter iOS können Background-Pushes gedrosselt werden, wenn Sie zu viele senden, zu viel Zeit benötigen oder der Nutzer die App selten öffnet. Dies ist das erwartete Verhalten der Plattform.

Background gestartet, aber nicht beendet

Wenn die Stats zeigen background_started ohne background_finished, the JavaScript handler likely threw, timed out, or did not call finish().

Den Handler umschließen mit try/finally:

await CapgoNotifications.addListener('backgroundNotification', async (event) => {
  try {
    await doShortBackgroundWork(event.notification.data)
  } finally {
    await event.finish()
  }
})

Probleme beim Silent Update Check

Update-Check-Benachrichtigung kommt an, aber kein Update wird installiert

Prüfen:

• @capgo/capacitor-updater ist installiert und konfiguriert.
• autoUpdater ist true oder enableUpdaterIntegration aufgerufen wurde.
• Die Notification-Einstellungen der App erlauben Push-Updates.
• Das Zielgerät gehört zum erwarteten Channel.
• Für die App ist ein neueres Bundle in Capgo verfügbar.
• Dein Update-Installationsmodus ist korrekt: next wartet auf den nächsten Neustart oder Background-Cycle, set wird installiert, sobald der Updater es sicher tun kann.

Führe einen manuellen Check durch, während die App offen ist:

const result = await CapgoNotifications.runUpdateCheck({
  enabled: true,
  installMode: 'next',
})

console.log(result)

Falls der manuelle Check unavailablezurückgibt, prüfe zuerst das Setup des Updater-Plugins.

Badge-Probleme

Prüfen:

• Das Ziel wird bei der Empfänger-Suche korrekt aufgelöst.
• Die Plattform unterstützt App-Badges für den getesteten Launcher oder Home-Screen.
• Der Nutzer hat Badges in den OS-Benachrichtigungseinstellungen nicht deaktiviert.
• Die App löscht Badges nicht sofort beim App-Start.
• Es kommt zu Race Conditions zwischen lokalen setBadge Aufrufen und Backend-Badge-Sends.

Statistik-Probleme

Statistiken wirken dupliziert

Das Versenden von Benachrichtigungen erfolgt nach dem At-Least-Once-Prinzip. Retries in der Queue oder durch die Plattform können zu Duplikaten führen. Nutze Notification IDs und Collapse IDs, wenn deine App-Aktion idempotent sein muss.

Statistiken fehlen für ältere Geräte

Das Analytics Engine Registry ist für aktive Geräte gedacht, nicht als permanente Datenbank. Das Plugin sollte die Registrierung beim App-Start, bei Token-Refresh, bei Änderungen der externen ID und regelmäßig vor Ablauf der Aufbewahrungsfrist für aktive Geräte aktualisieren.

Offene Events fehlen

Prüfen:

• Die Benachrichtigung enthält einen stabilen id.
• notificationOpened Listener wird während des App-Starts registriert.
• Die App ersetzt den nativen Open-Flow nicht durch ein eigenes code, bevor das Plugin es erkennt.
• Der Nutzer hat tatsächlich auf die Benachrichtigung getippt, anstatt die App manuell zu öffnen.

API Debug-Commands

Empfänger suchen:

curl -X POST 'https://api.capgo.app/notifications/recipients/lookup' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: CAPGO_API_KEY' \
  -d '{
    "appId": "com.example.app",
    "externalId": "customer-user-123"
  }'

Statistiken lesen:

curl 'https://api.capgo.app/notifications/stats?app_id=com.example.app&days=7' \
  -H 'x-api-key: CAPGO_API_KEY'

Foreground-Test senden:

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": "Capgo test",
      "body": "Open this notification to test events.",
      "data": { "debug": "true" }
    }
  }'

Häufige Ursachen

Symptom	Wahrscheinliche Ursache
Gerät wird nicht gefunden	register Nicht aufgerufen, Proof-Mismatch, Consent auf false oder App-ID-Mismatch.
Berechtigung verweigert	OS-Prompt abgelehnt oder noch nicht angefordert.
In Queue, aber keine gesendeten Stats	Plattform-Credentials fehlen oder sind deaktiviert.
Gesendet, aber keine empfangenen Stats	Gerät offline, OS-Throttling, App force-stopped oder Token ungültig.
Foreground-Logs vorhanden, aber kein Banner	Die App ist im Vordergrund und muss ihre eigene In-App-UI anzeigen.
Hintergrundausführung läuft unter iOS nie	Fehlende Capabilities, fehlendes AppDelegate-Forwarding, App-Force-Quit oder OS-Throttling.
Update-Check bewirkt nichts	Updater-Integration deaktiviert, kein neueres Bundle, falscher Channel oder falscher Install-Mode.
Badge-Resets	App-Startup code löscht Badges, oder lokale und Backend-Badge-Writes laufen in eine Race Condition.

Weiter mit dem Debugging

Sobald das Gerät registriert ist und eine Test-Notification funktioniert, nutzen Sie Erste Schritte um Badges, Campaign-Targeting und Silent Update-Checks in Ihre Production-App einzubinden.