Debugging

Verwenden Sie diese Liste, wenn eine Benachrichtigung nicht registriert, nicht ankommt, nicht erscheint oder nicht aktualisiert Capgo-Statistiken.

Mit dem Geräteverzeichnis beginnen

Bevor Sie an nativem code debuggen, bestätigen Sie, dass Capgo das Gerät sehen kann.

1. Öffnen Sie die App und melden Sie sich als der Benutzer, den Sie testen möchten.
2. Call CapgoNotifications.register(...) nach der Anmeldung.
3. In Capgo öffnen Sie Benachrichtigungen > Empfänger-Abfrage.
4. Nach demselben externen Kunden-Id suchen.

Sie sollten mindestens einen aktiven Gerät mit: sehen

• recipientKey
• deviceKey
• __CAPGO_KEEP_0__ android oder ios
• Zustand der Berechtigung
• Anwendungsversion
• Pluginversion
• Schlagwörter und Attribute

Wenn die Suche kein Gerät zurückgibt, kann der Sendebefehl nicht auf diesen Benutzer zielen.

Temporäre Debug-Hörer hinzufügen

Hinzufügen Sie temporäre Hörer zum Testen. Entfernen Sie lästige Log-Einträge, bevor Sie das Produkt freigeben.

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

Daten sammeln

Wenn Sie bei der Fehlerbehebung mit Ihrem Team oder Capgo-Support zusammenarbeiten, sammeln Sie:

• Capgo-Anwendungs-ID.
• App-Paket-ID oder iOS-Bundle-ID.
• Geräteplattform und Betriebssystemversion.
• Anwendungsversion und Buildnummer.
• Plugin-Version.
• Außenstehende Kunden-ID.
• recipientKey und deviceKey aus der Registrierung oder dem Empfängerabruf.
• Kampagnen-ID oder Benachrichtigungs-ID.
• Wurde die App im Vordergrund, Hintergrund, durch eine Zwangsschliessung oder frisch installiert?
• Geräteprotokolle aus der Ausführung, die das Problem reproduzierte.

Geräteprotokolle verwenden

Halten Sie ein reales Gerät während der Übermittlung einer Testbenachrichtigung angeschlossen.

Auf Android:

• Öffnen Sie Android Studio Logcat.
• Filtern Sie nach der Paket-ID der App.
• Beachten Sie die Anzeige der Benachrichtigungsanfrage, des nativen Token-Refreshes, der Nachrichtenempfangs- und der JavaScript-Listener-Protokolle.
• Zeigt eine sichtbare Benachrichtigung nicht auf, überprüfen Sie zunächst die Bedeutung der Benachrichtigungschannel und den Zustand der Android 13+-Erlaubnis.

Auf iOS:

• Führen Sie die App von Xcode auf einem physischen Gerät aus.
• Öffnen Sie das Xcode-Konsolenfenster oder Geräte und Simulator Protokolle.
• Filtern Sie nach dem Bundle-Id und CapgoNotifications.
• Bestätigen AppDelegate.swift für Remote-Benachrichtigungen und dass die Hintergrund-Modus-Fähigkeit aktiviert ist.

Senden Sie zunächst einen Vordergrund-Test, dann einen Hintergrund-Test, dann einen stillen Update-Prüfungstest. Diese Reihenfolge trennt JavaScript-Hörer-Probleme von OS-Hintergrund-Lieferungsgrenzen.

Registrierungsprobleme

CLI Setup Did Not Finish

Führen Sie den Setup-Befehl aus dem Ordner aus, der die capacitor.config.*:

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

Wenn der Befehl Ihre App-ID nicht ermitteln kann, geben Sie sie explizit an, wie oben gezeigt. Wenn die Paketinstallation fehlschlägt, bestätigen Sie, dass Capgo private-Vorschau-Paketzugriff für Ihr npm-Konto aktiviert hat, und führen Sie den Befehl dann erneut aus.

Gerät erscheint nicht in Empfängerübersicht

Überprüfen:

• register wird nachdem Ihr App einen authentifizierten Benutzer hat.
• externalId dem Benutzer-ID entspricht, die Sie in der Dashboard suchen.
• identityProof wurde von Ihrem Backend für das gleiche appId und externalId.
• appId in configure entspricht der App Capgo.
• consent ist nicht festgelegt false es sei denn, der Benutzer hat sich abgemeldet.
• Der Gerät hat Zugriff auf das Netzwerk https://api.capgo.app.
• Der native Push-Token wurde erstellt. Verwenden Sie registrationChanged um den Token-Refresh zu bestätigen.

