Fehlerbehebung

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-Identifikator.

Sie sollten mindestens einen aktiven Gerät mit:

• recipientKey
• deviceKey
• Plattform android oder ios
• Die Plattform oder die App-Version
• Berechtigungsstatus
• App-Version
• Plugin-Version

Tags und Attribute

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

Während des Testens temporäre Hörer hinzufügen. Lauter Log-Ausgaben vor der Veröffentlichung entfernen.

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 mit Ihrem Team oder Capgo-Support bei der Fehlerbehebung sind, sammeln Sie:

• Capgo-Anwendungs-ID.
• App-Paket-ID oder iOS-Bundle-ID.
• Geräteplattform und Betriebssystemversion.
• App-Version und Buildnummer.
• Plugin-Version.
• Externes Kunden-ID.
• recipientKey und deviceKey oder aus der Empfängerliste.
• Kampagnen-ID oder Benachrichtigungs-ID.
• Ob die App im Vordergrund, Hintergrund, durch Zwangsschließen 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 Paket-ID der App.
• Beobachten Sie die Anzeige der Benachrichtigungsrechte, die 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 Hintergrundfunktion aktiviert ist. AppDelegate.swift Senden Sie zunächst einen Vordergrund-Test, dann einen Hintergrund-Test, dann einen stummen Update-Prüfungstest. Diese Reihenfolge trennt JavaScript-Listener-Probleme von OS-Hintergrundlieferungsgrenzen.

Registrierungsprobleme

Abschnitt mit dem Titel „Registrierungsprobleme“

CLI Setup Did Not Finish

Führen Sie die Setup-Befehlsausführung 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 Empfängerlookup

Überprüfen Sie:

• register wird nachdem Ihr App einen authentifizierten 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 in configure entspricht der Capgo-App.
• consent ist nicht auf false solange der Benutzer sich nicht abgemeldet hat.
• Der Gerät hat Zugriff auf das Netzwerk https://api.capgo.app.
• Der native Push-Token wurde erstellt. Verwenden Sie registrationChanged zur Bestätigung der Token-Refresh.

Ungültige Identitätsbeweis

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

Machen Sie keinen Beweis für immer im Cache oder wiederholen Sie einen Beweis über Apps. Erzeugen Sie ihn auf Ihrem Backend nach der Anmeldung, geben Sie ihn an die App weiter und rufen Sie register.

Gerät registriert, aber Berechtigung verweigert

Das Plugin kann den Gerätestatus 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 Berechtigungsanleitungsschleife vor dem Betriebssystem-Fenster. Erklären Sie dem Benutzer, was er erhält, und fragen Sie nach der Berechtigung nur dann, wenn der Aktionssinn Sinn ergibt.

Zustellungsprobleme

Angekündigt, aber nicht gesendet

Überprüfen Sie:

• Die Plattformkreditstatus ist configured auf Capgo.
• Die Worker-Umgebung enthält den genauen geheimen Referenzzeiger, der vom Dashboard angezeigt wird.
• Die Paket- oder Bundle-ID im App entspricht der Plattform-Einstellung 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 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 der gleichen Zusammenbruch-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-Benachrichtigungschannel-Wichtigkeit 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ächen zum Löschen von Badges oder die Logik zum Öffnen der App entfernen während der Tests nicht die gelieferten Benachrichtigungen.

Probleme mit Hintergrundbenachrichtigungen

Hintergrundaufruf läuft nicht

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

Überprüfe:

• iOS hat Hintergrundmodi > 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().
• Arbeite innerhalb des Callbacks kurz, sicher im Netzwerk 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_finisheddass der JavaScript-Handler geworfen, abgelaufen oder nicht aufgerufen hat finish().

Fügen 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

Aktualisierungsprüfungsbenachrichtigung kommt an, aber keine Aktualisierung installiert

Überprüfen Sie:

• @capgo/capacitor-updater ist installiert und konfiguriert.
• 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 warten Sie für das nächste Neustart oder Hintergrundzyklus

installiert es, 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 zunächst die Einstellungen des Updater-Plugins.

Badge-Probleme

Überprüfen Sie:

• Die Zieladresse verweist auf das richtige Gerät im Empfänger-lookup.
• Die Plattform unterstützt App-Badges für den Launcher oder die Startseite, die getestet wird.
• Der Benutzer hat Badge in den Einstellungen für Benachrichtigungen in der Betriebssysteme nicht deaktiviert.
• Die App löscht die Badges nicht sofort bei dem Start.
• Sie rufen lokale setBadge Aufrufe nicht gegen den Hintergrund-Badge-Sendungen.

Statistik Probleme

Statistik Aussehen Dupliziert

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

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

Offene Ereignisse fehlen

Überprüfen Sie:

• Die Benachrichtigung enthält eine stabile id.
• notificationOpened Der Listener wird während der App-Startzeit registriert.
• Die App ersetzt den nativen Open-Flow nicht durch einen benutzerdefinierten code bevor der Plugin ihn sieht.
• Der Benutzer hat tatsächlich auf die Benachrichtigung getippt und nicht die App manuell geöffnet.

API Debug-Befehle

Suche nach einem 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 in der Suche	register nicht aufgerufen, Beweisungleichheit, Zustimmung falsch, Anwendungs-ID fehlt.
Zugriff verweigert	Befehlszeile des Betriebssystems wurde abgelehnt oder wurde noch nicht angefordert.
In der Warteschleife, aber keine gesendeten Statistiken	Plattformkredenziale sind fehlend oder deaktiviert.
Gesendet, aber keine Empfangsstatistiken	Gerät ist offline, Betriebssystem-Throttling, Anwendung wurde abgebrochen oder Token ist ungültig.
Vordergrundbenachrichtigungen werden protokolliert, aber keine Banner	Die Anwendung ist im Vordergrund und muss ihre eigene in-app-UI anzeigen.
Hintergrund läuft nie auf iOS	Fehlende Berechtigungen, fehlende AppDelegate-Forwarding, Anwendung wurde abgebrochen oder Betriebssystem-Throttling.
Aktualisierung überprüft nichts	Updater-Integration deaktiviert, kein neuer 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 rassen.

Weitermachen von Debugging

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