Créer des cartes sur Android à l'aide de l'API Google Wallet

1. Introduction

Présentation

L'API Google Wallet vous permet d'interagir avec les utilisateurs par le biais de différents types de cartes : cartes de fidélité, offres, cartes cadeaux, billets pour un événement, titres de transport, cartes d'embarquement, etc. Chaque type de pass ou classe de pass est fourni avec des champs et des fonctionnalités spécifiques à un cas d'utilisation pour améliorer l'expérience utilisateur.

Toutefois, ces catégories ne sont pas adaptées à tous les cas d'utilisation. Pour créer une expérience plus personnalisée, vous pouvez utiliser le type de pass générique. Voici quelques exemples d'utilisation du type de carte générique :

• Tickets de stationnement
• Cartes de bibliothèque
• Coupons
• Abonnements de gym
• Réservations

Vous pouvez utiliser des cartes génériques pour tous les cas d'utilisation pouvant être présentés avec :

• Jusqu'à trois lignes d'informations
• (Facultatif) Image du code-barres
• (Facultatif) Section "Détails"

Pour en savoir plus sur l'API Google Wallet ou sur l'ajout d'un bouton Ajouter à Google Wallet à une application Android, consultez la documentation pour les développeurs Google Wallet.

Toutes les classes et tous les objets de carte doivent respecter les Règles d'utilisation autorisée.

Classes et objets de carte

L'API Google Wallet expose des méthodes permettant de créer les éléments suivants :

Type	Description
Classe de carte	Modèle pour un objet de carte individuel. Il contient des informations communes à tous les objets Carte appartenant à cette classe.
Objet de carte	Instance d'une classe de pass unique à un ID utilisateur.

À propos de cet atelier de programmation

Dans cet atelier de programmation, vous allez effectuer les tâches suivantes :

1. Créer un compte d'émetteur en mode démo
2. Créer un compte de service pour émettre des cartes
3. Créer une classe de carte générique
4. Créer un objet Pass
5. Créer un bouton Ajouter à Google Wallet pour enregistrer une carte
6. Afficher le bouton dans votre application Android
7. Gérer le résultat de l'enregistrement de la carte

Prérequis

• Android Studio
• Git
• Un compte Google ayant accès à la console Google Cloud
• Node.js version 10 ou ultérieure

Objectifs

À la fin de cet atelier de programmation, vous saurez :

• Ajouter le SDK Google Wallet à votre application Android
• Vérifier si l'API Google Wallet est disponible sur un appareil Android
• Créer un bouton Ajouter à Google Wallet

Assistance

Si vous rencontrez des difficultés à un moment donné de l'atelier de programmation, le dépôt GitHub google-pay/wallet-android-codelab contient une solution complète pour référence.

2. Configuration

Dans cette étape, vous allez créer un compte d'émetteur en mode démo. Cela vous permettra de créer des classes et des objets de pass pouvant être ajoutés aux portefeuilles des utilisateurs. Ensuite, vous allez créer un projet et un compte de service Google Cloud. Ils seront utilisés pour créer des classes et des objets de cartes de manière programmatique, de la même manière qu'un serveur de backend. Enfin, vous autoriserez le compte de service Google Cloud à gérer les cartes dans votre compte émetteur Google Wallet.

Il est possible de créer des classes et des objets de cartes dans des clients publics tels que des applications mobiles. Toutefois, il est plus sûr de créer des cartes sur un client privé tel qu'un serveur backend ou en les récupérant à partir de vos applications clientes via des requêtes authentifiées et sécurisées.

S'inscrire pour obtenir un compte d'émetteur pour l'API Google Wallet

Un compte d'émetteur est nécessaire pour créer et distribuer des cartes pour Google Wallet. Vous pouvez vous inscrire à l'aide de la Google Pay & Wallet Console. Au début, vous pourrez créer des cartes en mode démo. Cela signifie que seuls certains utilisateurs de test pourront ajouter les cartes que vous créez. Vous pouvez gérer les utilisateurs de test dans la Google Pay & Wallet Console.

Pour en savoir plus sur le mode Démo, consultez les Conditions préalables génériques pour les pass.

1. Ouvrez la Google Pay & Wallet Console.
2. Suivez les instructions à l'écran pour créer un compte émetteur.
3. Sélectionnez API Google Wallet.
4. Confirmez que vous comprenez les conditions d'utilisation et les règles de confidentialité.
5. Copiez la valeur de l'ID de l'émetteur dans un éditeur de texte ou à un autre emplacement.
6. Dans l'onglet Gérer, sélectionnez Configurer des comptes de test.
7. Ajoutez les adresses e-mail que vous utiliserez dans cet atelier de programmation.