Ungültige Identitätsbeweis

Der Beweis ist an das Capgo-App-Id und externe ID gebunden. Wenn sich entweder der Wert ändert, erzeugen Sie einen neuen Beweis.

Stellen Sie einen Beweis nicht für immer im Cache oder wiederholen Sie einen Beweis über Apps. Erzeugen Sie ihn auf Ihrem Backend nach dem Login, geben Sie ihn an die App weiter und rufen Sie register.

Gerät Registriert, aber Berechtigung abgelehnt

Der Plugin kann Gerätezustand auch dann registrieren, wenn der Benutzer die Berechtigung abgelehnt hat. Sie können das Gerät immer noch sehen, aber sichtbare Benachrichtigungen werden nicht angezeigt.

Verwenden Sie eine Eingabeaufforderung vor der OS-Anfrage. Erklären Sie dem Benutzer, was er erhält, und fragen Sie nach der Zustimmung nur dann, wenn der Vorgang Sinn ergibt.

Lieferprobleme

In der Warteschleife, aber nicht gesendet

Überprüfen Sie:

• Die Plattformzertifikatsstatus ist configured in Capgo.
• Die Worker-Umgebung enthält den genauen geheimen Referenzwert, der vom Dashboard angezeigt wird.
• Die Paket-ID oder die Bundle-ID im App entspricht der Plattform-Setup für Push-Benachrichtigungen.
• Die Zielgruppe entspricht mindestens einer aktiven Geräte.
• Die Kampagne ist nicht auf eine Tag oder Segment beschränkt, das das Gerät nicht hat.

__CAPGO_KEEP_0__

Überprüfen:

• Das Gerät ist online.
• Die App wurde nicht durch den Benutzer beendet.
• Die Berechtigung für OS-Benachrichtigungen wurde erteilt.
• Android-Batteriebeschränkungen blockieren die App nicht während der Testphase.
• iOS-Low-Power-Modus und Hintergrundaktualisierungsbeschränkungen beeinflussen die Hintergrundlieferung nicht.
• Die Benachrichtigung wurde nicht durch eine andere Benachrichtigung mit derselben Zusammenfassungs-ID ersetzt.

Nativ-Push-Plattformen können eine Benachrichtigung annehmen und die Lieferung später verzögern, drosseln, konsolidieren oder abbrechen. Behandeln Sie die vom Anbieter akzeptierten Statistiken als „zur Lieferung angenommen“, nicht als Beweis dafür, dass das Gerät sie angezeigt hat.

__CAPGO_KEEP_0__

Überprüfen:

• Die App wurde nicht im Vordergrund geöffnet. Hintergrundbenachrichtigungen werden normalerweise an JavaScript weitergeleitet, damit die App entscheiden kann, welche Benutzeroberfläche angezeigt werden soll.
• Die Android-Benachrichtigungschannel-Wichtigkeit ist hoch genug, um eine Warnung anzuzeigen.
• Die Android-13+-Benachrichtigungs-Erlaubnis ist erteilt.
• iOS-Fokus, Benachrichtigungs-Zusammenfassung oder Benachrichtigungs-Einstellungen pro App verbergen die Benachrichtigung nicht.
• Badge-Entfernung oder App-Öffnen-Logik entfernt während der Testung nicht übergebene Benachrichtigungen.

Probleme mit Hintergrundbenachrichtigungen

Hintergrundrückruf läuft nicht

Hintergrundbenachrichtigungen sind willkürlich. Der Betriebssystem kann sie überspringen.

Überprüfen:

• iOS hat Hintergrundmodi > Remote-Nachrichten aktiviert.
• iOS AppDelegate.swift wird Remote-Nachrichten an CapgoNotificationsRemoteNotification.
• Sie testen das iOS-Hintergrundverhalten auf einem physischen Gerät.
• Das App wurde nicht durch den Benutzer beendet.
• Der Hintergrund-Handler ruft finish().
• Arbeiten im Callback sind kurz, netzwerksicher und idempotent.

Bei iOS können Hintergrundpushes eingeschränkt werden, wenn Sie zu viele senden, zu viel Zeit benötigen oder der Benutzer das App selten öffnet. Dies ist die erwartete Plattformverhalten.

Hintergrund gestartet, aber nicht abgeschlossen

Wenn Statistiken zeigen background_started ohne background_finisheddie JavaScript-Handler wahrscheinlich geworfen, abgelaufen oder nicht aufgerufen hat finish().

