Debugging

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

Mit dem Geräteverzeichnis beginnen

Bevor Sie native code debuggen, stellen Sie sicher, dass Capgo das Gerät sehen kann.

1. Öffnen Sie die App und melden Sie sich als der Benutzer an, den Sie testen möchten.
2. Anrufen CapgoNotifications.register(...) nach der Anmeldung.
3. In Capgo, öffnen Benachrichtigungen > Empfängerauflistung.
4. Suchen Sie nach dem gleichen externen Kunden-ID.

Sie sollten mindestens einen aktiven Gerät mit:

• recipientKey
• deviceKey
• Plattform android oder ios
• Entscheiden Sie sich für eine Plattform.
• Zustand der Berechtigung
• Anwendungsversion
• Pluginversion

Tags und Attribute

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

Hinzufügen Sie temporäre Hörer, während Sie testen. Entfernen Sie lästige Log-Einträge, bevor Sie es versenden.

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

Sammeln Sie diese Informationen

Wenn Sie mit Ihrem Team oder Capgo-Support debuggen, sammeln Sie:

• Capgo-Anwendungs-ID.
• App-Paket-ID oder iOS-Bundle-ID.
• Geräteplattform und Betriebssystemversion.
• Anwendungsversion und Buildnummer.
• Pluginversion.
• Externes Kunden-ID.
• recipientKey und deviceKey oder aus der Registrierung oder dem Empfänger-lookup.
• Kampagnen-ID oder Benachrichtigungs-ID.
• Ob die App im Vordergrund, Hintergrund, durch Zwangs-Schließen oder frisch installiert war.
• Geräteprotokolle aus der Ausführung, die das Problem reproduzierte.

Benutze Geräteprotokolle

Halten Sie ein reales Gerät an, während Sie eine Test-Benachrichtigung senden.

Bei Android:

• Öffnen Sie Android Studio Logcat.
• Filtern Sie nach der App-Paket-ID.
• Beobachten Sie die Benachrichtigungs-Erweiterungsanfrage, den nativen Token-Refresh, die Nachrichten-Empfangs- und die JavaScript-Listener-Protokolle.
• Wenn eine sichtbare Benachrichtigung nicht angezeigt wird, überprüfen Sie zunächst die Bedeutung des Benachrichtigungs-Kanals 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 der Bundle-ID und CapgoNotifications.
• Bestätigen Sie AppDelegate.swift dass Remote-Benachrichtigungen und die Hintergrundmodus-Fähigkeit aktiviert sind.

Senden Sie zunächst einen Vordergrund-Test, dann einen Hintergrund-Test und schließlich einen stillen Update-Prüfungstest. Diese Reihenfolge trennt JavaScript-Listener-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 automatisch 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 erneut aus.

Gerät erscheint nicht in der Empfängerliste

Überprüfen Sie:

• register wird nachdem Ihr App einen authentifizierten Benutzer hat.
• externalId entspricht der Benutzer-ID, die Sie in der Dashboard-Suche eingeben.
• identityProof wurde von Ihrem Backend für das gleiche appId und externalId.
• appId in configure passt sich dem Capgo-App an.
• consent wird nicht auf false solange der Benutzer sich nicht abgemeldet hat.
• Das Gerät hat Zugriff auf das Internet. https://api.capgo.app.
• Der native Push-Token wurde erstellt. Verwenden Sie registrationChanged zur Bestätigung der Token-Refresh.

Ungültige Identitätsnachweise

Der Nachweis ist an das Capgo-App-Id und den externen ID gebunden. Wenn sich entweder der Wert ändert, erstellen Sie einen neuen Nachweis.

Machen Sie keinen Nachweis für immer im Cache oder wiederholen Sie einen Nachweis über Apps. Erstellen Sie ihn auf Ihrem Backend nach dem Login, geben Sie ihn an das App zurück und rufen Sie register.

Gerät registriert, aber Berechtigung verweigert

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

Verwenden Sie eine Berechtigungsanzeige vor dem Betriebssystem-Fenster. Erklären Sie dem Benutzer, was er erhält, und fragen Sie nach der Berechtigung nur dann, wenn der Vorgang Sinn ergibt.

Zustellungsprobleme

Angekündigt, aber nicht gesendet

Überprüfen Sie:

• Plattformzertifikatsstatus ist configured Capgo.
• Die Worker-Umgebung enthält den genauen geheimen Referenzwert, der vom Dashboard angezeigt wird.
• Die Paket- oder 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.

Gesendet, aber nicht erhalten

Überprüfe:

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

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

Erhalten, aber nicht angezeigt

Überprüfen Sie:

• Die App war nicht im Vordergrund. Vordergrundbenachrichtigungen werden normalerweise an JavaScript weitergeleitet, damit die App entscheiden kann, welche Benutzeroberfläche angezeigt werden soll.
• Die Android-Benachrichtigungs-Kanal-Beliebtheit ist hoch genug, um eine Warnung anzuzeigen.
• Die Android-13+-Benachrichtigungs-Erlaubnis ist erteilt.
• iOS-Fokus, Benachrichtigungs-Zusammenfassung oder Einstellungen für pro-App-Benachrichtigungen verbergen die Benachrichtigung nicht.
• Die Schaltfläche zum Löschen der Benachrichtigung oder die Logik zum Öffnen der App entfernt während der Tests nicht die gelieferten Benachrichtigungen.

