Skip to content
Guida del Centro assistenzaFase di onboarding 6
4 min di letturaVerificato 2026-11-16

Metriche di emissione e utilizzo

Interpreta Pass creati, Attivi nei Wallet, Non installati, Rimossi e conteggio multi-dispositivo Apple.

In questa guida

Guide visive interattive UI

Apri nella guida in 6 fasi

Esplora schermate reali della dashboard e dettagli ingranditi collegati a questa guida.

Focus UI ingrandito
Elementi chiave dell'interfaccia

Salute dei pass e azioni consigliate (Zoom)

Monitora il rapporto tra pass attivi e non installati in Pass health e intervieni sulle raccomandazioni automatiche per sollecitare i pass in attesa di installazione.

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

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
TASSONOMIA ISTANZE PASS VS. REGISTRAZIONI DISPOSITIVI
FASE 01
1
LIVELLO ISTANZE PASS LOGICHE (1 record pass = 1 serialNumber univoco) [ Pass creato ]+[ Non reclamati (unclaimedPasses) ] (0 Registrazioni) (totalPasses)
+[ Attivi (activePasses) ] (>= 1 Reg. attiva) +[ Rimossi (inactivePasses) ] (Tutte reg. rimosse) +[ Terminali (expiredPasses / voidedPasses) ]
FASE 02
Ecosistema Apple Wallet (APNs)
iPhone del titolare (Reg #1)
Apple Watch abbinato (Reg #2)
1 Pass attivo = 2 Reg. disposit.
Ecosistema Google Wallet (REST)
PassObject associato a Google ID
Sync callback Save / Remove
1 Pass attivo = 1 Reg. Object
2
LIVELLO REGISTRAZIONI DISPOSITIVI FISICI (installedDevices su uniqueDevices)

Importante: In GET /api/v1/analytics/wallet-installations, un singolo pass installato sia sull'iPhone sia sull'Apple Watch del cliente viene conteggiato come 1 activePasses nel riepilogo Istanze pass, registrando al contempo 2 installedDevices nel 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 metricaEtichetta DashboardDefinizione tecnica e base di valutazione
totalPassesTotal Passes IssuedTotale dei record pass emessi e non eliminati al momento dello snapshot.
activePassesActive PassesIstanze pass attive che dispongono attualmente di almeno una registrazione dispositivo raggiungibile (esclude i pass scaduti e annullati nella panoramica standard dei pass).
inactivePassesRemoved PassesIstanze pass live precedentemente salvate in un Wallet che non hanno più alcuna registrazione dispositivo raggiungibile (removedPasses nei report di installazione).
unclaimedPassesUnclaimed PassesIstanze pass live emesse tramite API, CSV o PassFlow che non sono mai state salvate nel Wallet di un dispositivo (noRegistrationPasses).
expiredPassesExpired PassesIstanze pass la cui expirationDate è trascorsa o il cui stato è contrassegnato come EXPIRED.
voidedPassesVoided PassesIstanze pass revocate o annullate lato server tramite dashboard, workflow oppure VOIDED_AFTER_SCAN scan mode.

Metriche a livello di registrazione dispositivo

Chiave metricaEtichetta DashboardDefinizione tecnica e base di valutazione
installedDevicesActive Device RegistrationsTotale delle registrazioni di pass salvati raggiungibili su tutti i dispositivi fisici (1 pass su 2 dispositivi = 2).
inactiveDeviceRegistrationsRemoved Device RegistrationsRegistrazioni di pass salvati che sono state de-registrate dal dispositivo oppure invalidate da un errore push APNs permanente.
totalDeviceRegistrationsTotal Device RegistrationsCumulo delle registrazioni di pass salvati tra stati attivi e rimossi.
uniqueDevicesUnique DevicesIdentificativi hardware di dispositivi fisici distinti che detengono attualmente almeno una registrazione pass attiva.
devicePlatformDistributionDevice Platform DistributionRipartizione 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 richiama DELETE /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber oppure Google Wallet invia un callback di rimozione, oltre alle rimozioni dedotte quando APNs restituisce 410 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 callback save.

Endpoint API principali per emissioni e registrazioni

EndpointVerbo HTTPDescrizione
/api/v1/analytics/passes/overviewGETSnapshot di totalPasses, activePasses, inactivePasses, unclaimedPasses, expiredPasses e voidedPasses.
/api/v1/analytics/passes/createdGETSerie temporale delle nuove istanze pass create, raggruppate per day, week o month.
/api/v1/analytics/registrationsGETSerie temporale delle registrazioni dispositivi attive e disattivate nella finestra selezionata.
/api/v1/analytics/wallet-installationsGETMatrice completa che separa gli stati di installazione a livello pass dagli eventi di registrazione a livello dispositivo.

Esempio: matrice dettagliata delle installazioni Wallet

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

Documentazione correlata

Pronto a lanciare il tuo primo programma di carte Wallet?

Crea il tuo workspace, configura il modello e testa una carta reale in Apple Wallet e Google Wallet prima di scalare.