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 del trasporto pubblico, carte d'imbarco e altro ancora. Ogni tipo di tessera o classe di superamento include funzionalità e campi specifici per i casi d'uso che migliorano 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 della biblioteca
• Coupon con valore memorizzato
• Tessere della palestra
• Prenotazioni

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

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

Per ulteriori informazioni sull'API Google Wallet o sull'aggiunta di un pulsante Aggiungi a Google Wallet a un'applicazione Android, consulta la documentazione per gli sviluppatori Google Wallet.

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

Classi e oggetti di superamento

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

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

Informazioni su questo codelab

In questo codelab, completerai le attività seguenti.

1. Crea un nuovo account emittente in modalità demo
2. Crea un account di servizio per l'emissione delle tessere
3. Crea una nuova classe pass generica
4. Crea un nuovo oggetto pass
5. Crea un pulsante Aggiungi a Google Wallet per salvare una tessera
6. Mostrare 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:

• Aggiungi l'SDK Google Wallet alla tua app Android
• Verificare se l'API Google Wallet è disponibile su un dispositivo Android
• Crea un pulsante Aggiungi a Google Wallet

Assistenza

Se non riesci a proseguire in un qualsiasi momento del codelab, il repository GitHub di google-pay/wallet-android-codelab contiene una soluzione completa come riferimento.

2. Configurazione

In questo passaggio, creerai un account emittente in modalità demo. In questo modo potrai creare classi di tessere e oggetti che possono essere aggiunti ai portafogli degli utenti. Ora creerai un progetto Google Cloud e un account di servizio. Verranno utilizzati per creare in modo programmatico classi di passaggio e oggetti, come per un server di backend. Infine, autorizzerai l'account di servizio Google Cloud a gestire le tessere nel tuo account emittente Google Wallet.

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

Creare un account emittente API Google Wallet

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

Per ulteriori informazioni sulla modalità demo, consulta i prerequisiti per il superamento generico.

1. Apri l'app Google Pay e Console di 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 Issuer ID (ID emittente) in un editor di testo o in un'altra posizione.
6. Nella scheda Gestisci, seleziona Configura account di prova.
7. Aggiungi gli indirizzi email che utilizzerai in questo codelab

Abilitare 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. Attiva l'API Google Wallet (nota anche come API Google Pay for Passes) per il tuo progetto

Crea un account di servizio e una chiave

Per chiamare l'API Google Wallet sono necessari un account di servizio e una chiave dell'account di servizio. L'account di servizio è l'identità che chiama l'API Google Wallet. La chiave dell'account di servizio contiene una chiave privata che identifica l'applicazione come account di servizio. Questa chiave è sensibile, quindi mantienila riservata.

Fai attenzione quando utilizzi un account di servizio esistente per questo codelab, poiché potrebbe avere autorizzazioni per altre risorse non necessarie.

Crea un account di servizio

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

Crea una chiave dell'account di servizio

1. Seleziona il tuo account di servizio
2. Seleziona il menu KEYS.
3. Seleziona AGGIUNGI CHIAVE, quindi Crea nuova chiave.
4. Seleziona il tipo di chiave JSON
5. Seleziona CREA

Ti verrà chiesto di salvare il file della chiave sulla workstation locale. Assicurati di memorizzarne la posizione.

Imposta la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS

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

1. Segui le istruzioni nella documentazione relativa alle chiavi dell'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) (potrebbe essere necessario avviare una nuova sessione se ne hai già aperta una)

   echo $GOOGLE_APPLICATION_CREDENTIALS
   

Autorizza l'account di servizio

Infine, dovrai autorizzare l'account di servizio a gestire le tessere di Google Wallet.

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

3. Creare una classe pass generica

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

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

Questo grafico illustra un piccolo sottoinsieme di proprietà che possono essere impostate su una tessera. Consulta il Modello di tessera generico per scoprire in che modo le diverse proprietà della tessera influiscono sull'esperienza utente.