Probleme mit Hintergrundbenachrichtigungen

Hintergrundrückruf läuft nicht

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

Überprüfe:

• iOS hat Hintergrundfunktionen > Remote-Benachrichtigungen aktiviert.
• iOS AppDelegate.swift überträgt Remote-Benachrichtigungen an CapgoNotificationsRemoteNotification.
• Du testest die Hintergrundverhalten von iOS auf einem physischen Gerät.
• Die App wurde nicht durch den Benutzer beendet.
• Der Hintergrundhandler ruft finish().
• Arbeite innerhalb des Callbacks kurz, sicher im Netzwerk und idempotent.

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

Hintergrund gestartet, aber nicht abgeschlossen

Wenn Statistiken zeigen background_started ohne background_finished, ist der JavaScript-Handler wahrscheinlich abgestürzt, ist abgelaufen oder hat nicht aufgerufen finish().

Verwenden Sie den Handler in einem try/finally:

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

Stille Aktualisierungsprüfungsprobleme

Update-Prüfungsnachricht tritt auf, aber keine Aktualisierung installiert

Überprüfen Sie:

• @capgo/capacitor-updater installiert und konfiguriert ist.
• autoUpdater ist true oder enableUpdaterIntegration oder
• wurde genannt.
• Die Benachrichtigungen-Einstellungen der App ermöglichen Push-Update-Überprüfungen.
• The app has a newer bundle available in Capgo.
• Die App hat ein neueres Bundle in __CAPGO_KEEP_0__ verfügbar. next Ihr Update-Installationsmodus ist korrekt: set sich für die nächste Neustart- oder Hintergrundzyklus-Warteschlange anstellt,

installiert, sobald der Updater es sicher tun kann.

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

console.log(result)

Wenn die manuelle Überprüfung zurückgibt unavailable, überprüfen Sie die Einstellungen der Updater-Plugin-Setup zuerst.

Badge-Probleme

Überprüfen Sie:

• Die Zieladresse führt zum richtigen Gerät in der Empfängerübersicht.
• Die Plattform unterstützt App-Badges für den Launcher oder die Homescreen, die getestet werden.
• Der Benutzer hat Badge in den Einstellungen für Benachrichtigungen im Betriebssystem nicht deaktiviert.
• Die App löscht die Badges nicht sofort beim Start.
• Sie rufen lokale setBadge Aufrufe nicht gegen den Hintergrundversand von Badges aus.

Statistik-Probleme

Statistik-Ausgaben Doppelten

Die Benachrichtigungssendung erfolgt mindestens einmal. Die Wiederholung der Warteschlange und die Wiederholung der Plattform können eine Sendung duplizieren. Verwenden Sie Benachrichtigungs-IDs und Zusammenfassungs-IDs, wenn Ihre App-Aktion idempotent sein muss.

Statistik-Ausgaben 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 App-Start, Token-Refresh, Änderung der externen ID und regelmäßig vor dem Aktiv-Gerät-Retentionsfenster aktualisieren.

Offene Ereignisse Fehlen

Überprüfen Sie:

• Die Benachrichtigung enthält eine stabile id.
• notificationOpened Hörer wird während der Anwendungsstart registriert.
• Die App ersetzt den nativen Open-Flow nicht mit einem benutzerdefinierten code bevor der Plugin es sieht.
• Der Benutzer hat tatsächlich auf die Benachrichtigung getippt und nicht die App manuell geöffnet.

API Debug-Befehle

Suche 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"
  }'

Lese Statistiken:

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

Senden Sie einen Vordergrund-Test:

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 bei der Suche	register nicht aufgerufen, Beweisungleichheit, Zustimmung falsch, App-ID-Übereinstimmung falsch.
Zugriffsverweigerung	OS-Fenster wurde abgelehnt oder wurde noch nicht angefordert.
In der Warteschleife, aber keine gesendeten Statistiken	Plattformkennungen sind fehlend oder deaktiviert.
Gesendet, aber keine Empfangsstatistiken	Gerät ist offline, Betriebssystem-Throttling, Anwendung wurde beendet oder Token ist ungültig.
Hintergrundbenachrichtigungen werden protokolliert, aber keine Banner	Die Anwendung ist im Vordergrund und muss ihre eigene In-app-UI anzeigen.
Hintergrundprozess läuft nie auf iOS	Fehlende Berechtigungen, fehlende AppDelegate-Forwarding, Anwendung wurde beendet oder Betriebssystem-Throttling.
Aktualisierungsprüfung tut nichts	Updater-Integration deaktiviert, keine neue Bundle, falscher Kanal oder Installationsmodus wird falsch verstanden.
Abzeichen wird zurückgesetzt	Bei der App-Start code werden Abzeichen oder lokale und Backend-Abzeichen-Schreibvorgänge rassen.

Weitermachen von Debugging

Nachdem sich das Gerät registriert und eine Testbenachrichtigung funktioniert, verwenden Sie Einstieg um Badges, Kampagnenzielgruppen und stille Aktualisierungsprüfungen in Ihre Produktionsanwendung einzubinden.