Debugging

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

Mit dem Geräte-Record beginnen

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

1. Öffnen Sie die App und melden Sie sich als Benutzer an, den Sie testen möchten.
2. Call CapgoNotifications.register(...) In __CAPGO_KEEP_0__, öffnen Sie
3. In Capgo, öffnen Benachrichtigungen > Empfängerauflösung.
4. Sie sollten mindestens ein aktives Gerät mit:

Sie sollten mindestens ein aktives Gerät mit:

• recipientKey
• deviceKey
• Plattform android oder ios
• Zustimmungsstatus
• Anwendungsversion
• Pluginversion
• Tags und Attribute

If lookup returns no device, the send path cannot target that user.

Hinzufügen temporärer Debug-Hörer

Hinzufügen temporärer Hörer bei der Testung. Löschung von lauten Log-Einträgen vor der Veröffentlichung.

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

Dieses Informationen sammeln

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

• Capgo-App-ID.
• App-Paket-ID oder iOS-Bundle-ID.
• Geräteplattform und Betriebssystemversion.
• App-Version und Buildnummer.
• Plugin-Version.
• 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 Zwangs-Schließen oder frisch installiert war.
• Geräteprotokolle vom Ausführungszyklus, der das Problem reproduzierte.

Benutze Geräteprotokolle

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

Auf Android:

• Öffnen Sie Android Studio Logcat.
• Filtern Sie nach der App-Paket-ID.
• Beobachten Sie die Benachrichtigungsrechteanfrage, die native Token-Refresh, die Nachrichtenempfangs- und die JavaScript-Listener-Protokolle.
• Wenn eine sichtbare Benachrichtigung nicht erscheint, überprüfen Sie zunächst die Benachrichtigungs-Kanal-Wichtigkeit und den Android 13+-Rechtezustand.

Auf iOS:

• Laufen 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 AppDelegate.swift für die Weiterleitung von Remotebenachrichtigungen und die Aktivierung der Hintergrundfähigkeit.

Senden Sie zunächst einen Vordergrundtest, dann einen Hintergrundtest und schließlich einen stillen Update-Prüfungstest. Diese Reihenfolge trennt JavaScript-Listener-Probleme von OS-Hintergrundlieferungsgrenzen.

Registrierungsprobleme

CLI-Einrichtung ist nicht abgeschlossen

Führen Sie den Einrichtungsbefehl im Ordner aus, der die capacitor.config.*:

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

If der Befehl kann nicht Ihre App-ID ermitteln, 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 den Netzwerkzugriff, dann wiederholen Sie den Befehl.

Gerät erscheint nicht in Empfängerabfrage

Check:

• register wird nachdem Ihr App eine authentifizierte Benutzer hat.
• externalId entspricht der Benutzer-ID, die Sie in der Dashboard suchen.
• identityProof war von Ihrem Backend für das gleiche appId und externalId.
• appId in configure passt dem Capgo-App entspricht.
• consent ist nicht auf false es sei denn, der Benutzer hat sich abgemeldet.
• Der Gerät hat Zugriff auf das Netzwerk zu 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 das Capgo-App-Id und externe ID gebunden. Wenn sich entweder der Wert ändert, muss ein neuer Beweis erstellt werden.

Stellen Sie keinen Beweis 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 zurück und rufen Sie register.

Gerät Registriert, aber Berechtigung abgelehnt

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

Zustellungsschwierigkeiten

Angefangen, aber nicht gesendet

Check:

• Die Plattformkreditstatus ist configured auf Capgo.
• Die Arbeiterumgebung enthält den genauen geheimen Referenzwert, der durch das 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 Benachrichtigungsrechte der Betriebssysteme sind erteilt.
• Android-Batteriebeschränkungen blockieren das Gerät 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 demselben Zusammenbruch-ID ersetzt.

Nativ-Push-Plattformen können eine Benachrichtigung annehmen und die Lieferung später verzögern, einschränken, konsolidieren oder abbrechen. Behandle 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

Check:

