Creare tessere su Android utilizzando l'API Google Wallet

1. Introduzione

Panoramica

L'API Google Wallet ti consente di interagire con gli utenti tramite vari tipi di tessere: carte fedeltà, offerte, carte regalo, biglietti per eventi, biglietti per il trasporto pubblico, carte d'imbarco e altro ancora. Ogni tipo di tessera, o classe di tessera, è dotato di campi e funzionalità specifici per il caso d'uso per migliorare l'esperienza utente.

Tuttavia, potrebbero non essere adatti a tutti i casi d'uso. Per creare un'esperienza più personalizzata, puoi utilizzare il tipo di tessera generica. Ecco alcuni casi d'uso di esempio per il tipo di tessera generica:

• Tessere per il parcheggio
• Tessere di iscrizione alla biblioteca
• Voucher per il credito monetario
• Tessere di abbonamento a palestre
• Prenotazioni

Puoi utilizzare tessere generiche per qualsiasi caso d'uso che può essere presentato con:

• Fino a tre righe di informazioni
• (Facoltativo) Immagine del codice a barre
• (Facoltativo) Sezione Dettagli

Per saperne di più sull'API Google Wallet o sull'aggiunta di un pulsante Aggiungi a Google Wallet a un'applicazione per Android, consulta la documentazione per sviluppatori di Google Wallet.

Tutte le classi e gli oggetti delle tessere devono rispettare le Norme di utilizzo accettabile.

Passare classi e oggetti

L'API Google Wallet espone metodi per creare quanto segue:

Tipo	Descrizione
Classe di abbonamento	Un modello per un singolo oggetto pass. Contiene informazioni comuni a tutti gli oggetti tessera appartenenti a questa classe.
Oggetto tessera	Un'istanza di una classe di tessera univoca per un ID utente.

Informazioni su questo codelab

In questo codelab completerai le seguenti attività.

1. Crea un nuovo account emittente in modalità demo
2. Creare un service account per l'emissione di tessere
3. Crea una nuova classe di pass generico
4. Creare un nuovo oggetto tessera
5. Crea un pulsante Aggiungi a Google Wallet per salvare una tessera
6. Visualizzare il pulsante nell'app per Android
7. Gestire il risultato del salvataggio della tessera

Prerequisiti

• Android Studio
• Git
• Un Account Google con accesso alla console Google Cloud
• Node.js versione 10 o successive

Obiettivi

Dopo aver completato questo codelab, sarai in grado di:

• Aggiungere l'SDK Google Wallet alla tua app per Android
• Controllare se l'API Google Wallet è disponibile su un dispositivo Android
• Creare un pulsante Aggiungi a Google Wallet

Assistenza

Se ti blocchi in qualsiasi punto del codelab, il repository GitHub google-pay/wallet-android-codelab contiene una soluzione completa a cui fare riferimento.

2. Configurazione

In questo passaggio creerai un account emittente in modalità demo. In questo modo potrai creare classi e oggetti di tessere che possono essere aggiunti ai wallet degli utenti. Successivamente, creerai un progetto Google Cloud e un account di servizio. Verranno utilizzate per creare in modo programmatico classi e oggetti di tessere nello stesso modo di un server di backend. Infine, autorizzerai il service account Google Cloud a gestire le tessere nel tuo account emittente Google Wallet.

È possibile creare classi e oggetti di tessere all'interno di client pubblici come le applicazioni mobile. Tuttavia, è più sicuro creare tessere su un client privato, ad esempio un server di backend, o recuperarle dalle applicazioni client tramite richieste autenticate e sicure.

Registrarsi per un account emittente dell'API Google Wallet

Per creare e distribuire tessere per Google Wallet è necessario un account emittente. Puoi registrarti utilizzando la console di Google Pay e Wallet. Inizialmente, avrai accesso alla creazione di tessere in modalità demo. Ciò significa che solo utenti di test specifici potranno aggiungere le tessere che crei. Gli utenti di test possono essere gestiti nella Google Pay & Wallet Console.

Per ulteriori informazioni sulla modalità demo, consulta i prerequisiti per la tessera generica.