Der Handler in try/finally:

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

Stille Aktualisierungskontrolleprobleme

Aktualisierungskontrolleankündigung tritt auf, aber keine Aktualisierung installiert wird

Überprüfen:

• @capgo/capacitor-updater installiert und konfiguriert ist.
• autoUpdater installiert und konfiguriert ist. true oder wurde genannt. enableUpdaterIntegration Die Einstellungen für Benachrichtigungen der App ermöglichen es, Push-Update-Überprüfungen durchzuführen.
• Das Zielgerät gehört zum Kanal, den Sie erwarten.
• Die App hat ein neueres Bundle in __CAPGO_KEEP_0__ zur Verfügung.
• The app has a newer bundle available in Capgo.
• warten für den nächsten Neustart oder Hintergrundzyklus, next installiert, sobald der Updater es sicher tun kann. set Führen Sie eine manuelle Überprüfung durch, während die App geöffnet ist:

Zurücksetzen in die Zwischenablage

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

console.log(result)

, überprüfen Sie die Einstellungen des Updater-Plugins zuerst. unavailablequeues for the next restart or background cycle, translates to: warten für den nächsten Neustart oder Hintergrundzyklus,

Probleme mit dem Badge

Überprüfen Sie:

• Die Zieladresse wird auf das richtige Gerät im Empfängerlookup gefunden.
• Die Plattform unterstützt App-Badges für den Launcher oder die Startseite, die getestet wird.
• Der Benutzer hat die Badges in den Einstellungen für Benachrichtigungen des Betriebssystems nicht deaktiviert.
• Die App löscht die Badges nicht sofort beim Start.
• Sie führen keine lokalen "Rennen" gegen den Backend-Badge-Sendevorgang durch. setBadge Probleme mit den Statistiken

Abschnitt: "Probleme mit den Statistiken"

Abschnitt: "Doppelte Statistik-Anzeigen"

Bei der Benachrichtigungsversendung wird mindestens einmal versucht. Die Wiederholung der Warteschlange und die Wiederholung der Plattform können eine Sendung duplizieren. Verwenden Sie Benachrichtigungs-IDs und Zusammenbruch-IDs, wenn die Aktion Ihres Apps unveränderlich sein muss.

Statistiken fehlen für alte Geräte

Die Analytics-Engine-Registrierung ist für aktive Geräte und nicht für eine ewige Datenbank gedacht. Der Plugin sollte die Registrierung bei der App-Start, Token-Refresh, Änderung des externen IDs und regelmäßig vor dem Zeitfenster der aktiven-Geräte-Retention aktualisieren.

Offene Ereignisse fehlen

Überprüfen Sie:

• Die Benachrichtigung enthält einen stabilen id.
• notificationOpened Der Listener wird während der App-Startzeit registriert.
• Die App ersetzt die native offene Fluss nicht mit einem benutzerdefinierten code bevor der Plugin es sieht.
• Der Benutzer hat die Benachrichtigung tatsächlich angeklickt und nicht die App manuell geöffnet.

API Debug Commands

Suchen Sie einen Empfänger:

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'

Einen Vordergrund-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 fehlt in der Lookup	register __CAPGO_KEEP_0__
Zugriff verweigert	OS-Fenster wurde nicht angefordert oder abgelehnt
In der Warteschleife, aber keine gesendeten Statistiken	Plattformkredenziale sind fehlend oder deaktiviert
Gesendet, aber keine empfangenen Statistiken	Gerät ist offline, OS-Throttling, App wurde gestoppt oder Token ist ungültig
Hintergrundbenachrichtigungen, aber keine Banner	Die App ist im Vordergrund und muss ihre eigene in-app-UI anzeigen.
Hintergrund läuft nie auf iOS.	Fehlende Funktionen, fehlende AppDelegate-Forwarding, Zwangsvorbeugung der App oder Betriebssystem-Throttling.
Update-Überprüfung tut nichts.	Updater-Integration deaktiviert, kein neuer Bundle, falscher Kanal oder Installationsmodus missverstanden.
Badge wird zurückgesetzt.	App-Start code löscht Badges oder lokale und Backend-Badge-Schreibvorgänge laufen auseinander.

Weitermachen von Debugging

Nachdem sich das Gerät registriert und eine Testbenachrichtigung funktioniert, verwenden Einstieg um Badges, Kampagnenzielsetzung und stille Update-Überprüfungen in Ihre Produktions-App einzubinden.