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
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 1activePassesdans le résumé des instances de passes, tout en enregistrant 2installedDevicesdans 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étrique | Libellé du tableau de bord | Définition technique et base d'évaluation |
|---|---|---|
totalPasses | Total Passes Issued | Nombre total d'enregistrements de passes émis et non supprimés au moment de l'instantané. |
activePasses | Active Passes | Instances 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). |
inactivePasses | Removed Passes | Instances 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). |
unclaimedPasses | Unclaimed Passes | Instances de passes en production émises via API, CSV ou PassFlow qui n'ont jamais été enregistrées dans le portefeuille d'un appareil (noRegistrationPasses). |
expiredPasses | Expired Passes | Instances de passes dont la date expirationDate est dépassée ou dont le statut est marqué comme EXPIRED. |
voidedPasses | Voided Passes | Instances 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étrique | Libellé du tableau de bord | Définition technique et base d'évaluation |
|---|---|---|
installedDevices | Active Device Registrations | Total des enregistrements de passes sauvegardés et joignables sur l'ensemble des appareils physiques (1 pass sur 2 appareils = 2). |
inactiveDeviceRegistrations | Removed Device Registrations | Enregistrements 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. |
totalDeviceRegistrations | Total Device Registrations | Cumul des enregistrements de passes sauvegardés couvrant à la fois les états actifs et supprimés. |
uniqueDevices | Unique Devices | Identifiants matériels d'appareils physiques distincts détenant actuellement au moins un enregistrement de pass actif. |
devicePlatformDistribution | Device Platform Distribution | Ré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 appelleDELETE /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumberou lorsque Google Wallet envoie un callback de suppression, ainsi que lors des suppressions déduites lorsqu'APNs renvoie410 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 terminaison | Verbe HTTP | Description |
|---|---|---|
/api/v1/analytics/passes/overview | GET | Instantané de totalPasses, activePasses, inactivePasses, unclaimedPasses, expiredPasses et voidedPasses. |
/api/v1/analytics/passes/created | GET | Série temporelle des nouvelles instances de passes créées, regroupées par day, week ou month. |
/api/v1/analytics/registrations | GET | Série temporelle des enregistrements d'appareils actifs et désactivés sur la fenêtre sélectionnée. |
/api/v1/analytics/wallet-installations | GET | Matrice 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
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>
{
"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
-
Comprenez comment les compteurs de passes actifs s'appliquent aux paliers d'abonnement dans Passes actifs et limites d'utilisation.
-
Explorez les commandes de graphiques de l'espace de travail dans Tableau de bord analytique.
