Overzicht
Voor een nauwkeurige interpretatie van Wallet-telemetrie is een strikt architectonisch onderscheid nodig tussen Pasinstanties (logische pasrecords in de database met UUID id, serialNumber en optionele externe externalId) en Apparaatregistraties (fysieke mobiele of draagbare apparaten waarop die passen actief zijn opgeslagen onder het Apple bundleId / passTypeIdentifier of het Google Wallet Object-ID van het sjabloon).
Passinstance handhaaft deze scheiding in metric-definitions.ts (PASS_ANALYTICS_METRIC_DEFINITIONS en WALLET_INSTALLATION_METRIC_DEFINITIONS), visueel getoond in Dashboard Analytics -> Passen (/analytics/passes) en via /api/v1/analytics/*, zodat marketingteams en facturatiebeheerders gegenereerde downloadlinks nooit verwarren met geïnstalleerde Wallet-kaarten.
Architectonische scheiding: Pasinstanties versus apparaatregistraties
Belangrijk: In
GET /api/v1/analytics/wallet-installationstelt één pas die zowel op de iPhone als op de Apple Watch van een klant is geïnstalleerd als 1activePassesin het pasoverzicht, terwijl 2installedDevicesworden vastgelegd bij de apparaatregistraties omdat APNs pushmeldingen afzonderlijk naar elk apparaattoken verstuurt.
Canonieke statistiekdefinities (metric-definitions.ts)
Pasinstantie-statistieken
| Statistieksleutel | Dashboardlabel | Technische definitie & berekeningsgrondslag |
|---|---|---|
totalPasses | Totaal uitgegeven passen | Totaal aantal uitgegeven en niet-verwijderde pasrecords op het momentopname-tijdstip. |
activePasses | Actieve passen | Live pasinstanties met momenteel ten minste één bereikbare apparaatregistratie (exclusief verlopen en ongeldige passen in het standaard pasoverzicht). |
inactivePasses | Verwijderde passen | Live pasinstanties die eerder in een Wallet waren opgeslagen maar geen bereikbare apparaatregistraties meer hebben (removedPasses in installatierapporten). |
unclaimedPasses | Niet-geclaimde passen | Live pasinstanties uitgegeven via API, CSV of PassFlow die nog nooit in een apparaat-Wallet zijn opgeslagen (noRegistrationPasses). |
expiredPasses | Verlopen passen | Pasinstanties waarvan de expirationDate is verstreken of met status EXPIRED. |
voidedPasses | Ongeldig verklaarde passen | Pasinstanties die aan de serverzijde zijn ingetrokken of ongeldig verklaard via dashboard, workflow of VOIDED_AFTER_SCAN scan mode. |
Apparaatregistratie-statistieken
| Statistieksleutel | Dashboardlabel | Technische definitie & berekeningsgrondslag |
|---|---|---|
installedDevices | Actieve apparaatregistraties | Totaal aantal bereikbare opgeslagen pasregistraties verdeeld over alle fysieke toestellen (1 pas op 2 toestellen = 2). |
inactiveDeviceRegistrations | Verwijderde apparaatregistraties | Opgeslagen pasregistraties die door het apparaat zijn afgemeld of door permanente APNs-pushfouten ongeldig zijn geworden. |
totalDeviceRegistrations | Totaal apparaatregistraties | Cumulatieve opgeslagen pasregistraties over zowel actieve als verwijderde toestanden. |
uniqueDevices | Unieke apparaten | Onderscheiden fysieke apparaat-identificaties die momenteel minstens één actieve pasregistratie bevatten. |
devicePlatformDistribution | Apparaatplatformverdeling | Uitsplitsing van actieve apparaatregistraties per Wallet-ecosysteem (APPLE_WALLET vs. GOOGLE_WALLET) en besturingssysteem. |
Nuances & randgevallen bij Wallet-telemetrie
Naast bevestigde toestanden volgt GET /api/v1/analytics/wallet-installations overgangen op gebeurtenisniveau:
-
installEvents(Wallet-installaties): Apparaatregistraties aangemaakt in de rapportageperiode, éénmaal geteld per unieke combinatie van pas en apparaat. Herinstalleren op hetzelfde toestel verhoogt dit cijfer niet kunstmatig. -
removalEvents(Wallet-verwijderingen): Vastgelegd zodra Apple WalletDELETE /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumberaanroept of Google Wallet een verwijderingscallback stuurt, aangevuld met afgeleide verwijderingen wanneer APNs410 Unregisteredteruggeeft. -
otherStatePasses(Onbesliste registraties): Passen waarvan alle registraties nog in behandeling, opgeschort of in een tussenstatus verkeren die noch een actieve installatie noch een definitieve verwijdering bewijst. -
noRegistrationPasses(Geen bevestigde installatie): Passen met nul registratierecords. Bij Apple Wallet leidt installatie altijd tot directe apparaatregistratie; bij Google Wallet is registratie afhankelijk van opslagcallbacks.
Belangrijkste API-endpoints voor uitgifte & registraties
| Endpoint | HTTP-methode | Beschrijving |
|---|---|---|
/api/v1/analytics/passes/overview | GET | Momentopname van totalPasses, activePasses, inactivePasses, unclaimedPasses, expiredPasses en voidedPasses. |
/api/v1/analytics/passes/created | GET | Tijdreeks van nieuw aangemaakte pasinstanties gegroepeerd op day, week of month. |
/api/v1/analytics/registrations | GET | Tijdreeks van actieve en gedeactiveerde apparaatregistraties in het gekozen venster. |
/api/v1/analytics/wallet-installations | GET | Volledige matrix die installatietoestanden op pasniveau scheidt van apparaatregistraties. |
Voorbeeld: Gedetailleerde Wallet-installatiematrix
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
}
}
Gerelateerde documentatie
-
Begrijp hoe aantallen actieve passen doorwerken in pakketlimieten in Actieve passen & verbruikslimieten.
-
Verken grafiekfilters van de werkruimte in het Analytics Dashboard.
