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 avec 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 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 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 pendant les tests. 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 ces informations

Lorsque vous déboguez avec votre équipe ou le 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 du dispositif provenant de l'exécution qui a reproduit le problème.

Utiliser les journaux du dispositif

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

Sur Android :

Ouvrez Logcat d'Android Studio.
Filtrez par l'ID de package de l'application.
Observez les journaux de demande de permission de notification, de rafraîchissement du jeton natif, 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 Android 13+.

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 un test de notification de fond, puis un test de fond, puis un test d'actualisation silencieuse. Cette séquence sépare les problèmes de listeners JavaScript des limites de livraison de fond de l'OS.

Problèmes de registration

Section intitulée « Problèmes de registration »

CLI Installation N'a Pas Terminé

Exécutez la commande d'installation à 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 privés-avance 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é créé par votre serveur de backend pour le même appId et externalId.
appId in 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.

Ne cachez pas une preuve éternellement ou réutilisez une preuve entre applications. Générez-l’à partir de votre serveur après connexion, la renvoyez à l'application et 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 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 file d'attente mais non envoyé

Vérifiez :

L'état des identifiants 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 de l'ensemble du package dans l'application correspond à la configuration de mise en route de la plateforme.
La cible du public se traduit par 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 consommation d'iOS et de mise à jour de fond ne touchent pas la livraison en arrière-plan.
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 acceptées par le fournisseur comme « acceptées pour livraison », et non comme preuve que le dispositif l'a affichée.

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 notification iOS, sommaire de notification ou 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 en arrière-plan

La callback 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 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().
Travaillez à l'intérieur de l'appel, il est court, sans risque réseau et idempotent.

Sur 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.

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

Si les statistiques montrent background_started sans background_finishedalors le 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 la vérification manuelle retourne unavailable, inspectez 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 à des envois de badges backend.

Problèmes de Statistiques

Les Statistiques Apparaissent Dupliquées

La mise à jour des notifications est au moins une fois. La file d'attente de réessai et la réessai de la 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'Analyse est pour les appareils actifs, et non une base de données à vie. 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 :

Les notifications incluent 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 effectivement 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"
  }'

Lecture des 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 dans la recherche	`register` pas appelé, preuve incohérente, consentement faux, ID d'application incohérent.
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	Le dispositif est hors ligne, le système d'exploitation applique un surcroît de charge, l'application est arrêtée 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 application.
Le background ne fonctionne jamais sur iOS	Capacités manquantes, AppDelegate de remplacement manquant, l'application a été arrêtée par force ou le surcroît de charge du système d'exploitation.
La vérification de mise à jour ne fait rien	L'intégration de l'actualiseur est désactivée, pas de nouvelle archive, mauvais canal ou mode d'installation mal compris.
La vignette est réinitialisée	L'application démarre avec code et efface les vignettes ou les écritures de vignettes locales et backend se chevauchent.

Continuez de la section de débogage

Après que le dispositif s'est inscrit et que la notification de test fonctionne, utilisez Démarrage pour brancher les badges, la ciblage de la campagne et les vérifications de mise à jour silencieuse dans votre application de production.