Aperçu : architecture en deux niveaux Classes & Objets
Contrairement à l'archive binaire .pkpass téléchargée localement par Apple Wallet, Google Wallet repose sur un modèle de données cloud en deux niveaux géré via l'API REST Google Wallet (walletobjects/v1) :
-
1
Wallet Class (couche Modèle) : Définit l'identité visuelle partagée, les métadonnées de l'émetteur, le logo du programme, la mise en page et les URLs de rappel pour tous les titulaires d'un même modèle (
LoyaltyClass,EventTicketClass,OfferClass,GiftCardClass,GenericClass). -
2
Wallet Object (couche Instance de passe) : Représente la carte individuelle d'un client rattachée à sa classe parente
classId(LoyaltyObject,EventTicketObject,OfferObject,GiftCardObject,GenericObject), contenant le code-barres unique, le solde de points, le palier et la charge utile Smart Tap.
Correspondance des programmes Passinstance avec les Classes & Objets Google Wallet
Les adaptateurs factory de Passinstance associent automatiquement la configuration de votre modèle à la paire de ressources Google Wallet adaptée :
| Programme Passinstance | Ressource Google Class | Ressource Google Object | Principaux champs spécialisés |
|---|---|---|---|
| Cartes de fidélité & tampons | LoyaltyClass | LoyaltyObject | loyaltyPoints, secondaryLoyaltyPoints, accountId, accountName, rewardsTier |
| Coupons & bons de réduction | OfferClass | OfferObject | redemptionChannel, provider, validTimeInterval, barcode |
| Cartes cadeaux & prépayées | GiftCardClass | GiftCardObject | cardNumber, pin, balance (micros + currencyCode), balanceUpdateTime |
| Billets d'événements | EventTicketClass | EventTicketObject | seatInfo (seat, row, section, gate), ticketHolderName, eventName, doorsOpen |
| Cartes de membre & badges | GenericClass | GenericObject | cardTitle, subheader, header, textModulesData, imageModulesData |
Important : Même si un client se connecte à son compte Google sur plusieurs smartphones ou tablettes Android, Google Wallet associe la carte à un identifiant canonique unique
<issuerId>.<objectId>. Passinstance déduplique au niveau de l'Objet et ne comptabilise cela que comme 1 passe actif Google Wallet.
Liens JWT signés d'ajout & webhooks de rappel
1. Jeton JWT Save to Google Wallet signé en RS256
Lorsqu'un client ouvre un lien intelligent depuis Android, Passinstance construit et signe un JSON Web Token avec la clé privée du compte de service Google Cloud et le redirige vers 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. Webhook d'installation & de suppression Google Wallet (POST /api/v1/wallet/callback)
Chaque Google Wallet Class provisionnée par Passinstance définit callbackOptions.url sur POST /api/v1/wallet/callback. Dès qu'un utilisateur Android enregistre ou retire la carte de Google Wallet, Google transmet un événement signé :
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": Enregistre l'installation active Google Wallet, incrémenteinstalledDeviceset déclenche le webhook ou automatismePASS_INSTALLED. -
eventType: "del": Marque l'objet Google Wallet comme désinstallé et décrémente les compteurs de passes actifs.
Surcharges spécifiques à Android en direct
Comme Google Wallet affiche les cartes dans une vue verticale déroulante (header, cardTitle et lignes à deux colonnes textModulesData) plutôt que sur une carte recto-verso fixe comme Apple Wallet, vous pouvez définir des Android Overrides dans l'inspecteur de l'éditeur visuel pour chaque champ ou image (googlePayLogo, androidBackground, androidLogo).
Approfondissez ces réglages sur Plateforme Google Wallet, Configuration Google Wallet et Google Smart Tap.
