Quasi tutte le tessere che puoi emettere affinché un utente finale possa salvare nel suo Google Wallet sono definite da due componenti: una classe Tessere e un oggetto Pass. Ogni volta che emetti un pass a un utente, hai bisogno di un'istanza sia di una classe Passes sia di un oggetto Passes, che indica all'API Google Wallet il tipo di pass da creare e i dettagli da mostrare sulla tessera, come il valore di una carta regalo o il nome di un titolare.
L'API Google Wallet fornisce un insieme predefinito di tessere e oggetti di cui puoi creare istanze, quindi utilizzare per creare una tessera che viene rilasciata a un utente, ad esempio GiftCardClass e GiftCardObject, GenericClass e GenericObject e altri.
Ogni istanza Passes Class e Passes Object è definita come oggetto JSON, che ha un insieme di proprietà obbligatorie e facoltative che corrispondono al caso d'uso specifico destinato a quel tipo di pass.
Pass per i corsi
Pensa a un corso di pass come a un modello condiviso che viene utilizzato per creare una o più tessere che fornirai agli utenti. Una classe Passes definisce un insieme comune di proprietà che saranno incluse in tutti i pass che vi fanno riferimento.
Ad esempio, la seguente istanza di EventTicketClass definisce i campi comuni a tutti i biglietti emessi per un evento imminente(sede, nome evento, emittente, data/ora).
{
"id": "ISSUER_ID.EVENT_CLASS_ID",
"issuerName": "[TEST ONLY] Heraldic Event",
"localizedIssuerName": {
"defaultValue": {
"language": "en-US",
"value": "[TEST ONLY] Heraldic Event"
}
},
"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"
}
Ogni istanza di una classe Passes richiede una proprietà id, da te specificata. Questo ID classe
agisce come un identificatore univoco a cui farai riferimento ogni volta che lo utilizzi per creare una nuova istanza di Passes Object.
Trasferimento di oggetti
Mentre un'istanza di una classe Passes specifica un insieme di proprietà condivise da utilizzare in uno o più pass, un oggetto Passes specifica i dettagli univoci di un pass specifico emesso a un utente specifico.
Ad esempio, quando viene creato un pass per l'evento con l'API Google Wallet, un'istanza EventTicketObject
include le proprietà del posto assegnato a quel biglietto, poiché questi valori saranno univoci per ogni
biglietto emesso.
{
"id": "ISSUER_ID.OBJECT_ID",
"classId": "ISSUER_ID.EVENT_CLASS_ID",
"state": "ACTIVE",
"seatInfo": {
"seat": {
"defaultValue": {
"language": "en-us",
"value": "9"
}
},
"row": {
"defaultValue": {
"language": "en-us",
"value": "L"
}
},
"section": {
"defaultValue": {
"language": "en-us",
"value": "45"
}
},
"gate": {
"defaultValue": {
"language": "en-us",
"value": "7C"
}
}
},
"barcode": {
"type": "BARCODE_TYPE_UNSPECIFIED",
"value": "BARCODE_VALUE",
"alternateText": ""
}
}
Ogni istanza di un oggetto Passes richiede una proprietà id, che specifichi. Questo ID oggetto
funge da identificatore univoco a cui farai riferimento quando emetti il pass a un utente.
Come funzionano i pass dei corsi con gli oggetti Passes
Gli oggetti Passes devono estendere un'istanza di una classe Passes facendo riferimento al relativo ID classe o includendo la definizione completa della classe Passes. Questa relazione tra un'istanza Passes Class e l'oggetto Passes consente di impostare e aggiornare le proprietà comuni a tutti i pass emessi tramite l'istanza Passes Class e le proprietà univoche di un singolo passaggio nell'istanza di Passes Object.
Ad esempio, il seguente diagramma di un pass semplice per un biglietto per un evento mostra come i campi definiti nel pass condiviso EventTicketClass e quelli relativi a un biglietto specifico definito in EventTicketObject vengono combinati per generare il pass finale emesso. Nota come viene fatto riferimento all'ID della classe Passes nella proprietà classId dell'oggetto Passes.
Le modifiche apportate a un'istanza di Passes Class verranno propagate immediatamente in tutte le istanze di Passes Object che fanno riferimento. Le modifiche apportate a un'istanza di Passes Class verranno applicate alla tessera nell'app Google Wallet alla successiva sincronizzazione degli utenti.
Aggiungere una tessera a Google Wallet di un utente
Per aggiungere una tessera a Google Wallet di un utente, crea un token JWT (JSON Web Token) contenente le rivendicazioni che tu (l'emittente) stai inviando in merito all'istanza dell'oggetto Passes che verrà salvata nel Google Wallet dell'utente, soprattutto l'ID oggetto dell'istanza dell'oggetto Passes che stai inviando all'utente. Il JWT viene quindi consegnato all'utente tramite un pulsante Aggiungi a Google Wallet o un link Aggiungi a Google Wallet.
Dopo che un utente fa clic sul pulsante o sul link per aggiungere una tessera rilasciata a Google Wallet, un link dell'istanza dell'oggetto Passes codificata nel JWT viene collegato all'Account Google dell'utente. Ciò significa che quando l'utente fa di nuovo clic sul pulsante, esiste già un link all'oggetto Passes, quindi le copie duplicate non verranno aggiunte al portafoglio dell'utente.
Se un utente rimuove una tessera dall'app Google Wallet, l'istanza dell'oggetto Passes corrispondente viene scollegata automaticamente dall'utente, ma non viene eliminata. Ciò significa che un utente può fare di nuovo clic sul pulsante Aggiungi a Google Wallet o sul link per salvare la tessera senza dover creare una nuova istanza di Passes Object o JWT.