Übersicht
Eine präzise Interpretation der Wallet-Telemetrie erfordert eine strikte architektonische Trennung zwischen Karteninstanzen (logischen Ausweisdatensätzen, die in der Datenbank ausgestellt und über die UUID id, die serialNumber sowie eine optionale vorgelagerte externalId identifiziert werden) und Geräteregistrierungen (physischen Smartphones oder Wearables, die diese Ausweise aktiv unter der Apple-bundleId / dem passTypeIdentifier der Vorlage oder der Google-Wallet-Objekt-ID gespeichert haben).
Passinstance setzt diese Trennung in metric-definitions.ts (PASS_ANALYTICS_METRIC_DEFINITIONS und WALLET_INSTALLATION_METRIC_DEFINITIONS) durch und stellt sie im Dashboard unter Analysen -> Karten (/analytics/passes) sowie über /api/v1/analytics/* visuell dar, damit Marketingteams und Abrechnungsadministratoren generierte Links niemals mit tatsächlich installierten Wallet-Karten verwechseln.
Architektonische Trennung: Karteninstanzen vs. Geräteregistrierungen
Wichtig: In
GET /api/v1/analytics/wallet-installationszählt eine einzelne Karte, die sowohl auf dem iPhone als auch auf der Apple Watch eines Kunden installiert ist, in der Karteninstanz-Übersicht als 1activePasses, während in der Geräteregistrierungs-Übersicht 2installedDeviceserfasst werden, da APNs Push-Benachrichtigungen unabhängig an jedes einzelne Geräte-Token zustellt.
Kanonische Metrikdefinitionen (metric-definitions.ts)
Metriken zu Karteninstanzen
| Metrikschlüssel | Bezeichnung im Dashboard | Technische Definition & Berechnungsgrundlage |
|---|---|---|
totalPasses | Insgesamt ausgestellte Karten | Gesamtzahl der zum Zeitpunkt des Snapshots ausgestellten und nicht gelöschten Kartendatensätze. |
activePasses | Aktive Karten | Aktive Karteninstanzen, die derzeit über mindestens eine erreichbare Geräteregistrierung verfügen (schließt abgelaufene und entwertete Karten in der Standard-Kartenübersicht aus). |
inactivePasses | Entfernte Karten | Aktive Karteninstanzen, die zuvor in einer Wallet gespeichert waren, aber über keine erreichbaren Geräteregistrierungen mehr verfügen (removedPasses in Installationsberichten). |
unclaimedPasses | Nicht abgerufene Karten | Aktive Karteninstanzen, die per API, CSV oder PassFlow ausgestellt, aber noch nie in einer Geräte-Wallet gespeichert wurden (noRegistrationPasses). |
expiredPasses | Abgelaufene Karten | Karteninstanzen, deren expirationDate überschritten wurde oder deren Status als EXPIRED markiert ist. |
voidedPasses | Entwertete Karten | Karteninstanzen, die serverseitig über das Dashboard, einen Workflow oder VOIDED_AFTER_SCAN scan mode widerrufen bzw. ungültig gemacht wurden. |
Metriken zu Geräteregistrierungen
| Metrikschlüssel | Bezeichnung im Dashboard | Technische Definition & Berechnungsgrundlage |
|---|---|---|
installedDevices | Aktive Geräteregistrierungen | Gesamtzahl der erreichbaren Registrierungen gespeicherter Karten über alle physischen Geräte hinweg (1 Karte auf 2 Geräten = 2). |
inactiveDeviceRegistrations | Entfernte Geräteregistrierungen | Registrierungen gespeicherter Karten, die vom Gerät abgemeldet oder aufgrund eines dauerhaften APNs-Push-Fehlers als ungültig markiert wurden. |
totalDeviceRegistrations | Gesamte Geräteregistrierungen | Kumulierte Registrierungen gespeicherter Karten über aktive und entfernte Status hinweg. |
uniqueDevices | Eindeutige Geräte | Eindeutige Hardwarekennungen physischer Geräte, die derzeit mindestens eine aktive Kartenregistrierung halten. |
devicePlatformDistribution | Geräteplattform-Verteilung | Aufschlüsselung aktiver Geräteregistrierungen nach Wallet-Ökosystem (APPLE_WALLET vs. GOOGLE_WALLET) und Betriebssystemfamilie. |
Feinheiten der Wallet-Telemetrie & Sonderfälle
Zusätzlich zu bestätigten Status verfolgt der Bericht GET /api/v1/analytics/wallet-installations Statusübergänge auf Ereignisebene und Grenzfälle:
-
installEvents(Wallet-Installationen): Während des Berichtszeitraums erstellte Geräteregistrierungen, die einmal pro eindeutigem Karten-und-Geräte-Paar gezählt werden. Die Neuinstallation einer bereits registrierten Karte auf demselben Gerät erhöht den Installationszähler nicht künstlich. -
removalEvents(Wallet-Entfernungen): Werden erfasst, wenn Apple WalletDELETE /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumberaufruft oder Google Wallet einen Entfernungs-Callback sendet, zuzüglich abgeleiteter Entfernungen, wenn APNs410 Unregisteredzurückgibt. -
otherStatePasses(Ungeklärte Registrierungen): Karten, deren einzige Registrierungen ausstehend, ausgesetzt oder in einem unbestimmten Zustand sind, der weder eine aktive Installation noch eine bestätigte Entfernung belegt. -
noRegistrationPasses(Keine bestätigte Installation): Karten ohne jegliche Registrierungsdatensätze. Bei Apple Wallet löst die Installation immer sofort einen Geräteregistrierungsaufruf aus; bei Google Wallet basiert die Erfassung auf Speicher-Callbacks.
Zentrale API-Endpunkte für Ausgabe & Registrierung
| Endpunkt | HTTP-Verb | Beschreibung |
|---|---|---|
/api/v1/analytics/passes/overview | GET | Momentaufnahme von totalPasses, activePasses, inactivePasses, unclaimedPasses, expiredPasses und voidedPasses. |
/api/v1/analytics/passes/created | GET | Zeitreihe neu erstellter Karteninstanzen, gruppiert nach day, week oder month. |
/api/v1/analytics/registrations | GET | Zeitreihe aktiver und deaktivierter Geräteregistrierungen über das ausgewählte Zeitfenster. |
/api/v1/analytics/wallet-installations | GET | Umfassende Matrix, die Installationsstatus auf Kartenebene von Registrierungsereignissen auf Geräteebene trennt. |
Beispiel: Detaillierte Wallet-Installationsmatrix
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
}
}
Weiterführende Dokumentation
-
Erfahren Sie unter Aktive Karten & Nutzungslimits, wie sich die Anzahl aktiver Karten auf Abonnementstufen auswirkt.
-
Entdecken Sie die Diagrammsteuerungen des Workspaces unter Analyse-Dashboard.