Activer l'API Google Wallet

1. Connectez-vous à la console Google Cloud.
2. Si vous n'avez pas encore de projet Google Cloud, créez-en un maintenant (pour en savoir plus, consultez Créer et gérer des projets).
3. Activez l'API Google Wallet (également appelée API Google Pay for Passes) pour votre projet.

Créer un compte de service et une clé

Vous devez disposer d'un compte de service et d'une clé de compte de service pour appeler l'API Google Wallet. Le compte de service est l'identité qui appelle l'API Google Wallet. La clé du compte de service contient une clé privée qui identifie votre application en tant que compte de service. Cette clé est sensible et doit rester confidentielle.

Soyez prudent lorsque vous utilisez un compte de service existant pour cet atelier de programmation, car il peut disposer d'autorisations pour d'autres ressources qui ne sont pas requises.

Créer un compte de service

1. Dans la console Google Cloud, ouvrez Comptes de service.
2. Saisissez un nom, un ID et une description pour votre compte de service.
3. Sélectionnez CRÉER ET CONTINUER.
4. Sélectionnez OK.

Créer une clé de compte de service

1. Sélectionnez votre compte de service.
2. Sélectionnez le menu CLÉS.
3. Sélectionnez AJOUTER UNE CLÉ, puis Créer une clé.
4. Sélectionnez le type de clé JSON.
5. Sélectionnez CRÉER.

Vous serez invité à enregistrer le fichier de clé sur votre poste de travail local. N'oubliez pas où il se trouve.

Définir la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS

La variable d'environnement GOOGLE_APPLICATION_CREDENTIALS est utilisée par les SDK Google pour s'authentifier en tant que compte de service et accéder à différentes API pour un projet Google Cloud.

1. Suivez les instructions de la documentation sur les clés de compte de service Google Cloud pour définir la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS.
2. Vérifiez que la variable d'environnement est définie dans une nouvelle session de terminal (macOS/Linux) ou de ligne de commande (Windows). Vous devrez peut-être démarrer une nouvelle session si vous en avez déjà une d'ouverte.

   echo $GOOGLE_APPLICATION_CREDENTIALS
   

Autoriser le compte de service

Enfin, vous devrez autoriser le compte de service à gérer les pass Google Wallet.

1. Ouvrez la Google Pay & Wallet Console.
2. Sélectionnez Utilisateurs.
3. Sélectionnez Inviter un utilisateur.
4. Saisissez l'adresse e-mail du compte de service (par exemple, [e-mail]).
5. Sélectionnez Développeur ou Administrateur dans le menu déroulant Niveau d'accès.
6. Sélectionnez Inviter.

3. Créer une classe de carte générique

Dans cette étape, vous allez créer la classe de base pour votre carte. Chaque fois qu'une carte est créée pour un utilisateur, elle hérite des propriétés définies dans la classe de carte.

La classe de carte que vous allez créer au cours de cet atelier de programmation utilise la flexibilité des cartes génériques pour créer un objet fonctionnant à la fois comme un badge d'identité et comme un outil de suivi des points de défi. Lorsqu'un objet de carte est créé à partir de cette classe, il ressemble à l'illustration suivante.

Ce graphique illustre un petit sous-ensemble de propriétés qui peuvent être définies sur une carte. Consultez le modèle de pass générique pour voir comment les différentes propriétés de pass affectent l'expérience utilisateur.

Les classes de cartes peuvent être créées directement dans la Google Pay & Wallet Console ou à l'aide de l'API Google Wallet. Dans cet atelier de programmation, vous allez créer la classe de carte générique à l'aide de l'API. Cela suit le processus qu'un serveur backend privé utiliserait pour créer des classes de pass.

1. Clonez le dépôt GitHub google-pay/wallet-android-codelab sur votre poste de travail local.

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

2. Ouvrez le dépôt cloné dans votre terminal ou votre invite de ligne de commande.
3. Accédez au répertoire backend (ces scripts imitent les actions du serveur backend).

   cd backend
   

4. Installer les dépendances Node.js

   npm install .
   

5. Dans le répertoire backend, ouvrez generic_class.js.
6. Remplacez la valeur de issuerId par votre ID d'émetteur dans la Google Pay & Wallet Console.

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

7. Dans votre terminal ou votre invite de commande, exécutez le script generic_class.js.

   node generic_class.js
   

