Skip to content
Guide du centre d'aidePhase d'intégration 6
4 min de lectureVérifié 2026-11-16

Indicateurs d'émission & d'usage

Interprétez Passes créés, Actifs en Wallet, Non installés, Supprimés et le comptage multi-appareils Apple.

Dans ce guide

Visites interactives de l'interface

Ouvrir dans le guide en 6 phases

Inspectez les écrans exacts du tableau de bord et les zooms annotés liés à ce guide.

Focus interface zoomé
Éléments clés de l'interface

Santé des cartes et actions recommandées (Zoom)

Suivez la répartition entre cartes actives et non installées et agissez sur les recommandations automatisées pour relancer les cartes en attente d'installation.

Présentation

Une interprétation précise de la télémétrie des portefeuilles exige une distinction architecturale stricte entre les instances de passes (enregistrements d'identifiants logiques émis en base de données et indexés par UUID id, serialNumber et un externalId amont facultatif) et les enregistrements d'appareils (appareils mobiles physiques ou montres connectées stockant activement ces identifiants sous le bundleId / passTypeIdentifier Apple du modèle ou l'Object ID Google Wallet).

Passinstance applique cette séparation dans metric-definitions.ts (PASS_ANALYTICS_METRIC_DEFINITIONS et WALLET_INSTALLATION_METRIC_DEFINITIONS), exposée visuellement dans le tableau de bord sous Analytics -> Passes (/analytics/passes) et via /api/v1/analytics/*, afin que les équipes marketing et les administrateurs de facturation ne confondent jamais les liens générés avec les cartes réellement installées dans les portefeuilles.

Séparation architecturale : Instances de passes vs Enregistrements d'appareils

FLUX ARCHITECTURE SYSTÈME
ARCHITECTURE INTERACTIVE
FLUX D'ARCHITECTURE SYSTÈME : TAXONOMIE INSTANCE DE PASS VS ENREGISTREMENT D'APPAREIL
ÉTAPE 01
1
COUCHE LOGIQUE DES INSTANCES DE PASSES (1 enregistrement de pass = 1 serialNumber unique) [ Pass créé ]+[ Non réclamé (unclaimedPasses) ] (0 Enreg.) (totalPasses)
+[ Actif (activePasses) ] (>= 1 Enreg. actif) +[ Supprimé (inactivePasses) ] (Tous enreg. retirés) +[ Terminal (expiredPasses / voidedPasses) ]
ÉTAPE 02
Écosystème Apple Wallet (APNs)
iPhone du détenteur (Enreg. #1)
Apple Watch jumelée (Enreg. #2)
1 Pass actif = 2 Enreg. appareil
Écosystème Google Wallet (REST)
PassObject lié à l'ID Google
Synchro callback Ajout/Retrait
1 Pass actif = 1 Enreg. objet
2
COUCHE PHYSIQUE D'ENREGISTREMENT D'APPAREIL (installedDevices sur uniqueDevices)

Important : Dans GET /api/v1/analytics/wallet-installations, un seul pass installé à la fois sur l'iPhone et sur l'Apple Watch d'un client compte pour 1 activePasses dans le résumé des instances de passes, tout en enregistrant 2 installedDevices dans le résumé des enregistrements d'appareils, car APNs remet les notifications push à chaque jeton d'appareil indépendamment.

Définitions canoniques des métriques (metric-definitions.ts)

Métriques des instances de passes

Clé de métriqueLibellé du tableau de bordDéfinition technique et base d'évaluation
totalPassesTotal Passes IssuedNombre total d'enregistrements de passes émis et non supprimés au moment de l'instantané.
activePassesActive PassesInstances de passes en production disposant actuellement d'au moins un enregistrement d'appareil joignable (exclut les passes expirés et révoqués dans la vue d'ensemble standard).
inactivePassesRemoved PassesInstances de passes en production précédemment enregistrées dans un portefeuille mais qui n'ont plus aucun enregistrement d'appareil joignable (removedPasses dans les rapports d'installation).
unclaimedPassesUnclaimed PassesInstances de passes en production émises via API, CSV ou PassFlow qui n'ont jamais été enregistrées dans le portefeuille d'un appareil (noRegistrationPasses).
expiredPassesExpired PassesInstances de passes dont la date expirationDate est dépassée ou dont le statut est marqué comme EXPIRED.
voidedPassesVoided PassesInstances de passes révoquées ou annulées côté serveur via le tableau de bord, un workflow ou VOIDED_AFTER_SCAN scan mode.

Métriques d'enregistrement d'appareils

Clé de métriqueLibellé du tableau de bordDéfinition technique et base d'évaluation
installedDevicesActive Device RegistrationsTotal des enregistrements de passes sauvegardés et joignables sur l'ensemble des appareils physiques (1 pass sur 2 appareils = 2).
inactiveDeviceRegistrationsRemoved Device RegistrationsEnregistrements de passes sauvegardés qui ont été désenregistrés par l'appareil ou invalidés à la suite d'un échec permanent de push APNs.
totalDeviceRegistrationsTotal Device RegistrationsCumul des enregistrements de passes sauvegardés couvrant à la fois les états actifs et supprimés.
uniqueDevicesUnique DevicesIdentifiants matériels d'appareils physiques distincts détenant actuellement au moins un enregistrement de pass actif.
devicePlatformDistributionDevice Platform DistributionRépartition des enregistrements d'appareils actifs par écosystème de portefeuille (APPLE_WALLET vs GOOGLE_WALLET) et par famille d'OS.

Nuances de la télémétrie de portefeuille et cas particuliers

Outre les états confirmés, le rapport GET /api/v1/analytics/wallet-installations suit les transitions au niveau des événements ainsi que les états limites :

  • installEvents (Installations dans le portefeuille) : Enregistrements d'appareils créés au cours de la période d'analyse, comptés une seule fois par couple unique pass-appareil. La réinstallation d'un pass déjà enregistré sur le même appareil ne gonfle pas le compteur d'installations.
  • removalEvents (Suppressions du portefeuille) : Enregistrés lorsqu'Apple Wallet appelle DELETE /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber ou lorsque Google Wallet envoie un callback de suppression, ainsi que lors des suppressions déduites lorsqu'APNs renvoie 410 Unregistered.
  • otherStatePasses (Enregistrements non résolus) : Passes dont les seuls enregistrements sont en attente, suspendus ou dans un état indéterminé qui ne prouve ni une installation active ni une suppression confirmée.
  • noRegistrationPasses (Aucune installation confirmée) : Passes ne comportant aucun enregistrement d'appareil. Pour Apple Wallet, l'installation déclenche toujours un appel immédiat d'enregistrement d'appareil ; pour Google Wallet, l'installation repose sur les callbacks d'enregistrement.

Principaux points de terminaison API d'émission et d'enregistrement

Point de terminaisonVerbe HTTPDescription
/api/v1/analytics/passes/overviewGETInstantané de totalPasses, activePasses, inactivePasses, unclaimedPasses, expiredPasses et voidedPasses.
/api/v1/analytics/passes/createdGETSérie temporelle des nouvelles instances de passes créées, regroupées par day, week ou month.
/api/v1/analytics/registrationsGETSérie temporelle des enregistrements d'appareils actifs et désactivés sur la fenêtre sélectionnée.
/api/v1/analytics/wallet-installationsGETMatrice complète séparant les états d'installation au niveau du pass des événements d'enregistrement au niveau de l'appareil.

Exemple : Matrice détaillée d'installation dans les portefeuilles

HTTP
GET /api/v1/analytics/wallet-installations?range=last_30days&templateId=b4f29c10-83e1-4a7b-9d12-56e8012a9c04 HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
JSON
{
  "snapshotAt": "2026-11-15T23:59:59.999Z",
  "passes": {
    "totalPasses": 5000,
    "activePasses": 3850,
    "removedPasses": 310,
    "otherStatePasses": 15,
    "noRegistrationPasses": 825
  },
  "registrations": {
    "installedDevices": 4290,
    "inactiveDeviceRegistrations": 365,
    "totalDeviceRegistrations": 4655,
    "uniqueDevices": 4180,
    "devicePlatformDistribution": {
      "apple": 2910,
      "google": 1380
    }
  },
  "periodEvents": {
    "passesCreated": 640,
    "installEvents": 595,
    "removalEvents": 42
  }
}

Documentation connexe

Prêt à lancer votre premier programme de cartes Wallet ?

Créez votre espace de travail, configurez votre modèle et testez une vraie carte dans Apple Wallet et Google Wallet avant de déployer à grande échelle.