Visão geral: Arquitetura em dois níveis de Classe e Objeto
Ao contrário do ficheiro binário transferível .pkpass da Apple Wallet, a Google Wallet funciona sobre um modelo de dados alojado na cloud em dois níveis, gerido através da API REST da Google Wallet (walletobjects/v1):
-
1
Wallet Class (Camada de Modelo): Define a identidade visual partilhada, metadados do emissor, logótipos do programa, estrutura do layout e URLs de callback em todos os titulares de um modelo (ex.:
LoyaltyClass,EventTicketClass,OfferClass,GiftCardClass,GenericClass). -
2
Wallet Object (Camada de Instância do Passe): Representa a credencial de um cliente individual referenciando a respetiva
classIdprincipal (ex.:LoyaltyObject,EventTicketObject,OfferObject,GiftCardObject,GenericObject), armazenando o código de barras único do titular, saldo de pontos, patamar e payload Smart Tap.
Mapeamento de programas Passinstance para Classes e Objetos Google Wallet
Os adaptadores factory da Passinstance mapeiam automaticamente a configuração do modelo para o par de recursos Google Wallet correspondente:
| Programa Passinstance | Recurso Class Google | Recurso Object Google | Principais campos especializados |
|---|---|---|---|
| Cartões de fidelização e carimbos | LoyaltyClass | LoyaltyObject | loyaltyPoints, secondaryLoyaltyPoints, accountId, accountName, rewardsTier |
| Cupões e vales | OfferClass | OfferObject | redemptionChannel, provider, validTimeInterval, barcode |
| Cartões-presente e pré-pagos | GiftCardClass | GiftCardObject | cardNumber, pin, balance (micros + currencyCode), balanceUpdateTime |
| Bilhetes de eventos | EventTicketClass | EventTicketObject | seatInfo (seat, row, section, gate), ticketHolderName, eventName, doorsOpen |
| Sócios e identificações | GenericClass | GenericObject | cardTitle, subheader, header, textModulesData, imageModulesData |
Importante: Mesmo que um cliente inicie sessão com a sua Conta Google em vários dispositivos Android, a Google Wallet associa a credencial a um único
<issuerId>.<objectId>canónico. A Passinstance desduplica ao nível do Objeto e contabiliza isto como 1 passe ativo Google Wallet.
Ligações Save JWT assinadas e webhooks de callback
1. Save to Google Wallet JWT assinado com RS256
Quando um titular abre uma ligação inteligente em Android, a Passinstance constrói e assina um JSON Web Token com a chave privada da sua Conta de Serviço Google Cloud e redireciona para 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 de instalação e remoção na Google Wallet (POST /api/v1/wallet/callback)
Cada Google Wallet Class provisionada pela Passinstance define callbackOptions.url como POST /api/v1/wallet/callback. Sempre que um utilizador Android guarda um passe na Google Wallet ou o remove do dispositivo, a Google envia um payload de callback assinado:
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": Regista a instalação ativa na Google Wallet, incrementainstalledDevicese dispara o gatilho de webhook/fluxoPASS_INSTALLED. -
eventType: "del": Marca o objeto Google Wallet como desinstalado e decrementa os contadores de utilização de passes ativos.
Substituições de campos em direto para Android
Como a Google Wallet apresenta passes num layout vertical deslizável (header, cardTitle e linhas textModulesData de duas colunas) em vez do cartão fixo frente/verso da Apple Wallet, pode configurar Substituições Android no Inspetor do Editor Visual para qualquer campo ou ativo de imagem (googlePayLogo, androidBackground, androidLogo).
Saiba mais em Plataforma Google Wallet, Configuração da Google Wallet e Google Smart Tap.