Lorsque votre code s'exécute, il crée une classe de pass et affiche l'ID de la classe. L'ID de classe est composé de l'ID de l'émetteur suivi d'un suffixe défini par le développeur. Dans ce cas, le suffixe est défini sur codelab_class (l'ID de classe ressemblerait à 1234123412341234123.codelab_class). Les journaux de sortie incluront également la réponse de l'API Google Wallet.

4. Ouvrir le projet dans Android Studio

Le dépôt GitHub que vous avez cloné contient un projet Android avec une activité vide. Au cours de cette étape, vous allez modifier cette activité pour inclure un bouton Ajouter à Google Wallet sur une page produit.

1. Ouvrir Android Studio
2. Sélectionnez Fichier, puis Ouvrir.
3. Sélectionnez le répertoire android dans le dépôt.
4. Sélectionnez Ouvrir.

Ajouter le SDK Google Wallet à votre application

1. Ouvrez le fichier de compilation Gradle au niveau du module (android/app/build.gradle).
2. Ajoutez le SDK Google Wallet à la section 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. Enregistrez le fichier.
4. Sélectionnez File (Fichier), puis Sync Project with Gradle Files (Synchroniser le projet avec les fichiers Gradle).

5. Créer le bouton "Ajouter à Google Wallet"

Au cours de cette étape, vous allez créer un bouton Ajouter à Google Wallet et l'ajouter à une activité existante. Les éléments du bouton ont déjà été inclus dans le projet. Pour inclure le bouton, vous allez créer un fichier de mise en page distinct. Une fois ajouté, le bouton se présente comme suit.

Si vous ajoutez ce bouton à votre propre application, consultez les Consignes relatives à la marque pour télécharger les fichiers SVG du bouton avec les langues de votre choix. Veillez à n'inclure des éléments graphiques que pour les configurations compatibles. Vous pouvez importer des éléments vectoriels dans Android Studio sous File > New > Vector Asset (Fichier > Nouveau > Élément vectoriel). Dans l'assistant, sélectionnez Fichier local, saisissez un nom (par exemple, add_to_google_wallet_button) et localisez le fichier sur votre poste de travail.

1. Créez un fichier de mise en page : app/src/main/res/layout/add_to_google_wallet_button.xml
2. Ajoutez le contenu suivant au nouveau fichier de mise en page.

   <?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. Incluez la mise en page add_to_google_wallet_button.xml dans le fichier de mise en page de l'activité de paiement (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. Vérifier si l'API Google Wallet est disponible

Si un utilisateur ouvre votre application sur un appareil qui n'est pas compatible avec l'API Google Wallet, il peut avoir une mauvaise expérience lorsqu'il essaie d'ajouter la carte. Si l'appareil de l'utilisateur n'est pas compatible avec l'API Google Wallet, masquez le bouton Ajouter à Google Wallet pour éviter toute confusion. Plusieurs raisons peuvent expliquer que l'API ne soit pas disponible : la version d'Android ou des services Google Play est obsolète par exemple, ou Google Wallet est indisponible dans le pays de l'utilisateur.

Dans cette étape, vous allez ajouter à votre application une logique qui vérifie si l'API Google Wallet est disponible sur l'appareil. Le cas échéant, le bouton s'affichera dans l'activité. Sinon, le bouton sera masqué.

Si vous utilisez d'autres modèles de conception, pensez à intégrer la logique métier spécifique à votre domaine de manière appropriée. Par exemple, si vous utilisez le modèle MVVM (Model-View-ViewModel), placez la logique métier associée à l'UI dans votre activité ou fragment (par exemple, éléments d'UI et résultats d'activité) et la logique opérationnelle dans votre ViewModel (par exemple, instanciation du client et déclencheurs d'appel réseau).

1. Ouvrez le fichier CheckoutActivity.kt dans le répertoire app/src/main/java/com/google/android/gms/samples/wallet/activity/.
2. Créez une propriété de classe pour l'instance PayClient.

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

3. Instanciez la propriété PayClient dans la méthode onCreate.

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

4. Créez une méthode qui vérifie si le SDK et l'API Google Wallet sont disponibles sur l'appareil, et gérez le résultat.

   // 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. Appelez la méthode fetchCanUseGoogleWalletApi dans la méthode onCreate pour vérifier si l'API Google Wallet est disponible.

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

Lorsque vous exécutez l'application, vous devriez à présent voir le bouton Ajouter à Google Wallet dans l'UI.

Si le bouton Ajouter à Google Wallet ne s'affiche pas, consultez l'erreur renvoyée par la méthode getPayApiAvailabilityStatus et les journaux pour en savoir plus. L'utilisateur en question pourra peut-être utiliser l'API à l'avenir.

7. Créer un objet Carte générique

Si votre compte d'émetteur est en mode démo, vous ne pourrez émettre des cartes que pour vos utilisateurs de test. Si vous exécutez l'application avec une autre adresse e-mail, vous ne pourrez pas ajouter la carte à votre portefeuille.

Maintenant que vous avez vérifié que l'API Google Wallet est disponible, vous pouvez créer une carte et inviter votre utilisateur à l'ajouter à son portefeuille. Il existe deux flux pour créer des objets de pass pour les utilisateurs.

Créer l'objet Pass sur le serveur de backend

Dans cette approche, l'objet pass est créé sur un serveur backend et renvoyé à l'application cliente sous la forme d'un JWT signé. Cette approche est idéale lorsque l'adoption par les utilisateurs est élevée, car elle garantit que l'objet existe avant que l'utilisateur tente de l'ajouter à son portefeuille.

Créer l'objet carte lorsque l'utilisateur l'ajoute à son portefeuille

Dans cette approche, l'objet de carte est défini et encodé dans un jeton JWT signé sur le serveur backend. Un bouton Ajouter à Google Wallet est ensuite affiché dans l'application cliente qui fait référence au JWT. Lorsque l'utilisateur sélectionne le bouton, le jeton JWT est utilisé pour créer l'objet de carte. Cette option est idéale lorsque l'adoption par les utilisateurs est variable ou inconnue, car elle empêche la création d'objets Pass qui ne sont pas utilisés. Cette approche sera utilisée dans l'atelier de programmation.

1. Ouvrez le fichier backend/generic_pass.js.
2. Remplacez la valeur de issuerId par votre ID d'émetteur dans la Google Pay & Wallet Console.

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

3. Dans votre terminal ou votre invite de ligne de commande, exécutez le fichier generic_pass.js.

   node generic_pass.js
   

4. Copiez le jeton de sortie dans votre presse-papiers ou un éditeur de texte.

Lorsque votre code s'exécute, il définit un nouvel objet de pass et l'intègre dans un jeton JWT. Le jeton JWT est ensuite signé par la clé de compte de service que vous avez créée précédemment. Cela authentifie la requête auprès de l'API Google Wallet afin que les identifiants n'aient pas besoin d'être stockés dans l'application cliente.

aside Dans un environnement de production, votre système backend est responsable de la création des jetons JWT et de leur renvoi aux clients. Dans cet atelier de programmation, le script generic_pass.js émule ce comportement et "renvoie" un jeton que vous pouvez utiliser dans l'application cliente.

8. Ajouter la carte à Google Wallet

Maintenant que vous avez vérifié que l'API Google Wallet est disponible et que vous avez créé un jeton JWT signé, vous pouvez inviter l'utilisateur à ajouter la carte à son portefeuille. Dans cette étape, vous allez ajouter un écouteur au bouton Ajouter à Google Wallet qui utilise l'API Google Wallet pour enregistrer la carte dans le portefeuille de l'utilisateur.

1. Ouvrez le fichier app/src/main/CheckoutActivity.kt.
2. Remplacez la valeur de token par le jeton JWT que vous avez créé précédemment.

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

3. Créer une propriété de classe pour stocker le code de requête

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

4. Définissez un écouteur pour le bouton Ajouter à 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)
   }
   

