Débogage

Utilisez cette checklist si une notification ne s'enregistre pas, n'arrive pas, ne s'affiche pas ou ne met pas à jour les stats Capgo.

Commencer par l'enregistrement de l'appareil

Avant de débugger le code natif, confirmez que Capgo peut voir l'appareil.

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

Vous devriez voir au moins un appareil actif avec :

• recipientKey
• deviceKey
• plateforme android ou ios
• état des permissions
• version de l'app
• version du plugin
• tags et attributs

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

Ajouter des écouteurs de debug temporaires

Ajoutez des écouteurs temporaires pendant vos tests. Supprimez les logs inutiles avant de déployer.

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

Lorsque vous débuggez avec votre équipe ou le support Capgo, collectez :

• L'ID de l'application Capgo.
• L'ID du package de l'app ou l'iOS bundle ID.
• Plateforme de l'appareil et version de l'OS.
• Version de l'application et numéro de build.
• La version du plugin.
• L'ID client externe.
• recipientKey et deviceKey Via l'enregistrement ou la recherche de destinataire.
• ID de campagne ou ID de notification.
• Si l'app était au premier plan, en arrière-plan, fermée de force ou fraîchement installée.
• Les logs de l'appareil lors de l'exécution ayant reproduit le problème.

Utiliser les logs de l'appareil

Gardez un appareil réel connecté pendant l'envoi d'une notification de test.

Sur Android :

• Ouvrez le Logcat d'Android Studio.
• Filtrez par l'ID du package de l'application.
• Surveillez la demande d'autorisation de notification, le refresh du token natif, la réception des messages et les logs du listener JavaScript.
• Si aucune notification n'apparaît, vérifiez d'abord l'importance du canal de notification et l'état des permissions sur Android 13+.

Sur iOS :

• Lancez l'application depuis Xcode sur un appareil physique.
• Ouvrez la console Xcode ou Appareils et simulateurs logs.
• Filtrez par bundle ID et CapgoNotifications.
• Confirmer AppDelegate.swift transmet les notifications distantes et que la capacité background mode est activée.

Envoyez d'abord un test en foreground, puis un test en background, puis un test de vérification de mise à jour silencieuse. Cet ordre permet de distinguer les problèmes d'écouteurs JavaScript des limites de livraison en arrière-plan de l'OS.

Problèmes d'enregistrement

CLI Setup n'est pas terminé

Exécutez la commande de setup depuis le dossier qui contient capacitor.config.*:

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

Si la commande ne peut pas inférer l'ID de votre app, passez-l’explicitement comme indiqué ci-dessus. Si l'installation du package échoue, vérifiez que le nom du package est @capgo/capacitor-notifications, vérifiez que votre registre npm est https://registry.npmjs.org, vérifiez l'accès au réseau, puis relancez la commande.

L'appareil n'apparaît pas dans la recherche de destinataire

Vérifiez :

• register est appelée une fois que votre app possède un utilisateur authentifié.
• externalId correspond à l'ID utilisateur recherché dans le dashboard.
• identityProof a été généré par votre backend pour le même appId et externalId.
• appId dans configure correspond à l'app Capgo.
• consent n'est pas configuré sur false sauf si l'utilisateur s'est désinscrit.
• L'appareil dispose d'un accès réseau à https://api.capgo.app.
• Le token push natif a été créé. Utilisez registrationChanged pour confirmer le rafraîchissement du token.

Preuve d'identité invalide

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

Ne mettez pas une preuve en cache indéfiniment et ne réutilisez pas une preuve entre plusieurs apps. Générez-la depuis votre backend après le login, renvoyez-l’à l'app, puis appelez register.

Appareil enregistré mais permission refusée

Le plugin peut enregistrer l'état de l'appareil même si l'utilisateur a refusé la permission. Vous pouvez toujours voir l'appareil, mais les notifications visibles ne s'afficheront pas.

Utilisez un écran explicatif avant le prompt du système. Expliquez ce que l'utilisateur y gagne, puis ne demandez la permission que lorsque l'action le justifie.

Problèmes de livraison

En attente mais non envoyée

Vérifiez :

• L'état des identifiants de la plateforme est configured dans Capgo.
• L'environnement du worker contient la référence de secret exacte affichée par le dashboard.
• Le package ID ou le bundle ID de l'application correspond à la configuration push de la plateforme.
• L'audience cible correspond à au moins un appareil actif.
• La campagne n'est pas limitée à un tag ou un segment que l'appareil ne possède pas.

Envoyée mais non reçue

Vérifiez :

• L'appareil est en ligne.
• L'application n'a pas été arrêtée de force par l'utilisateur.
• La permission de notification de l'OS est accordée.
• Les restrictions de batterie Android ne bloquent pas l'application pendant les tests.
• Le mode économie d'énergie d'iOS et les restrictions de rafraîchissement en arrière-plan n'affectent pas la livraison en arrière-plan.
• La notification n'a pas été remplacée par une autre notification avec le même collapse ID.

Les plateformes push natives peuvent accepter une notification et tout de même retarder, limiter, regrouper ou abandonner la livraison plus tard. Considérez les statistiques d'acceptation du fournisseur comme « acceptées pour livraison », et non comme une preuve que l'appareil l'a affichée.

