Skip to content
Torna al blog

Come creare un pass Google Wallet: Guida all'integrazione

Google Wallet API, token JWT firmati e classi di pass generici.

Passinstance Team
Passinstance Team

Wallet pass platform team

2026-08-163 min di lettura
Immagine di copertina per Come creare un pass Google Wallet: Guida all'integrazione

Google Wallet offre agli utenti Android un hub sicuro e preinstallato per gestire carte fedeltà digitali, biglietti per eventi, offerte, gift card, carte d'imbarco e tessere associative.

Questa guida completa per il 2026 analizza l'architettura della Google Wallet API, le credenziali dell'emittente, la relazione tra Classi e Oggetti, i link di salvataggio JWT firmati e gli aggiornamenti push Android in tempo reale.


1. Architettura Google Wallet: Classi vs. Oggetti

A differenza del singolo bundle .pkpass di Apple Wallet, Google Wallet separa i dati del pass in una Classe (Class) e un Oggetto (Object):

  • Pass Class: definisce le proprietà principali del layout, gli asset del brand, il logo, il colore primario, il nome dell'emittente e le condizioni generali del programma condivise da tutti gli utenti.
  • Pass Object: definisce lo stato specifico del singolo utente, il nome del cliente, i numeri seriali e i codici a barre individuali, il saldo punti corrente e la data di scadenza.
FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
FLUSSO ARCHITETTURALE
FASE 01 Classe Google Wallet (Modello principale)
FASE 02A Oggetto utente A (Jane Doe • 1.250 punti)
FASE 02B Oggetto utente B (John Smith • 500 punti)
FASE 02C Oggetto utente C (Alex Morgan • Livello Gold)

2. Configurazione della Google Pay & Wallet Console

Per emettere pass Google Wallet in modo nativo:

  1. 1
    Account emittente (Issuer Account): richiedi un Issuer Account nella Google Pay & Wallet Console.
  2. 2
    Credenziali Service Account: crea un Service Account su Google Cloud, assegna i permessi Google Wallet API Developer e scarica il file JSON con la chiave privata RSA.
  3. 3
    Definizione della Classe: pubblica una Pass Class (ad es. issuerId.loyalty_class_2026) tramite la Google Wallet REST API.

[!NOTE]

Opzione di avvio immediato: Passinstance è un emittente Google Wallet approvato e pre-verificato. Puoi lanciare pass Google Wallet immediatamente senza dover attendere settimane per la verifica aziendale di Google.


I pass Google Wallet vengono distribuiti mediante JSON Web Token (JWT) firmati crittograficamente e incorporati in normali URL HTTPS:

TS
import jwt from "jsonwebtoken";

const claims = {
  iss: serviceAccount.client_email,
  aud: "google",
  typ: "savetowallet",
  iat: Math.floor(Date.now() / 1000),
  payload: {
    loyaltyObjects: [
      {
        id: "338810294.user_pass_jane_2048",
        classId: "338810294.loyalty_class_v1",
        state: "ACTIVE",
        accountName: "Jane Doe",
        accountId: "MEM-2048",
        barcode: {
          type: "QR_CODE",
          value: "PASS-LOYALTY-8842",
        },
      },
    ],
  },
};

const token = jwt.sign(claims, serviceAccount.private_key, { algorithm: "RS256" });
const saveUrl = `https://pay.google.com/gp/v/save/${token}`;

Quando un cliente Android tocca questo link o scansiona un codice QR, Google Wallet verifica la firma del JWT e aggiunge il pass direttamente al dispositivo.


Ispettore campi — Associa variabili condivise come {storedValue} con override opzionali per Android
Ispettore campi — Associa variabili condivise come {storedValue} con override opzionali per Android

4. Aggiornamenti Over-The-Air tramite Google Wallet REST API

Quando un cliente accumula punti o riscatta un premio, puoi aggiornare il pass sui dispositivi Android inviando una richiesta PATCH alla Google Wallet REST API:

HTTP
PATCH /walletobjects/v1/loyaltyObject/338810294.user_pass_jane_2048 HTTP/1.1
Host: walletobjects.googleapis.com
Authorization: Bearer <OAuth2_Token>
Content-Type: application/json

{
  "loyaltyPoints": {
    "label": "Points",
    "balance": {
      "int": 1500
    }
  }
}

Il backend di Google aggiorna il dispositivo Android in tempo reale e attiva una notifica nativa nell'area notifiche.


5. Emissione automatizzata su Google Wallet con Passinstance

Passinstance unifica Apple Wallet e Google Wallet dietro un'unica chiamata API e un unico editor visuale:

TS
import { Passinstance } from "@passinstance/sdk";

const client = new Passinstance({ apiKey: process.env.PASSINSTANCE_API_KEY });

// Publish pass to both Apple Wallet and Google Wallet from one template
const pass = await client.passes.create({
  templateId: "tpl_retail_rewards",
  data: {
    customerName: "Jane Doe",
    points: 1500,
  },
});

console.log("Add to Google Wallet Link:", pass.googleWalletUrl);
Anteprima live Dual-Wallet — Passa rapidamente tra i layout Apple Wallet e Google Wallet
Anteprima live Dual-Wallet — Passa rapidamente tra i layout Apple Wallet e Google Wallet

Punti chiave

  • Nessuna app Android richiesta: i clienti toccano un link web o scansionano un codice QR per aggiungere i pass a Google Wallet.
  • Modello unificato: mantieni un unico design che viene compilato in modo pulito sia per Android sia per iOS.
  • Aggiornamenti Over-The-Air istantanei: invia variazioni dei punti e comunicazioni direttamente sulle schermate di blocco Android.
Demo interattiva dal vivo
Apple Wallet e Google Wallet

Prova un vero pass Wallet sul tuo smartphone

Prova in prima persona come funzionano i pass digitali. Scansiona con la fotocamera o tocca qui sotto per aggiungere il pass in Apple Wallet o Google Wallet.

Artisan RoastersCafé & F&B
Test QR code for Artisan Roasters

Scansiona con la fotocamera

Correlato in questo argomento

API per sviluppatori e integrazioni

Apri hub di argomenti

Pronto a lanciare il tuo programma di carte wallet?

Crea il tuo account, progetta il tuo modello di carta e testa carta reali direttamente in Apple Wallet e Google Wallet.