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 grâce à différents types de cartes: cartes de fidélité, offres, cartes cadeaux, billets pour des événements, titres de transport, cartes d'embarquement, etc. Chaque type de carte, ou classe de carte, est associé à des champs et à des fonctionnalités spécifiques au cas d'utilisation pour améliorer l'expérience utilisateur.

Toutefois, elles ne conviennent pas à tous les cas d'utilisation. Pour créer une expérience plus personnalisée, vous pouvez utiliser le type de carte 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 destinée aux développeurs Google Wallet.

Toutes les classes et tous les objets de carte doivent respecter la Politique 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 d'un objet de carte individuel. Il contient des informations communes à tous les objets de carte qui appartiennent à cette classe.
Objet de carte	Instance d'une classe de carte propre à 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 carte
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 pourrez:

• 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 à titre de référence.

2. Configuration

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

Vous pouvez créer des classes et des objets de carte dans des clients publics tels que des applications mobiles. Toutefois, il est plus sécurisé de créer des cartes sur un client privé tel qu'un serveur backend ou en les extrayant de vos applications clientes via des requêtes authentifiées et sécurisées.

Demander 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 Console Google Pay et Wallet. Au départ, vous pourrez créer des cartes en mode démo. Cela signifie que seuls des utilisateurs tests spécifiques pourront ajouter les cartes que vous créez. Les utilisateurs tests peuvent être gérés dans la Google Pay & Wallet Console.

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

1. Ouvrez la Console Google Pay et Wallet.
2. Suivez les instructions à l'écran pour créer un compte d'émetteur.
3. Sélectionnez API Google Wallet.
4. Confirmer que vous comprenez les conditions d'utilisation et les règles de confidentialité
5. Copiez la valeur ID de l'émetteur dans un éditeur de texte ou ailleurs.
6. Dans l'onglet Gérer, sélectionnez Configurer des comptes de test.
7. Ajoutez toutes 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é de compte de service contient une clé privée qui identifie votre application comme étant le compte de service. Cette clé est sensible et doit rester confidentielle.

Faites preuve de prudence 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 nécessaires.

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 KEYS.
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 de l'emplacement.

Définir la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS

Les SDK Google utilisent la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS 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 ouverte).

   echo $GOOGLE_APPLICATION_CREDENTIALS
   

Autoriser le compte de service

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

1. Ouvrez la Console Google Pay et Wallet.
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 de 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 lors de cet atelier de programmation utilise la flexibilité des cartes génériques pour créer un objet qui sert à la fois de badge d'identité et de suivi des points de défi. Lorsqu'un objet de carte est créé à partir de cette classe, il se présente comme illustré dans le graphique suivant.

Ce graphique illustre un petit sous-ensemble de propriétés pouvant être définies sur une carte. Consultez le modèle de carte générique pour découvrir l'impact des différentes propriétés de carte sur l'expérience utilisateur.

Vous pouvez créer des classes de cartes 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 cartes.

1. Cloner le dépôt GitHub google-pay/wallet-android-codelab sur votre station de travail locale

   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 console Google Pay et Wallet.

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

7. Dans le terminal ou l'invite de ligne 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 carte et affiche l'ID de classe. L'ID de classe se compose 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 ressemble à 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. Dans 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électionner 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. Ajouter 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"

À 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 le bouton à votre propre application, consultez les Consignes relatives à la marque pour télécharger les fichiers SVG du bouton dans la ou les langues qui vous conviennent. Veillez à n'inclure que des graphiques pour les configurations compatibles. Vous pouvez importer des éléments vectoriels dans Android Studio sous File > New > Vector Asset (Fichier > Nouveau > Élément vectoriel). Sélectionnez Fichier local dans l'assistant, saisissez un nom (par exemple, add_to_google_wallet_button) et recherchez 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 risque de vivre une expérience négative lorsqu'il tente d'ajouter la carte. Si l'appareil de l'utilisateur n'est pas compatible avec l'API Google Wallet, masquer le bouton Ajouter à Google Wallet évite toute confusion potentielle. L'API peut être indisponible pour diverses raisons, par exemple si la version d'Android ou des services Google Play est obsolète, ou si Google Wallet n'est pas disponible dans le pays de l'utilisateur.

À cette étape, vous allez ajouter une logique à votre application qui vérifie si l'API Google Wallet est disponible sur l'appareil. Si tel est le cas, le bouton s'affiche 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 Model-View-ViewModel (MVVM), placez la logique métier liée à l'UI dans votre activité ou votre 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éer 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, puis 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. Appeler 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, le bouton Ajouter à Google Wallet doit s'afficher dans l'interface utilisateur.

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 de carte générique

Si votre compte d'émetteur est en mode démo, vous ne pourrez émettre des cartes que pour vos utilisateurs tests. 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 carte pour les utilisateurs.

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

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

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

Dans cette approche, l'objet de la 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 jeton JWT. Lorsque l'utilisateur sélectionne le bouton, le jeton JWT est utilisé pour créer l'objet carte. Cette option est particulièrement adaptée aux cas où l'adoption par les utilisateurs est variable ou inconnue, car elle évite la création d'objets de carte 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 console Google Pay et Wallet.

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

3. Dans votre terminal ou à l'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 dans un éditeur de texte.

Lorsque votre code s'exécute, il définit un nouvel objet de carte et l'intègre dans un JWT. Le jeton JWT est ensuite signé par la clé de compte de service que vous avez créée précédemment. Cela permet d'authentifier 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 chargé de créer des jetons JWT et de les renvoyer aux clients. Dans cet atelier de programmation, le script generic_pass.js émule ce comportement et "renvoie" un jeton à 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. À 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éfinir un écouteur pour le bouton Ajouter à 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)
   }
   

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 de carte à son compte Google Wallet.

9. Gérer le résultat de savePassesJwt

À l'étape finale 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:

• Ajout de la carte réussi
• Annulation 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 Google Pay and Wallet Console pour demander un accès en production et autoriser votre application Android.

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