Debugging

Utilisez ce tableau de bord lorsqu'une notification ne s'enregistre pas, ne parvient pas, ne s'affiche pas ou ne met pas à jour les statistiques Capgo.

Commencez par le registre du dispositif

Avant de déboguer le code natif, assurez-vous que Capgo peut voir le dispositif.

1. Open the app and sign in as the user you want to test.
2. Appeler CapgoNotifications.register(...) après la connexion.
3. Dans Capgo, ouvrez Notifications > Recherche de destinataires.
4. Recherchez par le même ID client externe.

Vous devriez voir au moins un appareil actif avec :

• recipientKey
• deviceKey
• plateforme android ou ios
• état de permission
• état de permission
• version de l'application
• version du plugin

Si la recherche ne trouve aucun appareil, le chemin d'envoi ne peut pas cibler cet utilisateur.

Ajouter des Écouteurs de Débogage Temporaires

Section intitulée “Ajoutez des Écouteurs de Débogage Temporaires”

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

Collecter ces informations

Lors du débogage avec votre équipe ou le Capgo support, collectez :

• L'ID de l'application Capgo.
• L'ID de package de l'application ou l'ID de bundle iOS.
• Plateforme et version du système d'exploitation de l'appareil.
• Version et numéro de build de l'application.
• Version du plugin.
• ID client externe.
• recipientKey et deviceKey from registration or recipient lookup.
• ID de campagne ou ID de notification.
• Indiquez si l'application était en avant-plan, en arrière-plan, fermée par force ou récemment installée.
• Journal du dispositif provenant de l'exécution qui a reproduit le problème.

Utiliser les journaux du dispositif

Conservez un appareil réel connecté tout en envoyant une notification de test.

Sur Android :

• Ouvrez le journal de Logcat d'Android Studio.
• Filtrez par l'ID du package de l'application.
• Observez les journaux de demande de permission de notification, de mise à jour native, de réception de message et de listener JavaScript.
• Si une notification visible ne s'affiche pas, inspectez d'abord l'importance du canal de notification et l'état de la permission d'Android 13+.

Sur iOS :

• Exécutez l'application à partir de Xcode sur un appareil physique.
• Ouvrez la console Xcode ou Appareils et Simulateurs les journaux.
• Filtrez par l'ID de bundle et CapgoNotifications.
• Confirmez AppDelegate.swift Les notifications à distance sont transmises et le mode de fond est activé.

Envoyez d'abord une notification de test en avant-plan, puis une notification de test en arrière-plan, puis une mise à jour silencieuse de vérification.

Problèmes d'inscription

CLI Installation n'a pas été terminée

Exécutez la commande de configuration à partir du dossier qui contient capacitor.config.*:

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

Si la commande ne peut pas déduire votre ID d'application, passez-l’explicitement comme montré ci-dessus. Si l'installation de package échoue, confirmez que le nom de package est @capgo/capacitor-notificationsvérifiez que votre registre npm est https://registry.npmjs.orgvérifiez l'accès réseau, puis réexécutez la commande.

Le Dispositif N'apparaît Pas Dans La Recherche De Destinataires

Vérifiez :

• register est appelé après que votre application ait un utilisateur authentifié.
• externalId matches the user ID you search in the dashboard.
• identityProof a été créé par votre serveur backend pour le même appId et externalId.
• appId dans configure correspond à l'application Capgo.
• consent n'est pas configuré pour false sauf si l'utilisateur a opté pour la désactivation.
• Le dispositif a accès au réseau https://api.capgo.app.
• Le jeton de notification natif a été créé. Utilisez registrationChanged pour confirmer le renouvellement du jeton.

Preuve d'identité non valide

La preuve est liée à l'ID de l'application Capgo et à l'ID externe. Si l'une de ces valeurs change, générer une nouvelle preuve.

N'écrivez pas une preuve éternellement dans le cache ou réutilisez une preuve entre applications. Générez-l’à partir de votre serveur après connexion, renvoyez-l’à l'application et appelez register.

Enregistrement du Dispositif Mais Refus de Permission

Le plugin peut enregistrer l'état du dispositif même si l'utilisateur a refusé la permission. Vous pouvez toujours voir le dispositif, mais les notifications visibles ne seront pas affichées.

Utilisez un écran de rappel de permission avant la prompt du système. Expliquez ce que l'utilisateur obtient, puis demandez la permission uniquement lorsque l'action a du sens.

Problèmes de Livraison

Non Envoyé Mais En File d'Attente

Vérifiez :

• L'état des informations de plateforme est configured en Capgo.
• L'environnement de travail contient la référence exacte du secret affichée par le tableau de bord.
• The package ID or bundle ID in the app matches the platform push setup.
• La cible du public se résout à au moins un appareil actif.
• La campagne n'est pas limitée à une étiquette ou un segment que l'appareil ne possède pas.

Envoyé Mais Non Réceptionné

Vérifiez :

• L'appareil est en ligne.
• L'application n'a pas été arrêtée par l'utilisateur.
• La permission de notification de l'OS est accordée.
• Les restrictions de batterie d'Android ne bloquent pas l'application pendant les tests.
• iOS Mode faible sur puissance et restrictions de mise à jour de fond ne touchent pas la livraison de fond.
• La notification n'a pas été remplacée par une autre notification ayant le même ID de collapsage.

