Dégagement

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 de l'appareil

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

1. Ouvrez l'application et connectez-vous en tant qu'utilisateur que vous souhaitez tester.
2. Appel CapgoNotifications.register(...) après la connexion.
3. Dans Capgo, ouvrez Notifications > Recherche de destinataires.
4. Recherchez en fonction du même ID client externe.

Vous devriez voir au moins un appareil actif avec :

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

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

Ajouter des Écouteurs de Débogage Temporaires

Ajouter des écouteurs temporaires pendant le test. Supprimer les journaux bruyants avant la mise en production.

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

Collectez Cette Information

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

• Capgo ID de l'application.
• ID de package de l'application ou 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 à partir de l'enregistrement ou de la recherche de destinataire.
• ID de campagne ou ID de notification.
• Quelle que soit l'état de l'application, en avant-plan, en arrière-plan, fermée par force ou fraîchement installée.
• Les journaux 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 Logcat d'Android Studio.
• Filtrez par l'ID du package de l'application.
• Voyez les journaux de la demande de permission de notification, de la mise à jour du jeton natif, de la réception de message et des écouteurs JavaScript.
• Si une notification visible ne s'affiche pas, inspectez d'abord l'importance de la chaîne 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.
• Confirmer AppDelegate.swift envoie des notifications à distance et que la capacité de mode de fond est activée.

Envoyez d'abord un test de fond d'écran, puis un test de fond, puis un test de mise à jour silencieuse. Cette séquence sépare les problèmes de listeners JavaScript des limites de livraison de fond de l'OS.

Problèmes d'inscription

CLI Configuration N'a Pas Terminé

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

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

Si le commandement ne peut pas inférer votre ID d'application, passez-le explicitement comme indiqué ci-dessus. Si l'installation du package échoue, confirmez que Capgo a activé l'accès aux packages Preview privé pour votre compte npm, puis réexécutez la commande.

L'appareil ne s'affiche pas dans la recherche de destinataires

Vérifiez :

• register est appelé après que votre application ait un utilisateur authentifié.
• externalId correspond à l'ID d'utilisateur que vous recherchez dans le tableau de bord.
• identityProof a été créé par votre serveur backend pour la même appId et externalId.
• appId dans configure correspond à l'application Capgo.
• consent n'est pas défini false sauf si l'utilisateur a opté pour la non-participation.
• 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 d'application Capgo et à l'ID externe. Si l'une de ces valeurs change, créez une nouvelle preuve.

N'écrivez pas une preuve en cache pour toujours ou réutilisez une preuve entre applications. Créez-la à partir de votre serveur backend après connexion, renvoyez-la à l'application et appelez register.

Le dispositif est enregistré mais a refusé la 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 premier pas de permission avant la demande de l'OS. Expliquez ce que l'utilisateur obtient, puis demandez la permission uniquement lorsque l'action a du sens.

Problèmes de livraison

En file d'attente mais pas envoyé

Vérifiez :

• L'état des credentials de la plateforme est configured sur Capgo.
• L'environnement de travail contient la référence secrète exacte affichée par le tableau de bord.
• L'ID du package ou l'ID de l'ensemble du bundle dans l'application correspond à la configuration de la plateforme de push.
• L'audience cible 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.

Non Envoyé Mais Réceptionné

Vérifier :

• Le dispositif est en ligne.
• L'application n'a pas été arrêtée par l'utilisateur.
• La permission de notification du système d'exploitation est accordée.
• Les restrictions de batterie d'Android ne bloquent pas l'application lors des tests.
• Les restrictions de mode faible consommation d'iOS et de mise à jour de fond ne touchent pas la livraison de fond.
• La notification n'a pas été remplacée par une autre notification avec le même ID de collapsage.

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

Réceptionné Mais Non Affiché

Vérifiez :

• L'application n'était pas en avant-plan. Les notifications en avant-plan sont généralement envoyé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 par application ne masquent pas la notification.
• La logique de nettoyage de la vignette 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 notification en arrière-plan ne s'exécute pas.

Les notifications en arrière-plan sont des meilleures intentions. Le système peut les ignorer.

Vérifiez :