1. Apri la Console di Google Pay e Wallet.
2. Segui le istruzioni sullo schermo per creare un account emittente.
3. Seleziona API Google Wallet.
4. Conferma di aver compreso i Termini di servizio e le Norme sulla privacy
5. Copia il valore dell'ID emittente in un editor di testo o in un'altra posizione.
6. Nella scheda Gestisci, seleziona Configura account di test.
7. Aggiungi gli indirizzi email che utilizzerai in questo codelab

Abilita l'API Google Wallet

1. Accedi alla console Google Cloud.
2. Se non hai ancora un progetto Google Cloud, creane uno ora (per saperne di più, consulta Creazione e gestione dei progetti).
3. Abilita l'API Google Wallet (nota anche come API Google Pay for Passes) per il tuo progetto

Creare un service account e una chiave

Per chiamare l'API Google Wallet sono necessari un service account e una chiave del service account. Il service account è l'identità che chiama l'API Google Wallet. La chiave del service account contiene una chiave privata che identifica la tua applicazione come service account. Questa chiave è sensibile, quindi mantienila riservata.

Fai attenzione quando utilizzi un service account esistente per questo codelab, in quanto potrebbe disporre di autorizzazioni per altre risorse non richieste.

Crea un account di servizio

1. Nella console Google Cloud, apri Service Account.
2. Inserisci un nome, un ID e una descrizione per il service account
3. Seleziona CREA E CONTINUA.
4. Seleziona FINE.

Crea una chiave dell'account di servizio

1. Seleziona il tuo service account
2. Seleziona il menu KEYS (TASTI).
3. Seleziona AGGIUNGI CHIAVE, poi Crea nuova chiave.
4. Seleziona il tipo di chiave JSON.
5. Seleziona CREA.

Ti verrà chiesto di salvare il file della chiave nella tua workstation locale. Assicurati di ricordare la sua posizione.

Imposta la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS

La variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS viene utilizzata dagli SDK Google per l'autenticazione come service account e per accedere a diverse API per un progetto Google Cloud.

1. Segui le istruzioni riportate nella documentazione sulle chiavi degli account di servizio Google Cloud per impostare la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS.
2. Verifica che la variabile di ambiente sia impostata in una nuova sessione di terminale (macOS/Linux) o della riga di comando (Windows). Potresti dover avviare una nuova sessione se ne hai già una aperta.

   echo $GOOGLE_APPLICATION_CREDENTIALS
   

Autorizzare il account di servizio

Infine, dovrai autorizzare il service account a gestire le tessere Google Wallet.

1. Apri la Console di Google Pay e Wallet.
2. Seleziona Utenti.
3. Seleziona Invita un utente.
4. Inserisci l'indirizzo email del service account (ad es. [e-mail])
5. Seleziona Sviluppatore o Amministratore dal menu a discesa Livello di accesso.
6. Seleziona Invita.

3. Crea una classe di tessere generica

In questo passaggio creerai la classe base per la tua tessera. Ogni volta che viene creata una nuova tessera per un utente, questa eredita le proprietà definite nella classe della tessera.

La classe di tessere che creerai durante questo codelab utilizza la flessibilità delle tessere generiche per creare un oggetto che funziona sia come badge di identità sia come tracker dei punti sfida. Quando viene creato un oggetto tessera da questa classe, avrà l'aspetto del seguente grafico.

Questa immagine mostra un piccolo sottoinsieme di proprietà che possono essere impostate su una tessera. Consulta il modello di tessera generica per scoprire in che modo le diverse proprietà della tessera influiscono sull'esperienza utente.

Le classi di tessere possono essere create direttamente nella Console di Google Pay e Wallet o utilizzando l'API Google Wallet. In questo codelab creerai la classe di pass generica utilizzando l'API. Questo segue la procedura che un server di backend privato utilizzerebbe per creare classi di tessere.

1. Clona il repository GitHub google-pay/wallet-android-codelab nella tua workstation locale

   git clone https://github.com/google-pay/wallet-android-codelab.git
   

2. Apri il repository clonato nel terminale o nel prompt della riga di comando.
3. Vai alla directory backend (questi script imitano le azioni del server di backend)

   cd backend
   