Le classi di pass possono essere create direttamente in Google Pay e Console Wallet o utilizzando l'API Google Wallet. In questo codelab, creerai la classe pass generico utilizzando l'API. Questa operazione segue il processo che un server di backend privato utilizzerebbe per creare classi di accesso.

1. Clona il repository GitHub google-pay/wallet-android-codelab sulla 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 issuerId con il tuo ID emittente indicato in Google Pay e Console di Wallet

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

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

   node generic_class.js
   

Quando viene eseguito, il codice crea una nuova classe pass 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 sarà 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 l'attività in modo da includere un pulsante Aggiungi a Google Wallet nella pagina di un prodotto.

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

Aggiungi 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 il progetto con i 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, dovrai creare un file di layout separato. Una volta aggiunto, il pulsante sarà simile al seguente.

Se aggiungi il pulsante alla tua applicazione, consulta le linee guida per il branding per scaricare i file SVG del pulsante nella lingua o nelle lingue 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 esempio 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. Verificare se l'API Google Wallet è disponibile

Se un utente apre la tua app su un dispositivo che non supporta l'API Google Wallet, potrebbe creare 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 confusione. Esistono diversi motivi per cui l'API potrebbe non essere disponibile, ad esempio le versioni 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 per verificare se l'API Google Wallet è disponibile sul dispositivo. In questo caso, il pulsante verrà visualizzato nell'attività. In caso contrario, il pulsante verrà nascosto.

Se utilizzi altri pattern di progettazione, ti consigliamo di posizionare in modo appropriato la logica di business specifica del dominio. Ad esempio, se utilizzi il pattern Model-View-ViewModel (MVVM), inserisci la logica di business relativa all'interfaccia utente nell'Attività o nel Frammento (ad es.: elementi UI e risultati dell'attività) e logica operativa nel ViewModel (ad es. trigger di istanza client e chiamata di rete).

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

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

3. Crea un'istanza per la proprietà PayClient nel metodo onCreate

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

4. Crea un metodo che verifichi se l'SDK e l'API Google Wallet sono disponibili sul dispositivo e gestisca 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 nell'interfaccia utente.

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

7. Creare un oggetto pass generico

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

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 pass sul server di backend

In questo approccio, l'oggetto pass viene creato su un server di backend e restituito all'app client come un JWT firmato. Questa opzione è più adatta nei casi in cui l'adozione da parte dell'utente è elevata, in quanto garantisce l'esistenza dell'oggetto prima che l'utente provi ad aggiungerlo al proprio portafoglio.

Crea l'oggetto pass quando l'utente lo aggiunge al proprio Wallet

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

1. Apri il file backend/generic_pass.js
2. Sostituisci il valore issuerId con il tuo ID emittente indicato in Google Pay e Console di 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 viene eseguito, il codice definisce un nuovo oggetto pass e lo incorpora in un JWT. Il JWT viene quindi firmato dalla chiave dell'account di servizio creata in precedenza. Questa operazione autentica la richiesta all'API Google Wallet in modo che non sia necessario archiviare le credenziali nell'app client.

In un ambiente di produzione, il tuo sistema di backend sarebbe responsabile della creazione di JWT e della loro 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 portafoglio. 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 creato in precedenza

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

3. Crea una proprietà della classe in cui archiviare il codice di richiesta

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

4. Imposta 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.
   
   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 richiede all'utente di aggiungere il nuovo oggetto tessera a Google Wallet.

9. Gestisci Risultato di savePassesJwt

Nel passaggio finale di questo codelab, configurerai la tua 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:

• Aggiunta di tessera riuscita
• Annullamento utente
• Errori imprevisti

Esegui l'app per confermare di poter aggiungere la tessera e gestire il risultato come previsto.

10. Complimenti

Congratulazioni, hai completato correttamente l'integrazione dell'API Google Wallet su Android.

Scopri di più

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

Crea tessere e richiedi l'accesso in produzione

Quando è tutto pronto per emettere i tuoi pass in produzione, vai alla sezione Google Pay e Console Wallet per richiedere l'accesso in produzione e autorizzare la tua app per Android.

Per scoprire di più, consulta la pagina Prerequisiti dell'SDK Android.