Questo documento elenca la terminologia e i concetti comuni che dovresti conoscere quando utilizzi l'API Google Wallet.
Passaggi
Conforme
Una tessera è un'istanza di un oggetto Passes che viene inviata a un utente per il salvataggio nel suo Google Wallet. L'API Google Wallet supporta vari tipi di tessere comuni, tra cui carte d'imbarco, biglietti per eventi, carte d'identità e altro. L'API Google Wallet fornisce anche un tipo di tessera generica che può essere utilizzato per creare tessere non altrimenti specificatamente supportate.
Nella maggior parte dei casi, una tessera viene creata utilizzando sia una classe Passes che un oggetto Passes.
Emittente tessera
Un emittente della tessera è un'entità che crea tessere e le emette agli utenti affinché possano salvare nel proprio Google Wallet. L'emittente della tessera è proprietaria delle tessere e può crearle, emetterle e aggiornarle. Gli emittenti delle tessere possono essere singoli sviluppatori, aziende e organizzazioni, nonché aggregatori che creano ed emettono tessere per conto di altri, come una società specializzata nell'implementazione di biglietti per eventi o coupon per rivenditori.
Tessere per la classe
Una classe Tessere può essere considerata come un modello condiviso da cui vengono create le tessere. Una classe dei pass definisce alcune proprietà che saranno incluse in tutti i pass che la utilizzano. Un emittente della tessera può creare più classi, ciascuna con il proprio insieme distintivo di proprietà che definiscono attributi come stile e aspetto, nonché funzionalità aggiuntive come Smart Tap, registrazione e accesso.
Nella maggior parte dei casi, una tessera viene creata fornendo una classe Passes per definire il modello della tessera e un oggetto Passes per definire le specifiche del singolo pass emesso.
Trasferimento di oggetti
Un oggetto Passes definisce una singola tessera che viene rilasciata a un utente per essere salvata nel suo Google Wallet. Gli oggetti pass contengono spesso informazioni specifiche sull'utente. Ad esempio, mentre una classe Pass potrebbe definire l'aspetto di una carta regalo per un determinato negozio, l'oggetto Pass fornirà dettagli specifici come il saldo o la data di scadenza.
È necessario creare un oggetto Passes per ogni pass emesso, a differenza delle classi Passes che possono essere condivise tra molte istanze di pass.
Pass privati
Alcune tessere che crei con l'API Google Wallet potrebbero contenere dati utente sensibili. Questi pass richiedono una protezione aggiuntiva per proteggere i dati degli utenti e vengono gestiti in modo diverso nell'API Google Wallet utilizzando il tipo documento privato generico. Il pass privato generico deve essere utilizzato nei casi in cui sono inclusi nel pass dati sensibili (come definiti nelle Norme di utilizzo accettabile dell'API Google Wallet) e potrebbe essere soggetto a ulteriori controlli per la privacy e a una revisione durante l'onboarding.
Smart tap
Smart Tap è un protocollo di comunicazione Near Field Communication di proprietà di Google per trasmettere dati tra un dispositivo mobile e un terminale NFC. La tecnologia Smart Tap consente agli utenti di utilizzare le tessere salvate nel loro Google Wallet avvicinando il telefono a qualsiasi terminale NFC compatibile.
Per utilizzare il protocollo Smart Tap con le tessere, devi stabilire un rapporto con un fornitore di terminali compatibile con Smart Tap.
API e SDK
API Google Wallet
L'API Google Wallet è un servizio fornito da Google che ti consente di creare ed emettere tessere che gli utenti possono salvare nei loro Google Wallet. L'API può essere utilizzata in diversi modi, ad esempio con l'API REST di Google Wallet, l'SDK Google Wallet per Android e la console Google Wallet.
API REST Google Wallet
L'API REST di Google Wallet è un'interfaccia che consente di creare e gestire in modo programmatico le tessere inviando richieste HTTP all'API Google Wallet.
Per utilizzare l'API REST di Google Wallet, ti serve anche un account Google Cloud per creare un account di servizio che viene utilizzato per autenticare le richieste all'API REST di Google Wallet.
SDK Google Wallet Android
L'SDK Google Wallet per Android offre una serie di pratici metodi per utilizzare l'API Google Wallet nelle tue app Android, ad esempio creare ed emettere tessere.
Aggiungi a Google Wallet
Pulsante "Aggiungi a Google Wallet"
Il pulsante "Aggiungi a Google Wallet" è un asset approvato da Google per presentare una tessera a un utente. Quando un utente fa clic sul pulsante o lo tocca, dovrebbe essere attivato un link "Aggiungi a Google Wallet" per avviare la procedura di aggiunta della tessera rilasciata all'account Google Wallet dell'utente.
Ti consigliamo di utilizzare il pulsante "Aggiungi a Google Wallet" quando possibile, poiché si tratta di un elemento UI familiare con cui gli utenti sanno già come interagire.
Gli asset e le linee guida per l'utilizzo del pulsante sono disponibili nelle linee guida per il branding dell'API Google Wallet.
Link "Aggiungi a Google Wallet"
Con il link "Aggiungi a Google Wallet", puoi inviare una tessera a un utente tramite un normale link ipertestuale. Può essere utilizzato ovunque sia possibile utilizzare link ipertestuali, ad esempio email, SMS, siti web e app mobile.
I link "Aggiungi a Google Wallet" vengono creati aggiungendo un JWT firmato all'URL https://pay.google.com/gp/v/save/.
Account emittente
Modalità demo
Al momento della creazione, l'account emittente resterà in "Modalità demo" finché non verrà approvata l'autorizzazione di accesso in pubblicazione. In modalità demo puoi creare tessere, ma puoi assegnarle solo agli utenti con il ruolo "Amministratore" o "Sviluppatore" del tuo account emittente o agli utenti che sono stati aggiunti come account di prova nella console Google Wallet.
In "Modalità Demo", il titolo dei pass che emetti inizierà automaticamente con le parole "[SOLO TEST]" per indicare che il pass è solo a scopo di test.
Account di prova
Quando il tuo account emittente è in "Modalità demo", se vuoi inviare tessere a qualsiasi utente che non dispone dei ruoli "Amministratore" o "Sviluppatore" per il tuo account, devi aggiungerli come account di prova nella console Google Wallet. Gli utenti registrati come account di prova potranno aggiungere le tessere emesse da te a Google Wallet. Questa funzionalità è utile per testare le tessere con un pubblico più ampio in "Modalità demo".
Profilo dell'attività
Per creare un account emittente per l'API Google Wallet, devi configurare un profilo dell'attività quando ti registri alla console Google Pay & Wallet. Un profilo dell'attività fornisce a Google informazioni di base sulla tua azienda o organizzazione e deve essere approvato per l'accesso con diritti di pubblicazione.
Accesso per la pubblicazione
Prima di poter emettere tessere che qualsiasi utente può salvare nel proprio Google Wallet, devi aver ricevuto l'approvazione per l'accesso in pubblicazione. Per ottenere l'approvazione per l'accesso con diritti di pubblicazione, devi aver creato almeno un corso di pass e disporre di un profilo dell'attività completo. Gli emittenti che vogliono emettere tessere utilizzando l'SDK Google Wallet per Android devono inviare anche l'impronta SHA-1 per la loro app.
Per richiedere l'accesso con diritti di pubblicazione, vai alla console di Google Wallet e fai clic sul pulsante "Richiedi accesso con diritti di pubblicazione". Il team di Google Wallet esaminerà la tua richiesta e ti invierà una notifica non appena ti sarà concesso l'accesso con diritti di pubblicazione.
Autenticazione
JSON Web Token (JWT)
I token web JSON sono uno standard di settore di uso comune per trasferire in modo sicuro le informazioni sotto forma di oggetto JSON. Quando utilizzi l'API Google Wallet, codifichi i dettagli dell'oggetto Passes che vuoi utilizzare per creare un'istanza di pass in formato JWT (pronunciato "jot"), quindi invii il JWT in una richiesta all'API Google Wallet.
I JWT vengono protetti firmandoli con un segreto condiviso prima di essere inviati all'API Google Wallet. Se utilizzi l'API REST di Google Wallet, il secret di firma è la chiave dell'account di servizio Google Cloud. Se utilizzi l'SDK Google Wallet per Android, il secret di firma è l'impronta SHA-1 della tua app Android.
Account di servizio
Un account di servizio Google Cloud è un tipo speciale di account generalmente utilizzato da un'applicazione o da un carico di lavoro di computing, anziché da una persona. Nel caso dell'API Google Wallet, un account di servizio è quello che utilizzerai per autenticare le richieste inviate all'API REST di Google Wallet.
Gli account di servizio vengono creati nella console Google Cloud. Per utilizzare un account di servizio, dovrai anche abilitare l'API Google Wallet nella console Cloud per consentire all'account di servizio di effettuare richieste all'API REST di Google Wallet.
Chiave account di servizio
La chiave dell'account di servizio è la credenziale che utilizzerai per autenticare le chiamate all'API REST di Google Wallet. La chiave dell'account di servizio è considerata molto sensibile e deve essere mantenuta privata, in quanto consente di accedere a molte delle funzionalità relative all'emittente della tessera nel tuo account tramite l'API REST di Google Wallet, inclusa la creazione di tessere, corsi e oggetti dei pass.
Impronta SHA-1
L'impronta SHA-1 del certificato di firma della tua app per Android è la credenziale che utilizzerai per autenticare le chiamate all'API Google Wallet quando usi l'SDK Google Wallet per Android. L'impronta SHA-1 del tuo certificato viene generata utilizzando Gradle o keytool. Per autenticare le tue richieste, devi registrarla nella console Google Wallet.