Debugging

Verwenden Sie diese Liste, wenn eine Benachrichtigung nicht registriert, nicht eintrifft, nicht angezeigt 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ängerabfrage.
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 zwischen
• Zustand der Berechtigung
• App-Version
• Plugin-Version

Tags und Attribute

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

Fügen Sie temporäre Hörer während der Testphase hinzu. 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()
})

Diese Informationen sammeln

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

• Capgo-Anwendungs-ID.
• Anwendungs-Paket-ID oder iOS-Bundle-ID.
• Geräteplattform und Betriebssystemversion.
• Anwendungsversion und Buildnummer.
• Pluginversion.
• Außenliegende Kunden-ID.
• recipientKey und deviceKey aus der Registrierung oder der Empfängerabfrage.
• Kampagnen-ID oder Benachrichtigungs-ID.
• Ob die App im Vordergrund, Hintergrund, durch Zwangsbeendigung oder neu installiert war.
• Geräteprotokolle aus der Ausführung, die das Problem reproduzierte.

Geräteprotokolle verwenden

Halten Sie ein reales Gerät an, während Sie eine Testbenachrichtigung senden.

Bei Android:

• Öffnen Sie Android Studio Logcat.
• Filtern Sie nach der App-Paket-ID.
• Beobachten Sie die Benachrichtigungsanforderung, den nativen Token-Refresh, die Nachrichtenempfangs- 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 Filtern Sie nach der Bundle-ID und
• Bestätigen Sie CapgoNotifications.
• dass Remote-Benachrichtigungen und dass die Hintergrund-Modus-Fähigkeit aktiviert ist. AppDelegate.swift Senden Sie zunächst einen Vordergrund-Test, dann einen Hintergrund-Test und dann einen stillen Update-Überprüfungs-Test. Diese Reihenfolge trennt JavaScript-Hörer-Probleme von OS-Hintergrund-Lieferungsgrenzen.

Registrierungsprobleme

Abschnitt mit dem Titel „Registrierungsprobleme“

CLI Setup Fertigstellung hat nicht funktioniert

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 der Paketname @capgo/capacitor-notificationsüberprüfen Sie Ihr npm-Registrierung ist https://registry.npmjs.orgÜberprüfen Sie die Netzwerkverbindung, dann den Befehl erneut ausführen.

Gerät erscheint nicht in Empfängerlookup

Überprüfen Sie:

• register wird nachdem Ihr App eine authentifizierte Benutzer hat.
• externalId entspricht der Benutzer-ID, die Sie im Dashboard suchen.
• identityProof wurde von Ihrem Backend für das gleiche appId und externalId.
• appId context:Seite/ Bereich: Capgo-Marketing-Website. Rolle: Kurze Benutzeroberflächenebene oder Navigationspunkt. Anzeigen in: Seite trust.astro. Nachrichtsschlüssel `und` (Und). configure matches the Capgo app.
• consent entspricht der __CAPGO_KEEP_0__-App. false ist nicht auf
• es sei denn der Benutzer hat sich abgemeldet. https://api.capgo.app.
• Der Gerät hat Zugriff auf das Netzwerk registrationChanged Der native Push-Token wurde erstellt. Verwenden Sie

zur Bestätigung der Token-Refresh.

Die Verifizierung ist an die Capgo-App-ID und die externe ID gebunden. Wenn sich entweder der Wert ändert, erstellen Sie eine neue Verifizierung.

Verwenden Sie keine Verifizierung für immer im Cache oder wiederholen Sie eine Verifizierung über Apps. Erstellen Sie sie auf Ihrem Backend nach der Anmeldung, senden Sie sie an die App und rufen Sie sie dann auf. register.

Gerät registriert, aber Berechtigung verweigert

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

Verwenden Sie eine Berechtigungshinweis-Anzeige 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.

Lieferprobleme

In der Warteschleife, aber nicht gesendet

Überprüfen Sie:

• Plattformzertifikatsstatus ist configured in Capgo.
• Der Worker-Umgebung enthält den genauen geheimen Referenz, wie sie vom Dashboard angezeigt wird.
• Die Paket-ID oder die Bundle-ID in der 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 OS-Benachrichtigungs-Erlaubnis ist 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 demselben Zusammenbruch-ID ersetzt.

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

Empfangen, aber nicht angezeigt

Überprüfe:

