Panoramica: architettura a due livelli Class e Object
A differenza dell'archivio binario .pkpass scaricabile di Apple Wallet, Google Wallet opera su un modello dati ospitato in cloud a due livelli gestito tramite la REST API Google Wallet (walletobjects/v1):
-
1
Wallet Class (Livello Modello): Definisce branding visivo condiviso, metadati dell'emittente, loghi del programma, struttura del layout e URL di callback per tutti i titolari di un modello (es.
LoyaltyClass,EventTicketClass,OfferClass,GiftCardClass,GenericClass). -
2
Wallet Object (Livello Istanza Pass): Rappresenta la credenziale del singolo cliente con riferimento al
classIdpadre (es.LoyaltyObject,EventTicketObject,OfferObject,GiftCardObject,GenericObject), contenente codice a barre univoco, saldo punti, stato del livello e payload Smart Tap.
Mappatura dei programmi Passinstance su Class e Object di Google Wallet
Gli adapter factory di Passinstance mappano automaticamente la configurazione del modello sulla coppia di risorse Google Wallet corrispondente:
| Programma Passinstance | Risorsa Class Google | Risorsa Object Google | Campi specializzati principali |
|---|---|---|---|
| Carte fedeltà e timbri | LoyaltyClass | LoyaltyObject | loyaltyPoints, secondaryLoyaltyPoints, accountId, accountName, rewardsTier |
| Coupon e buoni sconto | OfferClass | OfferObject | redemptionChannel, provider, validTimeInterval, barcode |
| Gift card e prepagate | GiftCardClass | GiftCardObject | cardNumber, pin, balance (micros + currencyCode), balanceUpdateTime |
| Biglietti eventi | EventTicketClass | EventTicketObject | seatInfo (seat, row, section, gate), ticketHolderName, eventName, doorsOpen |
| Tessere socio e badge ID | GenericClass | GenericObject | cardTitle, subheader, header, textModulesData, imageModulesData |
Importante: Anche se un cliente accede al proprio Account Google su più dispositivi Android, Google Wallet associa la credenziale a un unico
<issuerId>.<objectId>canonico. Passinstance deduplica a livello di Object e conteggia l'installazione come 1 pass Google Wallet attivo.
Link Save JWT firmati e webhook di callback
1. JWT di salvataggio in Google Wallet firmato RS256
Quando un titolare apre uno smart link su Android, Passinstance costruisce e firma un JSON Web Token con la chiave privata del Service Account Google Cloud e reindirizza a https://pay.google.com/gp/v/save/<jwt>:
{
"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. Callback di installazione e rimozione Google Wallet (POST /api/v1/wallet/callback)
Ogni Google Wallet Class creata da Passinstance imposta callbackOptions.url su POST /api/v1/wallet/callback. Ogni volta che un utente Android salva un pass in Google Wallet oppure lo rimuove dal proprio dispositivo, Google invia un payload di callback firmato:
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": Registra l'installazione attiva di Google Wallet, incrementainstalledDevicese attiva il trigger webhook/workflowPASS_INSTALLED. -
eventType: "del": Contrassegna l'oggetto Google Wallet come disinstallato e decrementa i contatori di utilizzo dei pass attivi.
Override live dei campi per Android
Poiché Google Wallet renderizza i pass con un layout a tessera verticale scorrevole (header, cardTitle e righe textModulesData a due colonne) anziché il modello fronte/retro ribaltabile di Apple Wallet, è possibile configurare gli Override Android nell'Ispettore dell'editor visuale per qualsiasi campo o asset immagine (googlePayLogo, androidBackground, androidLogo).
Approfondisca in Piattaforma Google Wallet, Configurazione Google Wallet e Google Smart Tap.
