Quasi tutte le tessere che puoi emettere per un utente finale da salvare in Google Wallet sono definite da due componenti: una classe di tessere e un oggetto tessera. Ogni volta che emetti una tessera per un utente, avrai bisogno di un'istanza di una classe di tessere e di un oggetto tessera, che indica all'API Google Wallet il tipo di tessera da creare, nonché i dettagli da visualizzare sulla tessera, come il valore di una carta regalo o il nome di un titolare del biglietto.
L'API Google Wallet fornisce un insieme predefinito di classi e oggetti delle tessere di cui crei istanze, che poi utilizzi per creare una tessera rilasciata a un utente, ad esempio GiftCardClass e GiftCardObject, GenericClass e GenericObject e altri.
Ogni istanza di classe di tessere e oggetto tessera è definita come oggetto JSON, che ha un insieme di proprietà obbligatorie e facoltative che corrispondono al caso d'uso specifico previsto per quel tipo di tessera.
Classi delle tessere
Considera una classe di tessere come un modello condiviso utilizzato per creare una o più tessere che emetterai per i tuoi utenti. Una classe di tessere definisce un insieme comune di proprietà che verranno incluse in tutte le tessere che vi fanno riferimento.
Ad esempio, la seguente istanza di EventTicketClass definisce i campi comuni a tutti i biglietti emessi per un evento futuro(sede, nome dell'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 di tessere richiede una proprietà id, che specifichi. Questo ID classe
funge da identificatore univoco a cui farai riferimento ogni volta che lo utilizzerai per creare una nuova istanza
dell'oggetto tessera.
Passes Objects
Mentre un'istanza di una classe di tessere specifica un insieme di proprietà condivise da utilizzare in una o più tessere, un oggetto tessera specifica i dettagli univoci di una tessera specifica emessa per un utente specifico.
Ad esempio, quando viene creata una tessera per biglietti per eventi con l'API Google Wallet, un'istanza EventTicketObject
include proprietà per il 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 Pass richiede una proprietà id, che devi specificare. Questo ID oggetto
funge da identificatore univoco a cui farai riferimento quando emetti la tessera per un utente.
Come funzionano le classi di tessere con gli oggetti delle tessere
Gli oggetti Pass devono estendere un'istanza di una classe Pass facendo riferimento al relativo ID classe o includendo la definizione completa della classe Pass. Questa relazione tra un'istanza di una classe di tessere e un oggetto tessera ti consente di impostare e aggiornare le proprietà comuni a tutte le tessere emesse tramite l'istanza della classe di tessere e le proprietà uniche di una singola tessera nell'istanza dell'oggetto tessera.
Ad esempio, il seguente diagramma di una semplice tessera per eventi mostra come i campi definiti in EventTicketClass condiviso e i campi per un biglietto specifico definiti in EventTicketObject si combinano per creare la tessera emessa finale. Nota come viene fatto riferimento all'ID della classe di tessere nella proprietà classId dell'oggetto tessera.
Le modifiche apportate a un'istanza della classe di tessere vengono propagate immediatamente a tutte le istanze dell'oggetto tessera che vi fanno riferimento. Gli utenti vedranno le modifiche apportate a un'istanza della classe Tessere riflesse nella tessera nell'app Google Wallet la volta successiva che eseguiranno la sincronizzazione.
Aggiungere una tessera al Google Wallet di un utente
Per aggiungere una tessera al Google Wallet di un utente, devi creare un token JWT (JSON Web Token) che contenga le attestazioni che tu (l'emittente) stai facendo sull'istanza dell'oggetto tessera che verrà salvata nel Google Wallet dell'utente. L'attestazione più importante è l'ID oggetto dell'istanza dell'oggetto tessera che stai emettendo per l'utente. Il JWT viene quindi inviato 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 emessa al proprio Google Wallet, un link all'istanza dell'oggetto tessere 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 Pass, quindi copie duplicate non verranno aggiunte al wallet dell'utente.
Se un utente rimuove una tessera dall'app Google Wallet, l'istanza dell'oggetto tessera corrispondente viene scollegata automaticamente dall'utente, ma non viene eliminata. Ciò significa che un utente può fare clic di nuovo sul pulsante o sul link Aggiungi a Google Wallet per salvare la tessera senza dover creare una nuova istanza dell'oggetto tessera o un nuovo JWT.