Lorsqu'un utilisateur sélectionne le bouton Ajouter à Google Wallet, la méthode walletClient.savePassesJwt est appelée. Cette méthode invite l'utilisateur à ajouter le nouvel objet "carte" à son compte Google Wallet.

9. Gérer le résultat savePassesJwt

Dans la dernière étape de cet atelier de programmation, vous allez configurer votre application pour qu'elle gère le résultat de l'opération walletClient.savePassesJwt.

1. Ouvrez le fichier app/src/main/CheckoutActivity.kt.
2. Forcez le code suivant à la place de la méthode onActivityResult :

   // 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
         }
       }
     }
   }
   

Votre application peut désormais gérer les scénarios suivants :

• Carte ajoutée
• Résiliation par l'utilisateur
• Erreurs inattendues

Exécutez votre application pour vérifier que vous pouvez ajouter la carte et gérer le résultat comme prévu.

10. Félicitations

Félicitations, vous avez intégré l'API Google Wallet sur Android !

En savoir plus

Consultez l'intégration complète dans le dépôt GitHub google-pay/wallet-android-codelab.

Créer des cartes et demander un accès en production

Lorsque vous êtes prêt à émettre vos propres cartes en production, accédez à la Console Google Pay et Wallet pour demander l'accès à la production et autoriser votre application Android.

Pour en savoir plus, consultez les conditions préalables du SDK Android.