Informazioni su questo codelab
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 i casi 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 generico. Ecco alcuni casi d'uso di esempio per il tipo di documento generico:
- Tessere per il parcheggio
- Tessere di adesione alla biblioteca
- Buoni con valore memorizzato
- Tessere per l'abbonamento in palestra
- Prenotazioni
Puoi utilizzare le 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 ulteriori informazioni 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.
Passare classi e oggetti
L'API Google Wallet espone metodi per creare quanto segue:
Tipo | Descrizione |
Passare il corso | Un modello per un singolo oggetto pass. Contiene informazioni comuni a tutti gli oggetti pass che appartengono a questa classe. |
Passare l'oggetto | Un'istanza di una classe di tessere univoca per un ID utente. |
Informazioni su questo codelab
In questo codelab, dovrai completare le seguenti attività.
- Creare un nuovo account emittente in modalità demo
- Crea un account di servizio per emettere le tessere
- Crea una nuova classe Generic pass
- Crea un nuovo oggetto tessera
- Creare un pulsante Aggiungi a Google Wallet per salvare una tessera
- Mostrare il pulsante nell'app per Android
- 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, potrai eseguire le seguenti operazioni:
- Aggiungere l'SDK Google Wallet all'app per Android
- Verificare se l'API Google Wallet è disponibile su un dispositivo Android
- Creare un pulsante Aggiungi a Google Wallet
Assistenza
Se non riesci a procedere in un determinato punto del codelab, il repository GitHub google-pay/wallet-android-codelab contiene una soluzione completa da utilizzare come 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 portafogli degli utenti. A questo punto, dovrai creare un progetto e un account di servizio Google Cloud. Verranno utilizzati per creare in modo programmatico classi e oggetti pass nello stesso modo di un server di backend. Infine, dovrai autorizzare il service account Google Cloud a gestire le tessere nel tuo account emittente Google Wallet.
Registrati per creare un account emittente dell'API Google Wallet
Per creare e distribuire tessere per Google Wallet è necessario un account emittente. Puoi registrarti utilizzando la console Google Pay & Wallet. Inizialmente, avrai accesso alla creazione di pass in modalità demo. Ciò significa che solo utenti di test specifici potranno aggiungere le tessere che crei. Gli utenti di test possono essere gestiti in Google Pay & Wallet Console.
Per ulteriori informazioni sulla modalità demo, consulta i prerequisiti per i permessi generici.
- Apri la console Google Pay & Wallet.
- Segui le istruzioni sullo schermo per creare un account emittente
- Seleziona API Google Wallet.
- Conferma di aver compreso i Termini di servizio e le Norme sulla privacy
- Copia il valore Issuer ID in un editor di testo o in un'altra posizione.
- Nella scheda Gestisci, seleziona Configura account di prova.
- Aggiungi gli indirizzi email che utilizzerai in questo codelab
Abilita l'API Google Wallet
- Accedi alla console Google Cloud.
- Se non hai ancora un progetto Google Cloud, creane uno ora (per ulteriori informazioni, consulta Creare e gestire i progetti).
- Abilita l'API Google Wallet (chiamata anche API Google Pay for Passes) per il tuo progetto
Creare 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 la tua applicazione come account di servizio. Questa chiave è sensibile, quindi mantienila riservata.
Crea un account di servizio
- Nella console Google Cloud, apri Account di servizio.
- Inserisci un nome, un ID e una descrizione per l'account di servizio
- Seleziona CREA E CONTINUA.
- Seleziona FINE.
Crea una chiave dell'account di servizio
- Seleziona il tuo account di servizio
- Seleziona il menu KEYS (CHIAVI).
- Seleziona AGGIUNGI CHIAVE, quindi Crea nuova chiave.
- Seleziona il tipo di chiave JSON
- Seleziona CREA.
Ti verrà chiesto di salvare il file della chiave nella tua workstation locale. Assicurati di ricordare la posizione.
Imposta la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS
La variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS
viene utilizzata dagli SDK Google per autenticarsi come account di servizio e accedere a diverse API per un progetto Google Cloud.
- Segui le istruzioni riportate nella documentazione relativa alle chiavi degli account di servizio Google Cloud per impostare la variabile di ambiente
GOOGLE_APPLICATION_CREDENTIALS
- Verifica che la variabile di ambiente sia impostata in una nuova sessione di terminale (MacOS/Linux) o riga di comando (Windows) (potrebbe essere necessario avviare una nuova sessione se ne hai già una aperta).
echo $GOOGLE_APPLICATION_CREDENTIALS
Autorizza l'account di servizio
Infine, dovrai autorizzare l'account di servizio a gestire le tessere Google Wallet.
- Apri la console Google Pay & Wallet.
- Seleziona Utenti.
- Seleziona Invita un utente.
- Inserisci l'indirizzo email dell'account di servizio (ad es.
test-svc@myproject.iam.gserviceaccount.com
) - Seleziona Sviluppatore o Amministratore dal menu a discesa Livello di accesso.
- Seleziona Invita.
3. Crea una classe di documenti generici
In questo passaggio, creerai la classe di base per la tessera. Ogni volta che viene creato un nuovo documento per un utente, questo eredita le proprietà definite nella classe del documento.
La classe della tessera che creerai durante questo codelab utilizza la flessibilità delle tessere generiche per creare un oggetto che funge sia da badge di identità sia da tracker dei punti della sfida. Quando viene creato un oggetto pass da questa classe, avrà il seguente aspetto.
Le classi di pass possono essere create direttamente nella Console di Google Pay e Wallet o utilizzando l'API Google Wallet. In questo codelab, creerai la classe Generic pass utilizzando l'API. Questo segue la procedura utilizzata da un server di backend privato per creare classi di passaggio.
- Clona il repository GitHub google-pay/wallet-android-codelab nella tua workstation locale
git clone https://github.com/google-pay/wallet-android-codelab.git
- Apri il repository clonato nel terminale o nel prompt dei comandi
- Vai alla directory
backend
(questi script simulano le azioni del server di backend)cd backend
- Installa le dipendenze Node.js
npm install .
- Nella directory
backend
, aprigeneric_class.js
- Sostituisci il valore di
issuerId
con il tuo ID emittente da Google Pay & Wallet Console// TODO: Define Issuer ID
let issuerId = 'ISSUER_ID'; - Nel terminale o nel prompt della riga di comando, esegui lo script
generic_class.js
node generic_class.js
Quando il codice viene eseguito, viene creato un nuovo gruppo di permessi e viene visualizzato l'ID gruppo. L'ID classe è costituito 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, apporterai modifiche a questa attività per includere un pulsante Aggiungi a Google Wallet nella pagina di un prodotto.
- Apri Android Studio
- Seleziona File e poi Apri.
- Seleziona la directory
android
nel repository - Seleziona Apri.
Aggiungere l'SDK Google Wallet all'app
- Apri il file di compilazione Gradle a livello di modulo (
android/app/build.gradle
) - 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" - Salva il file
- Seleziona File e poi Sincronizza 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 avrà il seguente aspetto.
- Crea un nuovo file di layout:
app/src/main/res/layout/add_to_google_wallet_button.xml
- 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> - 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 confusioni. Esistono vari motivi per cui l'API potrebbe non essere disponibile, ad esempio le versioni di Android o Google Play Services non aggiornate o la mancata disponibilità di Google Wallet nel paese dell'utente.
In questo passaggio, aggiungerai alla tua app la 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 verrà nascosto.
- Apri il file
CheckoutActivity.kt
inapp/src/main/java/com/google/android/gms/samples/wallet/activity/
- 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 - Crea un'istanza della proprietà
PayClient
nel metodoonCreate
// TODO: Instantiate the client
walletClient = Pay.getClient(this) - Crea un metodo che controlli se l'SDK e l'API 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
}
} - Chiama il metodo
fetchCanUseGoogleWalletApi
nel metodoonCreate
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.
7. Creare un oggetto Generic pass
Ora che hai verificato che l'API Google Wallet è disponibile, puoi creare una tessera e chiedere all'utente di aggiungerla al suo portafoglio. Esistono due flussi per creare 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 JWT firmato. Questa opzione è più adatta ai casi in cui l'adozione da parte degli utenti è elevata, in quanto garantisce che l'oggetto esista prima che l'utente provi ad aggiungerlo al proprio portafoglio.
Crea l'oggetto tessera quando l'utente la aggiunge al proprio portafoglio
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 per i casi in cui l'adozione da parte degli utenti è variabile o sconosciuta, in quanto impedisce la creazione di oggetti pass e il loro mancato utilizzo. Questo approccio verrà utilizzato nel codelab.
- Apri il file
backend/generic_pass.js
- Sostituisci il valore di
issuerId
con il tuo ID emittente da Google Pay & Wallet Console// TODO: Define Issuer ID
let issuerId = 'ISSUER_ID'; - Nel terminale o nel prompt della riga di comando, esegui il file
generic_pass.js
node generic_pass.js
- Copia il token di output negli appunti o in un editor di testo
Quando il codice viene eseguito, definisce un nuovo oggetto pass e lo incorpora in un JWT. Il JWT viene poi firmato dalla chiave dell'account di servizio creata in precedenza. In questo modo, la richiesta all'API Google Wallet viene autenticata in modo che le credenziali non debbano essere memorizzate nell'app client.
aside In un ambiente di produzione, il sistema di backend è responsabile della creazione dei token 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 suo portafoglio. In questo passaggio, aggiungerai un ascoltatore al pulsante Aggiungi a Google Wallet che utilizza l'API Google Wallet per salvare la tessera nel portafoglio dell'utente.
- Apri il file
app/src/main/CheckoutActivity.kt
- Sostituisci il valore di
token
con il token JWT creato in precedenza// TODO: Save the JWT from the backend "response"
private val token = "TOKEN" - Crea una proprietà di classe per memorizzare il codice richiesta
// TODO: Add a request code for the save operation
private val addToGoogleWalletRequestCode = 1000 - Impostare un ascoltatore 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 chiede all'utente di aggiungere il nuovo oggetto tessera a Google Wallet.
9. Gestire il risultato savePassesJwt
Nel passaggio finale di questo codelab, configurerai l'app per gestire il risultato dell'operazione walletClient.savePassesJwt
.
- Apri il file
app/src/main/CheckoutActivity.kt
- Sostituisci il 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 della tessera andata a buon fine
- Annullamento da parte dell'utente
- Errori imprevisti
Esegui l'app per verificare di poter aggiungere la tessera e gestire il risultato come previsto.
10. Complimenti
Complimenti, 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.
Creare pass e richiedere l'accesso in produzione
Quando è tutto pronto per emettere le tue tessere in produzione, vai a 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.