Skip to content
Guida del Centro assistenza · Integrazioni Wallet
3 min di letturaVerificato 2026-11-16

Google Wallet

Come Passinstance provisiona classi e oggetti Generic, Loyalty, Offer, Gift Card ed Event via JWT firmati.

In questa guida

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. 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. 2
    Wallet Object (Livello Istanza Pass): Rappresenta la credenziale del singolo cliente con riferimento al classId padre (es. LoyaltyObject, EventTicketObject, OfferObject, GiftCardObject, GenericObject), contenente codice a barre univoco, saldo punti, stato del livello e payload Smart Tap.
FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
CLASS/OBJECT GOOGLE WALLET E PIPELINE SAVE JWT
FASE 01 FASE 1: PUBBLICAZIONE MODELLOPROVISIONING CLASS
Modello Passinstance pubblicato (POST/api/v1/templates/:id/publish)
Google Wallet Sync esegue upsert di <issuerId>.<templateClassId> via REST (LoyaltyClass | EventTicketClass | OfferClass | GiftCardClass)
FASE 02 FASE 2: EMISSIONE PASS E GENERAZIONE SAVE JWT RS256
1
Predispone o incorpora <issuerId>.<passObjectId> (LoyaltyObject, ecc.)
2
Firma i claim JWT (iss, aud: "google", typ: "savetowallet", payload) usando la chiave privata RSA del Service Account Google Cloud (RS256)
3
Restituisce URL di salvataggio: https://pay.google.com/gp/v/save/<signed_jwt>
Utente salva / rimuove pass
FASE 03A Google Cloud richiama il webhook
Passinstance:`POST/api/v1/wallet/callbac
Evento: eventType: "save" | "del"
Aggiorna telemetria installaz. attive
Modifica pass lato server
FASE 03B Passinstance esegue PATCH REST
su walletobjects/v1/...Object
Google Play Services sincronizza subito la tessera su Android

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 PassinstanceRisorsa Class GoogleRisorsa Object GoogleCampi specializzati principali
Carte fedeltà e timbriLoyaltyClassLoyaltyObjectloyaltyPoints, secondaryLoyaltyPoints, accountId, accountName, rewardsTier
Coupon e buoni scontoOfferClassOfferObjectredemptionChannel, provider, validTimeInterval, barcode
Gift card e prepagateGiftCardClassGiftCardObjectcardNumber, pin, balance (micros + currencyCode), balanceUpdateTime
Biglietti eventiEventTicketClassEventTicketObjectseatInfo (seat, row, section, gate), ticketHolderName, eventName, doorsOpen
Tessere socio e badge IDGenericClassGenericObjectcardTitle, 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.

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>:

JSON
{
  "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:

JSON
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, incrementa installedDevices e attiva il trigger webhook/workflow PASS_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.

Documentazione prodotto e API correlata

Pronto a lanciare il tuo primo programma di carte Wallet?

Crea il tuo workspace, configura il modello e testa una carta reale in Apple Wallet e Google Wallet prima di scalare.