4. Installa le dipendenze Node.js

   npm install .
   

5. Nella directory backend, apri generic_class.js.
6. Sostituisci il valore di issuerId con il tuo ID emittente dalla console Google Pay & Wallet.

   // TODO: Define Issuer ID
   let issuerId = 'ISSUER_ID';
   

7. Nel terminale o al prompt della riga di comando, esegui lo script generic_class.js.

   node generic_class.js
   

Quando il codice viene eseguito, crea una nuova classe di tessere e restituisce l'ID classe. L'ID classe è composto dall'ID emittente seguito da un suffisso definito dallo sviluppatore. In questo caso, il suffisso è impostato su codelab_class (l'ID classe sarebbe simile a 1234123412341234123.codelab_class). I log di output includeranno anche la risposta dell'API Google Wallet.

4. Apri il progetto in Android Studio

Il repository GitHub che hai clonato contiene un progetto Android con un'attività vuota. In questo passaggio, modificherai questa attività per includere un pulsante Aggiungi a Google Wallet in una pagina di prodotto.

1. Apri Android Studio
2. Seleziona File e poi Apri.
3. Seleziona la directory android nel repository.
4. Seleziona Apri.

Aggiungere l'SDK Google Wallet alla tua app

1. Apri il file di build Gradle a livello di modulo (android/app/build.gradle).
2. Aggiungi l'SDK Google Wallet alla sezione dependencies

   // TODO: Add the "com.google.android.gms:play-services-pay" dependency to
   //       use the Google Wallet API
   implementation "com.google.android.gms:play-services-pay:16.0.3"
   

3. Salva il file.
4. Seleziona File, poi Sincronizza progetto con file Gradle.

5. Crea il pulsante Aggiungi a Google Wallet

In questo passaggio, creerai un pulsante Aggiungi a Google Wallet e lo aggiungerai a un'attività esistente. Gli asset per il pulsante sono già stati inclusi nel progetto. Per includere il pulsante, devi creare un file di layout separato. Una volta aggiunto, il pulsante avrà questo aspetto.

Se stai aggiungendo il pulsante alla tua applicazione, consulta le linee guida per il brand per scaricare i file SVG del pulsante con le lingue più adatte alle tue esigenze. Assicurati di includere solo elementi grafici per le configurazioni supportate. Puoi importare asset vettoriali in Android Studio in File > Nuovo > Asset vettoriale. Seleziona File locale nella procedura guidata, inserisci un nome (ad es. add_to_google_wallet_button) e individua il file sulla workstation.

1. Crea un nuovo file di layout: app/src/main/res/layout/add_to_google_wallet_button.xml
2. Aggiungi i seguenti contenuti al nuovo file di layout

   <?xml version="1.0" encoding="utf-8"?>
   <FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
       android:layout_width="match_parent"
       android:layout_height="48sp"
       android:background="@drawable/add_to_google_wallet_button_background_shape"
       android:clickable="true"
       android:contentDescription="@string/add_to_google_wallet_button_content_description"
       android:focusable="true">
     <ImageView
         android:layout_width="227dp"
         android:layout_height="26dp"
         android:layout_gravity="center"
         android:duplicateParentState="true"
         android:src="@drawable/add_to_google_wallet_button_foreground" />
   </FrameLayout>
   

3. Includi il layout add_to_google_wallet_button.xml nel file di layout dell'attività di pagamento (app/src/main/res/layout/activity_checkout.xml)

   <!--
       TODO: Create the button under `add_to_google_wallet_button.xml`
             and include it in your UI
   -->
   <include
       android:id="@+id/addToGoogleWalletButton"
       layout="@layout/add_to_google_wallet_button"
       android:layout_width="match_parent"
       android:layout_height="48dp"
       android:layout_marginTop="10dp" />
   

6. Controllare se l'API Google Wallet è disponibile

Se un utente apre la tua app su un dispositivo che non supporta l'API Google Wallet, potrebbe avere un'esperienza negativa quando tenta di aggiungere la tessera. Se il dispositivo dell'utente non supporta l'API Google Wallet, nascondere il pulsante Aggiungi a Google Wallet evita potenziali confusioni. L'API potrebbe non essere disponibile per vari motivi, ad esempio le versioni di Android o Google Play Services non aggiornate o Google Wallet non disponibile nel paese dell'utente.

