Débogage

Copiez un prompt de configuration avec les étapes d'installation et le guide Markdown complet pour ce plugin.

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.

Démarrez par le registre du dispositif

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

Ouvrez l'application et connectez-vous en tant qu'utilisateur que vous souhaitez tester.
Appeler CapgoNotifications.register(...) context : fragment de texte HTML provenant d'une chaîne de Capgo UI plus longue (clé parente `appflow_migration_step2`). Page/zone : Comparaison et migration de l'Appflow / marketing de copie. Rôle : Phrase de copie du site web. Voir dans : page ionic-appflow.astro. Conservez les termes de produit/marque et les termes de développeur de Capgo exactement. Clé de message `appflow_migration_step2` (Étape 2 de la migration de l'Appflow).
In Capgo, ouvrez Notifications > Recherche de destinataires.
Recherchez par le même ID client externe.

Vous devriez voir au moins un appareil actif avec :

recipientKey
deviceKey
plateforme android ou ios
Vous devriez voir au moins un appareil actif avec : plateforme ou
é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.

Ajoutez des écouteurs temporaires lors de la phase de test. Supprimez 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()
})

Collecter Cette Information

Lorsque vous déboguez 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 du dispositif.
Version et numéro de construction de l'application.
Version du plugin.
ID client externe.
recipientKey et deviceKey ou de la recherche de destinataires.
Identifiant de campagne ou d'alerte.
Indique si l'application était en avant-plan, en arrière-plan, fermée par force ou récemment installée.
Journal de l'appareil provenant de l'exécution qui a reproduit le problème.

Utiliser les journaux de l'appareil

Conservez un appareil réel connecté pendant que vous envoyez une notification de test.

Sur Android :

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

Sur iOS :

Exécutez l'application à partir de Xcode sur un appareil physique.
Ouvrez la console Xcode ou Appareils et Simulateurs Filtrez par l'ID de l'application et
Confirmez CapgoNotifications.
que les notifications à distance sont envoyées et que la capacité de mode arrière est activée. AppDelegate.swift Envoyez d'abord une test de notification en avant-plan, puis une test de notification en arrière-plan, puis une test de mise à jour silencieuse. Cette séquence sépare les problèmes de listeners JavaScript des limites de livraison en arrière-plan de l'OS.

Problèmes de registration

Section intitulée « Problèmes de registration »

CLI Installation 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 la commande ne peut pas inférer votre ID d'application, passez-l’explicitement comme montré ci-dessus. Si l'installation de package échoue, confirmez que Capgo a activé l'accès aux packages en version bêta privée pour votre compte npm, 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 correspond au ID d'utilisateur que vous recherchez dans le tableau de bord.
identityProof a été généré par votre serveur backend pour le même appId And externalId.
appId en 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 native 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.

Ne cachez pas une preuve pendant toute une éternité 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.

Appareil Enregistré Mais Auteur Un Accès Refusé

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 seront pas affichées.

Utilisez un écran de rappel 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

Vérifiez :

L'état du credencial de la plateforme est configured en Capgo.
L'environnement de travail contient la référence exacte du secret affichée par le tableau de bord.
L'ID du package ou l'ID du bundle dans l'application correspond à la configuration de mise en œuvre de la plateforme.
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 force 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 pendant les tests.
Les restrictions de mode faible sur 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 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 réglage de Focus, de résumé de notification ou de notification par application iOS ne masquent pas la notification.
La logique de nettoyage 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 de rappel en arrière-plan ne s'exécute pas

Les notifications de fond sont de meilleure volonté. Le système 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'utilisateur n'a pas fermé l'application.
Le gestionnaire de fond appelle finish().
Travaillez à l'intérieur de l'appel, il est court, sans risque réseau et idempotent.

Sur iOS, les pushs en arrière-plan 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.

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

Si les statistiques montrent background_started sans background_finishedle gestionnaire JavaScript a probablement lancé une erreur, dépassé le temps limite 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 de Mise à Jour Silencieuse

La Notification de Vérification de Mise à Jour Arrive Mais Pas de Mise à Jour Installe

Vérifiez :

@capgo/capacitor-updater est installé et configuré.
autoUpdater est true ou enableUpdaterIntegration ou
était appelé.
Les paramètres de notifications de l'application permettent de vérifier les mises à jour push.
The app has a newer bundle available in Capgo.
L'application dispose d'une mise à jour plus récente disponible dans __CAPGO_KEEP_0__. next Votre mode d'installation d'actualisation est correct : set file dans la file d'attente pour la prochaine redémarrage ou cycle de fond,

se met en place dès que l'actualiseur peut le faire en toute sécurité.

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

console.log(result)

Si le contrôle manuel 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 faire concurrence aux appels locaux setBadge aux envois de badges backend.

Problèmes de Statistiques

Les Statistiques Apparaissent Dupliquées

La mise en œuvre de notification 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 :

Le message de notification comporte un identifiant stable id.
notificationOpened L'écouteur est enregistré lors du démarrage de l'application.
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

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 courantes

Symptôme	Cause probable
Appareil manquant de 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 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 a été arrêtée par force, ou le jeton est invalide.
Les journaux de notification en avant-plan mais pas de bannière	L'application est en avant-plan et doit afficher son propre interface utilisateur en interne.
Le fond d'écran ne fonctionne jamais sur iOS	Capacités manquantes, AppDelegate de remplacement manquant, l'application a été arrêtée par force, ou le système d'exploitation applique un surcroît de charge.
La vérification de mise à jour ne fait rien	L'intégration de l'updateur est désactivée, pas de nouvelle archive, mauvais canal, ou mode d'installation mal compris.
La vignette est réinitialisée	L'appel à l'application code efface les vignettes ou les écritures locales et backend de la course.

Continuez de la section de débogage

Après l'enregistrement du dispositif et le test d'une notification fonctionnelle, utilisez Prise en main pour intégrer les badges, la ciblage de campagnes et les vérifications de mise à jour silencieuse dans votre application de production.