Flusso di sviluppo delle tessere di Google Wallet
L'API Google Wallet fornisce un insieme predefinito di tipi di tessere ottimizzate per casi d'uso specifici, ad esempio carte regalo, carte d'imbarco, biglietti per eventi e altro ancora. Esiste anche un tipo di tessera generico pensato per i casi d'uso in cui un tipo di tessera specifico non è disponibile.
Lo scopo di questo articolo è acquisire familiarità con i passaggi di base necessari per creare e emettere una tessera utilizzando l'API Google Wallet. Esistono diversi modi per eseguire alcuni dei passaggi descritti di seguito, ma a livello generale tutti i tipi di pass vengono creati seguendo lo stesso flusso di sviluppo di base.
Per una procedura dettagliata dettagliata sulla creazione di una tessera, consulta le guide per web, email e SMS o app per Android.
1. Crea un corso di pass
A cosa serve
Una classe Passes definisce un insieme di proprietà comuni a più passaggi, simili a un modello. Ad esempio, se emetti i biglietti per un evento, la classe Pass definisce i campi che sono gli stessi per tutti i biglietti, come nome, data e ora dell'evento.
Ogni tessera emessa deve fare riferimento a una classe di tessere. Devi anche assegnare a ogni classe delle tessere che crei un ID univoco, che verrà utilizzato come riferimento durante la creazione delle tessere.
Come si fa
Una classe di tessere è definita in formato JSON e può essere creata con l'API REST Google Wallet, l'SDK Android o nella Business Console di Google Wallet.
Mostra esempio di classe di tessere
{ "id": "ISSUER_ID.EVENT_CLASS_ID", "issuerName": "[TEST ONLY] Heraldic Event", "localizedIssuerName": { "defaultValue": { "language": "en-US", "value": "[TEST ONLY] Heraldic Event" } }, "logo": { "sourceUri": { "uri": "https://images.unsplash.com/photo-1475721027785-f74eccf877e2?ixlib=rb-4.0.3&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=660&h=660" }, "contentDescription": { "defaultValue": { "language": "en-US", "value": "LOGO_IMAGE_DESCRIPTION" } } }, "eventName": { "defaultValue": { "language": "en-US", "value": "Google Live" } }, "venue": { "name": { "defaultValue": { "language": "en-US", "value": "Shoreline Amphitheater" } }, "address": { "defaultValue": { "language": "en-US", "value": "ADDRESS_OF_THE_VENUE" } } }, "dateTime": { "start": "2023-04-12T11:30" }, "reviewStatus": "UNDER_REVIEW", "hexBackgroundColor": "#264750", "heroImage": { "sourceUri": { "uri": "https://images.unsplash.com/photo-1501281668745-f7f57925c3b4?ixlib=rb-4.0.3&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=1032&h=336" }, "contentDescription": { "defaultValue": { "language": "en-US", "value": "HERO_IMAGE_DESCRIPTION" } } } }
2. Crea un oggetto Passes
A cosa serve
Un oggetto Passes definisce le proprietà di una tessera univoca che verrà inviata a un utente specifico. Ad esempio, l'oggetto Pass di un biglietto per un evento definisce i campi univoci per un determinato biglietto, come il numero del posto o il codice QR del biglietto.
Quando viene creato un oggetto Pass, l'API Google Wallet memorizza una nuova tessera e lo associa al tuo account emittente. Questa tessera archiviata è una combinazione delle proprietà univoche dell'oggetto Passes e delle proprietà del modello della classe Pass associata.
Devi anche assegnare a ciascun oggetto delle tessere un ID univoco, che verrà utilizzato come riferimento quando emetti una tessera.
Come si fa
Un oggetto Passes è un formato JSON definito e può essere creato con l'API REST Google Wallet o l'SDK Android.
Mostra esempio di oggetto tessere
{ "id": "ISSUER_ID.OBJECT_ID", "classId": "ISSUER_ID.EVENT_CLASS_ID", "state": "ACTIVE", "seatInfo": { "seat": { "defaultValue": { "language": "en-us", "value": "5" } }, "row": { "defaultValue": { "language": "en-us", "value": "G" } }, "section": { "defaultValue": { "language": "en-us", "value": "40" } }, "gate": { "defaultValue": { "language": "en-us", "value": "3A" } } }, "barcode": { "type": "QR_CODE", "value": "BARCODE_VALUE", "alternateText": "" } }
3. Codificare la tessera in un token JWT (JSON Web Token).
A cosa serve
Per emettere una tessera a un utente, una classe Passes e un oggetto Passes devono essere codificati in un token web JSON (JWT). Il formato JWT è uno standard aperto e comune per rappresentare le rivendicazioni tra due parti. Nel caso dell'emissione di tessere con l'API Google Wallet, i JWT vengono utilizzati per inviare una rivendicazione secondo cui un utente ha il diritto di accedere a una tessera specifica associata al tuo account emittente.
Quando un JWT viene inviato all'API Google Wallet, i dati codificati vengono utilizzati per identificare una tessera specifica e rilasciarla all'utente. Se la tessera è già stata emessa, questi dati consentono inoltre all'API Google Wallet di identificare che la tessera è un duplicato, in modo che non venga aggiunta all'account Google Wallet dell'utente più volte.
Come si fa
I JWT sono definiti in formato JSON in base alla specifica JWT. Per definire un JWT per l'emissione di una tessera con l'API Google Wallet, devi fornire le informazioni sulla tessera che vuoi emettere nella proprietà payload
del JWT.
Mostra JWT di esempio
{ "iss": "issuer@example.com", "aud": "google", "typ": "savetowallet", "iat": 1696877738, "origins": [ "www.example.com" ], "payload": { "eventTicketObjects": [ { "id": "ISSUER_ID.LOYALTY_OBJECT_SUFFIX" } ] } }
4. Firma il JWT con le tue credenziali
A cosa serve
Tutti i JWT inviati all'API Google Wallet per emettere una tessera devono essere firmati con le credenziali che hai fornito in precedenza nella Business Console di Google Wallet. La firma utilizza le tue credenziali per criptare il JWT in modo che le tue tessere rimangano sicure e per consentire all'API Google Wallet di autenticare la validità dei relativi dettagli codificati e associati al tuo account emittente.
Come si fa
Le librerie client di Google Wallet e l'SDK Android forniscono metodi pratici per firmare i JWT. Sono inoltre disponibili numerose librerie open source che gestiscono la complessità della firma del codice tra cui scegliere.
Per coloro che utilizzano l'API REST di Google Wallet per emettere le tessere, il JWT viene firmato con una chiave dell'account di servizio Google Cloud. Per gli utenti che utilizzano l'SDK Google Wallet per Android, l'SDK gestisce automaticamente la firma del JWT con l'impronta SHA-1 del certificato di firma dell'app.
Per proteggere le tue credenziali, i JWT devono essere firmati solo sul tuo server oppure tramite l'SDK Google Wallet per Android nella tua app.
Mostra un esempio di firma del codice
Java
// Create the JWT as a HashMap object HashMapclaims = new HashMap (); claims.put("iss", ((ServiceAccountCredentials) credentials).getClientEmail()); claims.put("aud", "google"); claims.put("origins", Arrays.asList("www.example.com")); claims.put("typ", "savetowallet"); // Create the Google Wallet payload and add to the JWT HashMap payload = new HashMap (); payload.put("eventTicketObjects", Arrays.asList(newObject)); claims.put("payload", payload); // Google Cloud service account credentials are used to sign the JWT Algorithm algorithm = Algorithm.RSA256( null, (RSAPrivateKey) ((ServiceAccountCredentials) credentials).getPrivateKey()); String token = JWT.create().withPayload(claims).sign(algorithm);
Node.JS
// Create the JWT claims let claims = { iss: this.credentials.client_email, aud: 'google', origins: ['www.example.com'], typ: 'savetowallet', payload: { eventTicketObjects: [newObject] }, }; // The service account credentials are used to sign the JWT let token = jwt.sign(claims, this.credentials.private_key, { algorithm: 'RS256' });
Python
# Create the JWT claims claims = { 'iss': self.credentials.service_account_email, 'aud': 'google', 'origins': ['www.example.com'], 'typ': 'savetowallet', 'payload': { # The listed classes and objects will be created 'eventTicketObjects': [new_object] } } # The service account credentials are used to sign the JWT signer = crypt.RSASigner.from_service_account_file(self.key_file_path) token = jwt.encode(signer, claims).decode('utf-8')
5. Emettere la tessera con un pulsante o un link "Aggiungi a Google Wallet"
A cosa serve
Dopo aver creato un JWT firmato, puoi emettere la tessera a un utente Google Wallet. A questo scopo, presenta all'utente un pulsante "Aggiungi a Google Wallet" pulsante o link. Quando un utente fa clic sul pulsante o sul link ipertestuale, il JWT firmato viene inviato all'API Google Wallet, che quindi lo decripta utilizzando le credenziali salvate. Una volta autenticata la firma JWT, la tessera viene emessa all'utente per il salvataggio in Google Wallet.
Come si fa
Per creare un account "Aggiungi a Google Wallet" per un'app per Android, utilizza l'SDK Google Wallet per Android, che fornisce metodi per generare il pulsante. Per tutte le altre piattaforme, tra cui web, email e messaggi, crea un link ipertestuale nel formato https://pay.google.com/gp/v/save/<signed_jwt>
. Se possibile, è meglio consegnare questo link all'utente sotto forma di "Aggiungi a Google Wallet" .
Per ulteriori informazioni sull'utilizzo dell'app "Aggiungi a Google Wallet" consulta le linee guida per il branding dell'API Google Wallet
Mostra codice di esempio
Link ipertestuale
https://pay.google.com/gp/v/save/<signed_jwt>
SDK per Android
private lateinit var walletClient: PayClient private val addToGoogleWalletRequestCode = 1000 private lateinit var addToGoogleWalletButton: View override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) walletClient = Pay.getClient(this) addToGoogleWalletButton.setOnClickListener { walletClient.savePasses(newObjectJson, this, addToGoogleWalletRequestCode) } }
6. Visualizza in Google Wallet
Una volta che l'utente ha salvato la tessera rilasciata, questa verrà visualizzata nella sua app Google Wallet insieme agli altri pass salvati.
Creazione di oggetti pass e classi di pass nel JWT
Le classi delle tessere e gli oggetti delle tessere possono essere creati in anticipo utilizzando l'API REST Google Wallet o l'SDK Android. Una volta create, vengono utilizzate per emettere le tessere facendo riferimento al loro ID.
In alternativa, puoi anche creare classi e oggetti Pass "Just in time" incorporando il proprio JSON direttamente nel JWT utilizzato per emettere la tessera a un utente. Con questo metodo, le classi di tessere e gli oggetti Passes vengono creati dall'API Google Wallet quando il JWT firmato viene inviato utilizzando un'operazione "Aggiungi a Google Wallet" pulsante o link.
Ad esempio, di seguito viene mostrato un JWT con una nuova classe Passes e un nuovo oggetto Passes definiti utilizzando le proprietà payload.eventTicketClasses
e payload.eventTicketObjects
. Tieni presente che queste proprietà sono array, quindi possono accettare una o più classi Pass o oggetti Pass. Puoi anche specificare un nuovo oggetto tessere nel JWT che fa riferimento a una classe di tessere esistente tramite il suo ID.
Mostra JWT di esempio
{ "iss": "issuer@example.com", "aud": "google", "typ": "savetowallet", "iat": 1696877738, "origins": [ "www.example.com" ], "payload": { "eventTicketClasses": [{ "id": "ISSUER_ID.EVENT_CLASS_ID", "issuerName": "[TEST ONLY] Heraldic Event", "localizedIssuerName": { "defaultValue": { "language": "en-US", "value": "[TEST ONLY] Heraldic Event" } }, "logo": { "sourceUri": { "uri": "https://images.unsplash.com/photo-1475721027785-f74eccf877e2?ixlib=rb-4.0.3&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=660&h=660" }, "contentDescription": { "defaultValue": { "language": "en-US", "value": "LOGO_IMAGE_DESCRIPTION" } } }, "eventName": { "defaultValue": { "language": "en-US", "value": "Google Live" } }, "venue": { "name": { "defaultValue": { "language": "en-US", "value": "Shoreline Amphitheater" } }, "address": { "defaultValue": { "language": "en-US", "value": "ADDRESS_OF_THE_VENUE" } } }, "dateTime": { "start": "2023-04-12T11:30" }, "reviewStatus": "UNDER_REVIEW", "hexBackgroundColor": "#264750", "heroImage": { "sourceUri": { "uri": "https://images.unsplash.com/photo-1501281668745-f7f57925c3b4?ixlib=rb-4.0.3&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=1032&h=336" }, "contentDescription": { "defaultValue": { "language": "en-US", "value": "HERO_IMAGE_DESCRIPTION" } } } }], "eventTicketObjects": [{ "id": "ISSUER_ID.OBJECT_ID", "classId": "ISSUER_ID.EVENT_CLASS_ID", "state": "ACTIVE", "seatInfo": { "seat": { "defaultValue": { "language": "en-us", "value": "5" } }, "row": { "defaultValue": { "language": "en-us", "value": "G" } }, "section": { "defaultValue": { "language": "en-us", "value": "40" } }, "gate": { "defaultValue": { "language": "en-us", "value": "3A" } } }, "barcode": { "type": "QR_CODE", "value": "BARCODE_VALUE", "alternateText": "" } }] } }