In questo passaggio, aggiungerai alla tua app una logica che controlla se l'API Google Wallet è disponibile sul dispositivo. In questo caso, il pulsante verrà visualizzato nell'attività. In caso contrario, il pulsante sarà nascosto.

Se utilizzi altri pattern di progettazione, valuta la possibilità di inserire la logica di business specifica del dominio in modo appropriato. Ad esempio, se utilizzi il pattern Model-View-ViewModel (MVVM), inserisci la logica di business correlata all'interfaccia utente nell'attività o nel fragment (ad es. elementi dell'interfaccia utente e risultati dell'attività) e logica operativa nel ViewModel (ad es. istanziazione del client e trigger di chiamate di rete).

1. Apri il file CheckoutActivity.kt in app/src/main/java/com/google/android/gms/samples/wallet/activity/
2. Crea una proprietà di classe per l'istanza PayClient

   // TODO: Create a client to interact with the Google Wallet API
   private lateinit var walletClient: PayClient
   

3. Istanzia la proprietà PayClient nel metodo onCreate

   // TODO: Instantiate the client
   walletClient = Pay.getClient(this)
   

4. Crea un metodo che controlli se l'API e l'SDK Google Wallet sono disponibili sul dispositivo e gestisci il risultato

   // TODO: Create a method to check for the Google Wallet SDK and API
   private fun fetchCanUseGoogleWalletApi() {
     walletClient
       .getPayApiAvailabilityStatus(PayClient.RequestType.SAVE_PASSES)
       .addOnSuccessListener { status ->
         if (status == PayApiAvailabilityStatus.AVAILABLE)
           layout.passContainer.visibility = View.VISIBLE
       }
       .addOnFailureListener {
         // Hide the button and optionally show an error message
       }
   }
   

5. Chiama il metodo fetchCanUseGoogleWalletApi nel metodo onCreate per verificare se l'API Google Wallet è disponibile

   // TODO: Check if the Google Wallet API is available
   fetchCanUseGoogleWalletApi()
   

Quando esegui l'app, ora dovresti vedere il pulsante Aggiungi a Google Wallet nella UI.

Se il pulsante Aggiungi a Google Wallet non viene visualizzato, controlla l'errore restituito dal metodo getPayApiAvailabilityStatus e i log per saperne di più. L'utente in questione potrebbe diventare idoneo a utilizzare l'API in futuro.

7. Crea un oggetto tessera generica

Se il tuo account emittente è in modalità demo, potrai emettere tessere solo per gli utenti di test. Se esegui l'app utilizzando un indirizzo email diverso, non potrai aggiungere la tessera al tuo portafoglio.

Ora che hai verificato che l'API Google Wallet è disponibile, puoi creare una tessera e chiedere all'utente di aggiungerla al proprio wallet. Esistono due flussi per la creazione di oggetti pass per gli utenti.

Crea l'oggetto tessera sul server di backend

In questo approccio, l'oggetto tessera viene creato su un server backend e restituito all'app client come JWT firmato. Questo approccio è più adatto ai casi in cui l'adozione da parte degli utenti è elevata, in quanto garantisce l'esistenza dell'oggetto prima che l'utente tenti di aggiungerlo al proprio portafoglio.

Crea l'oggetto tessera quando l'utente lo aggiunge al proprio wallet

In questo approccio, l'oggetto tessera viene definito e codificato in un JWT firmato sul server di backend. Nell'app client che fa riferimento al JWT viene quindi visualizzato un pulsante Aggiungi a Google Wallet. Quando l'utente seleziona il pulsante, il JWT viene utilizzato per creare l'oggetto tessera. Questa opzione è più adatta ai casi in cui l'adozione da parte degli utenti è variabile o sconosciuta, in quanto impedisce la creazione e il mancato utilizzo degli oggetti pass. Questo approccio verrà utilizzato nel codelab.

