Überblick: Zweistufige Class- & Object-Architektur
Anders als das herunterladbare .pkpass-Binärarchiv von Apple Wallet arbeitet Google Wallet auf einem cloudgehosteten zweistufigen Datenmodell, das über die Google Wallet REST-API (walletobjects/v1) gesteuert wird:
-
1
Wallet Class (Vorlagenebene): Definiert gemeinsames visuelles Branding, Aussteller-Metadaten, Programm-Logos, Layoutstruktur und Callback-URLs für alle Pässe einer Vorlage (z. B.
LoyaltyClass,EventTicketClass,OfferClass,GiftCardClass,GenericClass). -
2
Wallet Object (Pass-Instanzebene): Repräsentiert den Ausweis einer einzelnen Kundin oder eines einzelnen Kunden mit Verweis auf die übergeordnete
classId(z. B.LoyaltyObject,EventTicketObject,OfferObject,GiftCardObject,GenericObject) inklusive individuellem Barcode, Punktestand, Stufenstatus und Smart-Tap-Payload.
Zuordnung von Passinstance-Programmen zu Google-Wallet-Classes & -Objects
Passinstances Factory-Adapter bilden Ihre Vorlagenkonfiguration automatisch auf das passende Google-Wallet-Ressourcenpaar ab:
| Passinstance-Programm | Google-Class-Ressource | Google-Object-Ressource | Zentrale Spezialfelder |
|---|---|---|---|
| Treue- & Stempelkarten | LoyaltyClass | LoyaltyObject | loyaltyPoints, secondaryLoyaltyPoints, accountId, accountName, rewardsTier |
| Coupons & Gutscheine | OfferClass | OfferObject | redemptionChannel, provider, validTimeInterval, barcode |
| Geschenk- & Prepaid-Karten | GiftCardClass | GiftCardObject | cardNumber, pin, balance (micros + currencyCode), balanceUpdateTime |
| Event-Tickets | EventTicketClass | EventTicketObject | seatInfo (seat, row, section, gate), ticketHolderName, eventName, doorsOpen |
| Mitgliedschaften & Ausweise | GenericClass | GenericObject | cardTitle, subheader, header, textModulesData, imageModulesData |
Wichtig: Selbst wenn eine Kundin oder ein Kunde mit demselben Google-Konto auf mehreren Android-Geräten angemeldet ist, bindet Google Wallet den Ausweis an eine einzige kanonische
<issuerId>.<objectId>. Passinstance dedupliziert auf Object-Ebene und zählt dies als 1 aktiven Google-Wallet-Pass.
Signierte Save-JWT-Links & Callback-Webhooks
1. RS256-signiertes „Zu Google Wallet hinzufügen“-JWT
Öffnet eine Person einen Smart-Link unter Android, erstellt und signiert Passinstance ein JSON Web Token mit dem Private Key Ihres Google-Cloud-Dienstkontos und leitet auf https://pay.google.com/gp/v/save/<jwt> weiter:
{
"iss": "wallet-signer@passinstance-prod.iam.gserviceaccount.com",
"aud": "google",
"typ": "savetowallet",
"iat": 1763218800,
"origins": ["https://app.passinstance.com"],
"payload": {
"loyaltyObjects": [
{
"id": "3388000000022194812.pass_c41a8d20",
"classId": "3388000000022194812.cls_7b9e4c12",
"state": "ACTIVE",
"accountId": "CUST-88412",
"accountName": "Alex Rivera",
"loyaltyPoints": {
"label": "Points",
"balance": { "int": 1450 }
},
"barcode": {
"type": "QR_CODE",
"value": "PI-8849-2026-X9",
"alternateText": "PI-8849-2026-X9"
}
}
]
}
}
2. Google-Wallet-Installations- & Entfernungs-Callback (POST /api/v1/wallet/callback)
Jede von Passinstance bereitgestellte Google-Wallet-Class setzt callbackOptions.url auf POST /api/v1/wallet/callback. Sobald jemand unter Android einen Pass in Google Wallet speichert oder vom Gerät entfernt, sendet Google ein signiertes Callback-Payload:
POST /api/v1/wallet/callback
{
"classId": "3388000000022194812.cls_7b9e4c12",
"objectId": "3388000000022194812.pass_c41a8d20",
"eventType": "save",
"expTimeMillis": 1763219100000,
"nonce": "9f8e7d6c-5b4a-3210-fedc-ba9876543210"
}
-
eventType: "save": Erfasst die aktive Google-Wallet-Installation, erhöhtinstalledDevicesund löst den Webhook-/Workflow-TriggerPASS_INSTALLEDaus. -
eventType: "del": Markiert das Google-Wallet-Objekt als deinstalliert und reduziert den Zähler aktiver Pässe.
Live-Feldüberschreibungen für Android
Da Google Wallet Pässe in einem vertikal scrollbaren Kartenlayout (header, cardTitle und zweispaltige textModulesData-Zeilen) statt in Apple Wallets fixer Vorder-/Rückseiten-Klappkarte darstellt, können Sie im Inspektor des visuellen Editors für jedes Feld oder Bild-Asset (googlePayLogo, androidBackground, androidLogo) gezielte Android Overrides hinterlegen.
Erfahren Sie mehr unter Google-Wallet-Plattform, Google-Wallet-Konfiguration sowie Google Smart Tap.