• Die App war nicht im Vordergrund. Vordergrundbenachrichtigungen werden normalerweise an JavaScript geliefert, 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 per-App-Benachrichtigungs-Einstellungen verbergen die Benachrichtigung nicht.
• Schaltflächen zum Lösen von Badge oder App-Öffnen-Logik entfernen während der Testphase nicht die gelieferten Benachrichtigungen.

Hintergrundbenachrichtigungsprobleme

Hintergrundcallback wird nicht ausgeführt

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

Überprüfe:

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

Bei 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 die 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().

Fassen Sie den Handler in try/finally:

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

Stille Aktualisierungsprüfungsprobleme

Benachrichtigung über Update-Check kommt, aber kein Update installiert wird

Überprüfen Sie:

• @capgo/capacitor-updater installiert und konfiguriert ist.
• autoUpdater oder true oder enableUpdaterIntegration oder
• oder
• oder
• The app has a newer bundle available in Capgo.
• Die Benachrichtigung über das Update ist angekommen, aber kein Update wird installiert. next Die Benachrichtigung über das Update ist angekommen, aber kein Update wird installiert. set installiert, sobald der Updater es sicher tun kann.

Führen Sie eine manuelle Überprüfung durch, während die App geöffnet ist:

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

console.log(result)

Wenn die manuelle Überprüfung unavailable, überprüfen Sie die Einstellungen der Updater-Plugin-Software 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 OS-Benachrichtigungs-Einstellungen nicht deaktiviert.
• Die App löscht Badge nicht sofort bei Start.
• Sie rufen lokale Anfragen nicht aus. setBadge Anfragen gegen den Backend-Badge werden nicht gesendet.

Statistikprobleme

Statistiken sehen dupliziert aus

Die Benachrichtigungsversendung ist mindestens einmalig. Die Wiederholungs- und Plattformwiederholungsqueue können eine Sendung duplizieren. Verwenden Sie Benachrichtigungs-IDs und Zusammenfassungs-IDs, wenn Ihre App-Aktion idempotent sein muss.

Statistiken fehlen für alte Geräte

Die Analytics-Engine-Registrierung ist für aktive Geräte gedacht, nicht für eine ewige Datenbank. Der Plugin sollte die Registrierung bei App-Start, Token-Refresh, externem ID-Wechsel und regelmäßig vor dem Aktivgeräte-Retentionsfenster aktualisieren.

Offene Ereignisse fehlen

Überprüfen Sie:

• Die Benachrichtigung enthält einen stabilen id.
• notificationOpened Der Listener ist während der Anwendungsstartzeit registriert.
• Die Anwendung ersetzt den nativen Open-Flow nicht durch einen benutzerdefinierten code bevor der Plugin ihn sieht.
• Der Benutzer hat die Benachrichtigung tatsächlich angeklickt und nicht die Anwendung manuell geöffnet.

API Debug-Befehle

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

Lesen Sie Statistiken:

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

Vordergrundtest 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 Suche	register nicht aufgerufen, Beweisungleichheit, Zustimmung falsch, App-Id-Ungleichheit.
Zugriffsrechte verweigert	OS-Fenster wurde abgelehnt oder noch nicht angefordert.
In der Warteschleife, aber keine gesendeten Statistiken	Plattformkredenziale sind fehlend oder deaktiviert.
Gesendet, aber keine empfangenen Statistiken	Gerät ist offline, Betriebssystem-Throttling, App wurde gezwungen, zu beenden oder Token ist ungültig.
Vordergrundbenachrichtigungen werden protokolliert, aber keine Banner	Die App ist im Vordergrund und muss ihre eigene in-app-UI anzeigen.
Hintergrund läuft nie auf iOS	Fehlende Fähigkeiten, fehlende AppDelegate-Forwarding, App wurde gezwungen, zu beenden oder Betriebssystem-Throttling.
Aktualisierungskontrolle tut nichts	Updater-Integration ist deaktiviert, keine neue Bundle, falscher Kanal oder Installationsmodus wird falsch verstanden.
Badge wird zurückgesetzt	Bei App-Start code werden Badges oder lokale und Backend-Badge-Schreibvorgänge konkurrieren.

Weitermachen aus Debugging

Nachdem sich das Gerät registriert und eine Testbenachrichtigung funktioniert hat, verwenden Sie Einstieg um Badges, Kampagnenzielsetzung und stille Updates in Ihrer Produktionsanwendung einzubinden.