Panoramica
Un'interpretazione accurata della telemetria Wallet richiede una rigorosa distinzione architetturale tra Istanze pass (record logici di credenziali emessi nel database e identificati da UUID id, serialNumber ed eventuale externalId upstream) e Registrazioni dispositivi (dispositivi mobili o indossabili fisici che archiviano attivamente tali credenziali rispetto al bundleId / passTypeIdentifier Apple del modello o all'Object ID Google Wallet).
Passinstance applica questa separazione in metric-definitions.ts (PASS_ANALYTICS_METRIC_DEFINITIONS e WALLET_INSTALLATION_METRIC_DEFINITIONS), presentata visivamente nella Dashboard sotto Analytics -> Pass (/analytics/passes) e tramite /api/v1/analytics/*, affinché i team marketing e gli amministratori della fatturazione non confondano mai i link generati con le tessere effettivamente installate nei Wallet.
Separazione architetturale: istanze pass vs. registrazioni dispositivi
Importante: In
GET /api/v1/analytics/wallet-installations, un singolo pass installato sia sull'iPhone sia sull'Apple Watch del cliente viene conteggiato come 1activePassesnel riepilogo Istanze pass, registrando al contempo 2installedDevicesnel riepilogo Registrazioni dispositivi poiché APNs invia le notifiche push separatamente a ciascun token dispositivo.
Definizioni canoniche delle metriche (metric-definitions.ts)
Metriche a livello di istanza pass
| Chiave metrica | Etichetta Dashboard | Definizione tecnica e base di valutazione |
|---|---|---|
totalPasses | Total Passes Issued | Totale dei record pass emessi e non eliminati al momento dello snapshot. |
activePasses | Active Passes | Istanze pass attive che dispongono attualmente di almeno una registrazione dispositivo raggiungibile (esclude i pass scaduti e annullati nella panoramica standard dei pass). |
inactivePasses | Removed Passes | Istanze pass live precedentemente salvate in un Wallet che non hanno più alcuna registrazione dispositivo raggiungibile (removedPasses nei report di installazione). |
unclaimedPasses | Unclaimed Passes | Istanze pass live emesse tramite API, CSV o PassFlow che non sono mai state salvate nel Wallet di un dispositivo (noRegistrationPasses). |
expiredPasses | Expired Passes | Istanze pass la cui expirationDate è trascorsa o il cui stato è contrassegnato come EXPIRED. |
voidedPasses | Voided Passes | Istanze pass revocate o annullate lato server tramite dashboard, workflow oppure VOIDED_AFTER_SCAN scan mode. |
Metriche a livello di registrazione dispositivo
| Chiave metrica | Etichetta Dashboard | Definizione tecnica e base di valutazione |
|---|---|---|
installedDevices | Active Device Registrations | Totale delle registrazioni di pass salvati raggiungibili su tutti i dispositivi fisici (1 pass su 2 dispositivi = 2). |
inactiveDeviceRegistrations | Removed Device Registrations | Registrazioni di pass salvati che sono state de-registrate dal dispositivo oppure invalidate da un errore push APNs permanente. |
totalDeviceRegistrations | Total Device Registrations | Cumulo delle registrazioni di pass salvati tra stati attivi e rimossi. |
uniqueDevices | Unique Devices | Identificativi hardware di dispositivi fisici distinti che detengono attualmente almeno una registrazione pass attiva. |
devicePlatformDistribution | Device Platform Distribution | Ripartizione delle registrazioni dispositivi attive per ecosistema Wallet (APPLE_WALLET vs. GOOGLE_WALLET) e famiglia OS. |
Particolarità della telemetria Wallet e casi limite
Oltre agli stati confermati, il report GET /api/v1/analytics/wallet-installations traccia le transizioni a livello di evento e gli stati intermedi:
-
installEvents(Installazioni Wallet): Registrazioni dispositivo create durante il periodo di riferimento, conteggiate una sola volta per coppia univoca pass-dispositivo. Reinstallare un pass già registrato sullo stesso dispositivo non gonfia il conteggio delle installazioni. -
removalEvents(Rimozioni Wallet): Registrate quando Apple Wallet richiamaDELETE /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumberoppure Google Wallet invia un callback di rimozione, oltre alle rimozioni dedotte quando APNs restituisce410 Unregistered. -
otherStatePasses(Registrazioni non risolte): Pass le cui uniche registrazioni risultano in sospeso, sospese o in uno stato indeterminato che non dimostra né un'installazione attiva né una rimozione confermata. -
noRegistrationPasses(Nessuna installazione confermata): Pass con zero record di registrazione. Per Apple Wallet, l'installazione attiva sempre una chiamata immediata di registrazione del dispositivo; per Google Wallet, il rilevamento dell'installazione si basa sui callbacksave.
Endpoint API principali per emissioni e registrazioni
| Endpoint | Verbo HTTP | Descrizione |
|---|---|---|
/api/v1/analytics/passes/overview | GET | Snapshot di totalPasses, activePasses, inactivePasses, unclaimedPasses, expiredPasses e voidedPasses. |
/api/v1/analytics/passes/created | GET | Serie temporale delle nuove istanze pass create, raggruppate per day, week o month. |
/api/v1/analytics/registrations | GET | Serie temporale delle registrazioni dispositivi attive e disattivate nella finestra selezionata. |
/api/v1/analytics/wallet-installations | GET | Matrice completa che separa gli stati di installazione a livello pass dagli eventi di registrazione a livello dispositivo. |
Esempio: matrice dettagliata delle installazioni Wallet
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
}
}
Documentazione correlata
-
Comprenda come il conteggio dei pass attivi si applica alle fasce di abbonamento in Pass attivi e limiti di utilizzo.
-
Esplori i controlli dei grafici nella Dashboard Analytics.