• iOS a Modes d'exécution en arrière-plan > Notifications à distance __CAPGO_KEEP_0__.
• iOS AppDelegate.swift transfère les notifications à distance vers CapgoNotificationsRemoteNotification.
• Vous testez le comportement en arrière-plan d'iOS sur un appareil physique.
• L'application n'a pas été fermée par l'utilisateur.
• Le gestionnaire en arrière-plan appelle finish().
• Travaillez à l'intérieur de l'appel de retour, il est court, sans risque réseau et idempotent.

Sur iOS, les push en arrière-plan peuvent être ralentis si vous en envoyez trop, utilisez trop de temps ou que l'utilisateur ouvre rarement l'application. C'est un comportement de plateforme attendu.

Démarré en Arrière-plan Mais Pas Terminé

If stats montrent background_started sans background_finished, le gestionnaire JavaScript a probablement lancé une erreur, s'est arrêté ou n'a pas appelé 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 vérification silencieuse

La notification de vérification arrive mais aucune mise à jour n'est installée

Vérifiez :

• @capgo/capacitor-updater est installé et configuré.
• autoUpdater est true ou a été appelé. enableUpdaterIntegration Les paramètres de notifications de l'application permettent de vérifier les mises à jour.
• Le dispositif cible appartient au canal que vous attendez.
• L'application dispose d'une mise à jour de bundle plus récente dans __CAPGO_KEEP_0__.
• The app has a newer bundle available in Capgo.
• s'aligne sur le prochain redémarrage ou cycle de fond, next s'installe dès que l'actualiseur peut le faire en toute sécurité. set Effectuez une vérification manuelle tout en ouvrant l'application :

Copier dans le presse-papiers

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

console.log(result)

Inspectez d'abord la configuration du plugin d'actualiseur. unavailableSi la vérification manuelle renvoie une erreur, inspectez d'abord la configuration du plugin d'actualiseur.

Problèmes de Badge

Vérifiez :

• La cible se résout vers le bon appareil dans la recherche de destinataire.
• 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 faire courir des appels locaux contre les envois de badges backend. setBadge Problèmes de Stats

Section intitulée “Problèmes de Stats”

Vérifiez les stats pour les dupliquer

L'envoi de notifications est au moins une fois. La file d'attente de réessai et la réessai de plateforme peuvent dupliquer une envoi. Utilisez les identifiants de notification et les identifiants de collapsage lorsque votre action d'application doit être idempotente.

Les Statistiques Manquent Pour Les Anciens Appareils

Le registre de l'Engine d'Analytique est pour les appareils actifs, pas une base de données à vie. Le plugin devrait rafraîchir l'enregistrement à l'ouverture de l'application, à la mise à jour du jeton, au changement 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 un stable id.
• notificationOpened Le listener est enregistré lors de l'ouverture de l'application.
• L'application ne remplace pas la navigation native par un code personnalisé avant que le plugin ne le voit.
• L'utilisateur a vraiment cliqué sur la notification plutôt que d'ouvrir l'application manuellement.

API Commandes de débogage

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 statistiques :

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 incohérente, consentement faux, ID d'application incohérent.
Droits refusés	Invite de système d'exploitation refusé ou non demandé encore.
En file d'attente mais pas de statistiques envoyées	Les informations de connexion de la plateforme sont manquantes ou désactivées.
Envoyé mais pas de statistiques reçues	L'appareil est hors ligne, le système d'exploitation applique un surcroît de charge, l'application est arrêtée par force ou le jeton est invalide.
Journalisation des notifications de fond mais pas de bannières	L'application est en avant-plan et doit afficher son propre interface utilisateur en application.
Le background ne s'exécute jamais sur iOS	Capacités manquantes, AppDelegate de passage manquant, fermeture de l'application ou ralentissement du système par l'OS.
La vérification de mise à jour ne fait rien	L'intégration de l'actualiseur est désactivée, pas de bundle plus récent, mauvais canal ou mode d'installation mal compris.
L'indicateur de notification est réinitialisé	Lorsque l'application démarre en mode code, les indicateurs de notification ou les écritures locales et backend des indicateurs de notification se chevauchent.

Continuez de la phase de débogage

Après que le périphérique s'est inscrit et que la notification de test fonctionne, utilisez Commencer pour brancher les indicateurs de notification, la ciblage de campagne et les vérifications de mise à jour silencieuses dans votre application de production.