Fehlersuche

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ä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
• Zustand der Berechtigung
• App-Version
• Plugin-Version

Schlüsselwörter und Attribute

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

Fügen Sie während des Testens temporäre Hörer hinzu. Entfernen Sie lästige Protokolle, bevor Sie es verschicken.

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 bei der Debugging 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.
• Pluginversion.
• Außenliegende Kunden-ID.
• recipientKey und deviceKey aus der Registrierung oder dem Empfängerabruf.
• Kampagnen-ID oder Benachrichtigungs-ID.
• Ob die App im Vordergrund, Hintergrund, durch Zwangsbeendigung oder neu installiert war.
• Geräteprotokolle vom Ausführungsrun, das das Problem reproduzierte.

Geräteprotokolle verwenden

Verwenden Sie ein echtes Gerät, während Sie eine Testbenachrichtigung senden.

Bei Android:

• Öffnen Sie Android Studio Logcat.
• Filtern Sie nach der App-Paket-ID.
• Achten Sie auf 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 die Hintergrundmodus-Fähigkeit aktiviert sind. AppDelegate.swift Senden Sie zunächst einen Vordergrund-Test, dann einen Hintergrund-Test und schließlich einen stillen Update-Prüfungstest. Diese Reihenfolge trennt JavaScript-Hörer-Probleme von OS-Hintergrundlieferungsgrenzen.

Registrierungsprobleme

Abschnitt mit dem Titel „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 erneut aus.

Gerät erscheint nicht in Empfänger-Überprüfung

Überprüfen Sie:

• register wird nach der Authentifizierung eines Benutzers in Ihrer App aufgerufen.
• externalId stimmt mit der im Dashboard gesuchten Benutzer-ID überein.
• identityProof wurde von Ihrem Backend für das gleiche appId und externalId.
• appId in configure entspricht der Capgo-App.
• consent wird nicht auf false es sei denn der Benutzer hat sich abgemeldet.
• Das 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 der Capgo-App-ID und der externen ID zugeordnet. Wenn sich entweder der Wert ändert, erstellen Sie einen neuen Beweis.

Stellen Sie einen Beweis nicht für immer im Cache oder wiederholen Sie einen Beweis über Apps. Erstellen Sie ihn auf Ihrem Backend nach dem Login, geben Sie ihn an die App weiter 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 Berechtigungsvorabinformationsschleife vor dem Betriebssystemanzeige. 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:

• Die Plattformkreditstatus 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 bestimmte 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 Hintergrund-Refresh-Beschrä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-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ächen zum Löschen von Badges oder die Logik zum Öffnen der App entfernen während der Testphase 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 das 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 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 es wahrscheinlich, dass der JavaScript-Handler ausgelöst, abgelaufen oder nicht aufgerufen wurde 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()
  }
})

Probleme bei stummen Update-Überprüfungen

Benachrichtigung über Update-Überprüfung kommt, aber kein Update installiert wird

Ü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 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 Homescreen, die getestet werden.
• Der Benutzer hat Badge in den Einstellungen für Benachrichtigungen des Betriebssystems nicht deaktiviert.
• Die App löscht die Badges nicht sofort bei dem Start.
• Sie rufen lokale setBadge Aufrufe nicht gegen Hintergrund-Aktionen zum Versenden von Badges.

Statistik Probleme

Statistik Aussehen Dupliziert

Die Benachrichtigungsversendung 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 Sichtbar 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 auf App-Start, Token-Refresh, Änderung der externen ID und regelmäßig vor dem Aktivgeräte-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 durch einen 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 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"
  }'

Lesen Sie 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 verwehrt	OS-Fenster wurde abgelehnt oder wurde noch nicht angefordert.
In der Warteschleife, aber keine gesendeten Statistiken	Plattformkredenziale fehlen oder sind deaktiviert.
Gesendet, aber keine Empfangsstatistiken	Gerät offline, Betriebssystem-Throttling, Anwendung abgebrochen oder Token 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 Fähigkeiten, fehlende AppDelegate-Forwarding, Anwendung abgebrochen oder Betriebssystem-Throttling.
Aktualisierungskontrolle tut nichts	Updater-Integration deaktiviert, keine neueren Bundle, falscher Kanal oder Installationsmodus missverstanden.
Abzeichen zurücksetzen	Bei der App-Start code werden Abzeichen oder lokale und Backend-Abzeichen-Schreibvorgänge rasseln.

Weitermachen von Debugging

Nachdem sich das Gerät registriert und eine Testbenachrichtigung funktioniert, verwenden Sie Anleitung zum Starten um Badges, Kampagnenzielsetzung und stille Update-Überprüfungen in Ihrer Produktionsanwendung einzubinden.