Reçue mais non affichée

Vérifiez :

• L'application n'était pas au premier plan. Les notifications au premier plan sont généralement transmises au JavaScript pour que votre application puisse décider de l'interface à afficher.
• L'importance du canal de notification Android est suffisamment élevée pour afficher une alerte.
• La permission de notification Android 13+ est accordée.
• Le mode Focus iOS, le résumé des notifications ou les paramètres de notification par application ne masquent pas la notification.
• La logique de suppression des badges ou d'ouverture de l'app ne retire pas les notifications livrées lors des tests.

Problèmes de notifications en arrière-plan

Le callback en arrière-plan ne s'exécute pas

Les notifications en arrière-plan sont fournies au mieux. L'OS peut les ignorer.

Vérifiez :

• iOS a Modes d'arrière-plan > Notifications distantes activé.
• iOS AppDelegate.swift transmet les notifications distantes à CapgoNotificationsRemoteNotification.
• Testez le comportement d'iOS en arrière-plan sur un appareil physique.
• The app was not force-quit by the user.
• Le handler en arrière-plan appelle finish().
• Le code dans le callback est court, sécurisé pour le réseau et idempotent.

Sur iOS, les notifications push en arrière-plan peuvent être limitées si vous en envoyez trop, consommez trop de temps ou si l'utilisateur ouvre rarement l'application. C'est le comportement attendu de la plateforme.

Tâche en arrière-plan démarrée mais non terminée

Si les stats indiquent background_started sans background_finished, le handler JavaScript a probablement planté, a expiré ou n'a pas appelé finish().

Entourez le handler avec try/finally:

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

Problèmes de vérification silencieuse des mises à jour

Notification de vérification reçue mais aucune mise à jour installée

Vérifiez :

• @capgo/capacitor-updater est installé et configuré.
• autoUpdater est true ou enableUpdaterIntegration a été appelée.
• Les paramètres de notifications de l'app permettent de vérifier les mises à jour push.
• L'appareil cible appartient bien au canal attendu.
• L'app dispose d'un bundle plus récent dans Capgo.
• Votre mode d'installation de mise à jour est correct : next en attente du prochain redémarrage ou cycle en arrière-plan, set s'installe dès que l'updater 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 renvoie unavailable, inspectez d'abord la configuration du plugin updater.

Problèmes de badge

Vérifiez :

• La cible correspond au bon appareil lors de la recherche du destinataire.
• La plateforme prend en charge les badges d'application pour le launcher ou l'écran d'accueil testé.
• L'utilisateur n'a pas désactivé les badges dans les paramètres de notification de l'OS.
• L'application n'efface pas les badges immédiatement au démarrage.
• Vous ne mettez pas en concurrence les appels setBadge locaux avec les envois de badges du backend.

Problèmes de stats

Les stats semblent dupliquées

L'envoi de notifications suit une logique « au moins une fois ». Les réessais de la file d'attente et de la plateforme peuvent dupliquer un envoi. Utilisez les ID de notification et les collapse IDs lorsque l'action de votre app doit être idempotente.

Stats manquantes pour les anciens appareils

Le registre de l'Analytics Engine concerne les appareils actifs, pas une base de données permanente. Le plugin doit rafraîchir l'enregistrement au démarrage de l'app, au refresh du token, au changement d'ID externe, et périodiquement avant la fin de la fenêtre de rétention des appareils actifs.

Événements d'ouverture manquants

Vérifiez :

• La notification inclut un identifiant stable id.
• notificationOpened un listener est enregistré au démarrage de l'app.
• L'app ne remplace pas le flux d'ouverture natif par un code personnalisé avant que le plugin ne le voie.
• L'utilisateur a bien appuyé sur la notification plutôt que d'ouvrir l'app manuellement.

Commandes de debug API

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

Lire les 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 foreground :

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 racines courantes

Symptôme	Cause probable
Appareil absent de la recherche	register non appelé, erreur de preuve, consentement refusé, ID d'application incorrect.
Permission refusée	Prompt de l'OS refusé ou pas encore demandé.
En attente mais aucune statistique d'envoi	Les identifiants de la plateforme sont manquants ou désactivés.
Envoyé mais aucune statistique de réception	Appareil hors ligne, limitation de l'OS, application arrêtée de force ou token invalide.
Logs de notification en foreground mais pas de bannière	L'application est au premier plan et doit afficher sa propre interface in-app.
Le mode background ne fonctionne jamais sur iOS	Capabilities manquantes, redirection AppDelegate manquante, application quittée de force ou limitation de l'OS.
La vérification de mise à jour ne fait rien	L'intégration de l'updater est désactivée : aucun bundle plus récent, mauvais canal ou mode d'installation incorrect.
Réinitialisation du badge	Le démarrage de l'application code efface les badges ou conflit d'écriture entre le local et le backend.

Continuer depuis Débogage

Une fois que l'appareil est enregistré et qu'une notification de test fonctionne, utilisez Prise en main to wire badges, campaign targeting, and silent update checks into your production app.