Les plateformes de push native peuvent accepter une notification et retarder, limiter, coaguler ou supprimer la livraison ultérieurement. Traitez les statistiques acceptées par le fournisseur comme « acceptées pour livraison », et non comme preuve que le dispositif l'a affiché.

Reçue Mais Non Affichée

Vérifiez :

• L'application n'était pas en avant-plan. Les notifications en avant-plan sont généralement livrées à JavaScript afin que votre application puisse décider quel UI afficher.
• L'importance du canal de notification Android est suffisamment élevée pour afficher un avertissement.
• La permission de notification Android 13+ est accordée.
• Les paramètres de notification iOS Focus, de résumé de notification ou de notification par application ne masquent pas la notification.
• La logique de suppression de badge ou d'ouverture de l'application n'enlève pas les notifications livrées pendant les tests.

Problèmes de notifications en arrière-plan

La Fonction d'appel de fond ne s'exécute pas

Les notifications de fond sont des tentatives. Le système d'exploitation peut les ignorer.

Vérifiez :

• iOS a Modes de fond > Notifications à distance activé.
• iOS AppDelegate.swift envoie les notifications à distance à CapgoNotificationsRemoteNotification.
• Vous testez le comportement de fond d'iOS sur un appareil physique.
• L'application n'a pas été fermée par l'utilisateur.
• Le gestionnaire de fond appelle finish().
• Travaillez à l'intérieur de l'appel, il est court, sans risque réseau et idempotent.

On iOS, les pushs de fond peuvent être ralenties si vous en envoyez trop, si vous utilisez trop de temps, ou si l'utilisateur ouvre rarement l'application. C'est un comportement de plateforme attendu.

Envoi de fond démarré mais non terminé

Si les statistiques montrent background_started sans background_finished, the JavaScript handler likely threw, timed out, or did not call finish().

Enveloppez le gestionnaire dans try/finally:

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

Problèmes de Contrôle de Mise à Jour Silencieux

Mise à jour de Contrôl’Arrive Mais Pas de Mise à jour Installe

Vérifiez :

• @capgo/capacitor-updater est installé et configuré.
• autoUpdater est true ou enableUpdaterIntegration était appelée.
• The app’s Notifications settings allow push update checks.
• Le dispositif cible appartient au canal que vous attendez.
• The app has a newer bundle available in Capgo.
• Votre mode d'installation de mise à jour est correct. next Files d'attente pour le prochain redémarrage ou cycle de fond. set s'installe dès que l'actualiseur peut le faire en toute sécurité.

Run a manual check while the app is open:

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

console.log(result)

Si la vérification manuelle retourne unavailableInspectez d'abord la configuration du plugin de mise à jour.

Problèmes de badge

Vérifiez :

• La cible se résout vers le bon appareil dans la recherche de destinataires.
• La plateforme prend en charge les badges d'application pour le lanceur ou l'écran d'accueil testé.
• L'utilisateur n'a pas désactivé les badges dans les paramètres de notification du système.
• L'application ne supprime pas les badges immédiatement au démarrage.
• Vous n'êtes pas en train de développer localement. setBadge aux envois de badges backend.

Problèmes de Statistiques

Stats Regardent Dupliqués

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 Are Missing For Old Devices

Le registre de l'Engine d'Analytique est pour les appareils actifs, pas une base de données à vie éternelle. Le plugin devrait rafraîchir l'enregistrement à l'ouverture de l'application, à la mise à jour du jeton, à la modification de l'ID externe et périodiquement avant la fenêtre de conservation des appareils actifs.

Les Événements Ouverts Manquent

Vérifiez :

• La notification inclut une version stable id.
• notificationOpened Le listener est enregistré lors du démarrage de l'application.
• Le l'application ne remplace pas le flux d'ouverture native par un code personnalisé avant que le plugin ne le voie.
• L’utilisateur a vraiment cliqué sur la notification plutôt que d'ouvrir l'application manuellement.

API Commandes de débogage

Recherchez un destinataire :

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'

Envoyer un test en avant-plan :

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

Causes de racines communes

Symptôme	Cause probable
Appareil manquant dans la recherche	register pas appelé, preuve de non-conformité, consentement faux, ID d'application en désaccord.
Accès refusé	Demande de l'OS refusée ou non demandée encore.
En file d'attente mais pas de statistiques envoyées	Les informations de plateforme manquent ou sont désactivées.
Envoyé mais pas de statistiques reçues	Device offline, OS throttling, app force-stopped, or token invalid.
Journal des notifications en avant-plan mais pas de bannière	App is foregrounded and must show its own in-app UI.
Le background ne fonctionne jamais sur iOS	Capacités manquantes, AppDelegate non transmis, fermeture de l'application forcé, ou ralentissement du système.
La mise à jour n'est pas effectuée.	L'intégration de l'actualiseur est désactivée, pas de nouvelle version disponible ou canal incorrect.
Badge de réinitialisation	App startup code clears badges or local and backend badge writes race.

Continuez de la section de débogage

Après que le dispositif s'est inscrit et qu'une notification de test fonctionne, utilisez Prise en main to wire badges, campaign targeting, and silent update checks into your production app.