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, confirmez 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 / migration de la copie de marketing d'Appflow. 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 d'Appflow).
In Capgo, ouvrez Notifications > Recherche de destinataires.
Recherchez par le même ID de 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 version de l'application.
État de permission
version de l'application
version du plugin

étiquettes et attributs

Si la recherche ne trouve 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 build de l'application.
Version du plugin.
ID client externe.
recipientKey et deviceKey ou de la recherche de destinataires.
ID de campagne ou ID de notification.
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é tout en envoyant une notification de test.

Sur Android :

Ouvrez Logcat Android Studio.
Filtrez par l'ID du package de l'application.
Observez les journaux de la demande de permission de notification, de la mise à jour du jeton natif, de la réception de message et des journaux des écouteurs 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.

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 de fond est activée. AppDelegate.swift Envoyez d'abord une test de notification de premier plan, puis une test de notification de fond, puis une test de mise à jour silencieuse. Cette séquence sépare les problèmes de listeners JavaScript des limites de livraison de fond du système.

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 le nom de package est @capgo/capacitor-notificationsVérifiez votre registre npm https://registry.npmjs.orgVérifiez l'accès au 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 correspond à l'ID utilisateur que vous recherchez dans l'interface de dashboard.
identityProof a été créé par votre 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 push 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 éternellement dans la cache ou réutilisez une preuve entre applications. Créez-l’à partir de votre serveur backend après connexion, renvoyez-l’à l'application et appelez-la 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 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

En attente mais non envoyé

Vérifiez :

Statut du statut de la plateforme est configured dans Capgo.
L'environnement du worker contient la référence secrète exacte affichée par l'interface de dashboard.
L'ID du package ou l'ID du bundle dans l'application correspond à la configuration de mise en route de la plateforme.
La cible de l'audience 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.
iOS Mode basse consommation 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 avec le même ID de collapsage.

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

Reçu mais non affiché

Vérifiez :

L'application n'était pas en avant-plan. Les notifications d'avant-plan sont généralement livrées à JavaScript afin que votre application puisse décider quelle interface utilisateur 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 notification iOS, sommarié de notification ou paramètres de notification par application ne cachent 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 de fond

La callback de fond ne s'exécute pas

Les notifications de fond sont des opérations de meilleure chance. Le système peut les ignorer.

Vérifiez :

iOS a Modes de fond > Notifications à distance activées.
iOS AppDelegate.swift transfère 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().
Le travail effectué dans l'appel de rappel est court, sécurisé par réseau et idempotent.

Sur iOS, les pushs de fond peuvent être ralentis si vous 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 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 Contrôle Silencieux de Mise à Jour

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

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 des vérifications de mise à 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 de mise à jour est correct : set s'installe dès que l'actualiseur peut le faire en toute sécurité.

Exécutez une vérification manuelle tout en ayant l'application ouverte :

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

console.log(result)

Si la vérification manuelle renvoie unavailable, inspectez d'abord la configuration de l'actualiseur.

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 simuler des appels locaux setBadge appels contre badge backend envoie.

Problèmes de Statistiques

Les Statistiques Ressemblent à des Dupliques

L'envoi 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 IDs de notification et les IDs 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 éternelle. Le plugin devrait rafraîchir la registration à 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 écouteur stable id.
notificationOpened L'écouteur stable 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

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

Lisez 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 incohérente, consentement faux, ID d'application incohérent.
Droit non accordé	Refus ou non demandé du prompt du système d'exploitation.
Statistiques en attente mais pas envoyées	Les informations de plateforme sont manquantes ou désactivées.
Statistiques envoyées mais pas reçues	L'appareil est hors ligne, l'OS applique un surcroît de charge, l'application a été arrêtée ou le jeton est invalide.
Les journaux de notification en arrière-plan mais pas de bannière	L'application est en avant-plan et doit afficher son propre interface utilisateur en application.
Le background ne fonctionne jamais sur iOS	Les capacités manquent, la mise en avant de AppDelegate est manquante, l'application a été arrêtée par force ou l'OS applique un surcroît de charge.
La vérification de mise à jour ne fait rien	L'intégration de l'actualiseur est désactivée, il n'y a pas de nouvelle archive, le canal est incorrect ou le mode d'installation est mal compris.
La vignette est réinitialisée	L'initialisation de l'application code efface les vignettes ou les écritures locales et backend de la course aux vignettes.

Continuez de là

Après l'enregistrement du dispositif et le test d'une notification réussi, utilisez Démarrage Modifier la page