1. Apri il file backend/generic_pass.js
2. Sostituisci il valore di issuerId con il tuo ID emittente dalla console Google Pay & Wallet.

   // TODO: Define Issuer ID
   let issuerId = 'ISSUER_ID';
   

3. Nel terminale o nel prompt della riga di comando, esegui il file generic_pass.js

   node generic_pass.js
   

4. Copia il token di output negli appunti o in un editor di testo

Quando il codice viene eseguito, definisce un nuovo oggetto tessera e lo incorpora in un JWT. Il JWT viene quindi firmato dalla chiave del service account che hai creato in precedenza. In questo modo, la richiesta all'API Google Wallet viene autenticata e le credenziali non devono essere memorizzate nell'app client.

aside In un ambiente di produzione, il tuo sistema di backend sarebbe responsabile della creazione dei JWT e della restituzione ai client. In questo codelab, lo script generic_pass.js emula questo comportamento e "restituisce" un token da utilizzare nell'app client.

8. Aggiungere la tessera a Google Wallet

Ora che hai verificato che l'API Google Wallet è disponibile e hai creato un JWT firmato, puoi chiedere all'utente di aggiungere la tessera al proprio wallet. In questo passaggio, aggiungerai un listener al pulsante Aggiungi a Google Wallet che utilizza l'API Google Wallet per salvare la tessera nel wallet dell'utente.

1. Apri il file app/src/main/CheckoutActivity.kt
2. Sostituisci il valore di token con il JWT che hai creato in precedenza.

   // TODO: Save the JWT from the backend "response"
   private val token = "TOKEN"
   

3. Crea una proprietà della classe per memorizzare il codice della richiesta

   // TODO: Add a request code for the save operation
   private val addToGoogleWalletRequestCode = 1000
   

4. Impostare un listener per il pulsante Aggiungi a Google Wallet

   // TODO: Set an on-click listener on the "Add to Google Wallet" button
   addToGoogleWalletButton = layout.addToGoogleWalletButton.root
   
   addToGoogleWalletButton.setOnClickListener {
     walletClient.savePassesJwt(token, this, addToGoogleWalletRequestCode)
   }
   

Quando un utente seleziona il pulsante Aggiungi a Google Wallet, viene chiamato il metodo walletClient.savePassesJwt. Questo metodo chiede all'utente di aggiungere il nuovo oggetto tessera a Google Wallet.

9. Gestisci il risultato di savePassesJwt

Nell'ultimo passaggio di questo codelab, configurerai l'app per gestire il risultato dell'operazione walletClient.savePassesJwt.

1. Apri il file app/src/main/CheckoutActivity.kt
2. Esegui l'override del metodo onActivityResult in modo che contenga il seguente codice

   // TODO: Handle the result
   override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
     super.onActivityResult(requestCode, resultCode, data)
   
     if (requestCode == addToGoogleWalletRequestCode) {
       when (resultCode) {
         RESULT_OK -> {
           // Pass saved successfully. Consider informing the user.
         }
   
         RESULT_CANCELED -> {
           // Save canceled
         }
   
         PayClient.SavePassesResult.SAVE_ERROR ->
           data?.let { intentData ->
             val errorMessage = intentData.getStringExtra(PayClient.EXTRA_API_ERROR_MESSAGE)
             // Handle error. Consider informing the user.
             Log.e("SavePassesResult", errorMessage.toString())
           }
   
         else -> {
           // Handle unexpected (non-API) exception
         }
       }
     }
   }
   

Ora la tua app è in grado di gestire i seguenti scenari:

• Tessera aggiunta correttamente
• Annullamento da parte dell'utente
• Errori imprevisti

Esegui l'app per verificare che tu possa aggiungere la tessera e gestire il risultato come previsto.

10. Complimenti

Congratulazioni, hai integrato correttamente l'API Google Wallet su Android.

Scopri di più

Dai un'occhiata all'integrazione completa nel repository GitHub google-pay/wallet-android-codelab.

Crea tessere e richiedi l'accesso in produzione

Quando è tutto pronto per emettere le tue tessere in produzione, vai alla Google Pay & Wallet Console per richiedere l'accesso in produzione e autorizzare la tua app per Android.

Per saperne di più, consulta i prerequisiti dell'SDK Android.