• Die App war nicht im Vordergrund. Benachrichtigungen im Vordergrund werden normalerweise an JavaScript gesendet, damit Ihre App entscheiden kann, welche Benutzeroberfläche angezeigt werden soll.
• Die Android-Benachrichtigungs-Kanalwichtigkeit ist hoch genug, um eine Warnung anzuzeigen.
• Die Android-13+-Benachrichtigungsberechtigung ist erteilt.
• iOS-Fokus, Benachrichtigungsübersicht oder Einstellungen für Benachrichtigungen pro App verbergen die Benachrichtigung nicht.
• Badge-Entfernung oder App-Öffnen-Logik entfernt während der Testung nicht gelieferte Benachrichtigungen.

Hintergrundbenachrichtigungsprobleme

Hintergrundaufruf wird nicht ausgeführt

Background notifications are best-effort. The OS can skip them.

Check:

• iOS hat Background-Modi > Remote-Nachrichten aktiviert.
• iOS AppDelegate.swift überträgt 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, Netzwerk-sicher und idempotent.

Bei iOS können Hintergrund-Pushes 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 anzeigen background_started ohne background_finished, hat der JavaScript-Handler wahrscheinlich geworfen, abgelaufen oder 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 Check Notification Arrives But No Update Installs

Check:

• @capgo/capacitor-updater ist installiert und konfiguriert.
• autoUpdater ob true oder enableUpdaterIntegration wurde genannt.
• Die Benachrichtigungs-Einstellungen der App ermöglichen Push-Update-Überprüfungen.
• Das Zielgerät gehört zum Kanal, den Sie erwarten.
• Die App hat ein neueres Bundle in Capgo verfügbar.
• Ihr Update-Installationsmodus ist korrekt: next Warteschlangen für das nächste Neustarten oder Hintergrundzyklus. set installiert, sobald der Updater es sicher tun kann.

Run a manual check while the app is open:

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

console.log(result)

Wenn der manuelle Check zurückgibt unavailable, inspect the updater plugin setup first.

Pinselprobleme

Check:

• Die Zieladresse verweist auf das richtige Gerät im Empfängerlookup.
• Die Plattform unterstützt App-Pinsel für den Launcher oder die Startseite, die getestet wird.
• The user has not disabled badges in OS notification settings.
• Die App löscht die Pinsel nicht sofort beim Start.
• Sie führen keine lokalen Aufrufe gegen Hintergrund-Pinsel-Sendungen aus. setBadge Anfragen an den Backend senden.

Abschnitt mit dem Titel „Statistikprobleme“

Statistiken Doppelte Anzeige

Notification sending is at-least-once. Queue retry and platform retry can duplicate a send. Use notification IDs and collapse IDs when your app action must be idempotent.

Stats 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, externer ID-Änderung und periodisch vor dem Aktiv-Gerät-Retentionsfenster aktualisieren.

Offene Ereignisse fehlen

Check:

• Die Benachrichtigung enthält eine stabile id.
• notificationOpened Der Listener wird während der App-Startzeit registriert.
• Die App ersetzt die native offene Fluss nicht mit einem benutzerdefinierten code vor der Plugin-Sicht.
• Der Benutzer hat die Benachrichtigung tatsächlich angeklickt 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"
  }'

Read stats:

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, App-Id-Ungleichheit.
Zugriffsrechte verweigert	OS-Fenster verweigert oder noch nicht angefordert.
In der Warteschleife, aber keine gesendeten Statistiken	Plattformkredenziale fehlen oder sind deaktiviert.
Gesendet, aber keine empfangenen Statistiken	Gerät ist offline, OS-Throttling, App wurde gezwungen beendet oder Token ist ungültig.
Foreground notification logs but no 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, Zwangsfreigabe der App oder Betriebssystem-Throttling.
Aktualisierungsprüfung tut nichts.	Updater-Integration deaktiviert, kein neuer Bundle, falscher Kanal oder Installationsmodus verstanden.
Abzeichen resetten.	App-Start code löscht Abzeichen oder lokale und Backend-Abzeichen-Schreibe-Rennen.

Weitermachen von Debugging.

Nachdem das Gerät registriert ist und eine Testbenachrichtigung funktioniert, verwenden Sie Getting Started um Abzeichen, Kampagnenzielsetzung und stumme Aktualisierungsprüfungen in Ihre Produktionsanwendung einzubinden.