Intégrer l'API Google Wallet pour numériser des cartes sur Android

1. Avant de commencer

L'API Google Wallet vous permet d'interagir avec les utilisateurs par le biais de différents types de "cartes" prédéfinies : cartes de fidélité, offres, cartes cadeaux, billets pour un événement, titres de transport et cartes d'embarquement. Toutes ces cartes sont associées à des champs et fonctionnalités spécifiques. Nous sommes conscients toutefois que ces catégories ne sont pas adaptées à tous les cas d'utilisation. C'est pourquoi nous avons créé un type de carte générique. Comme son nom l'indique, le type générique doit être utilisé lorsque les autres catégories ne conviennent pas à votre cas. Voici quelques exemples d'utilisation du type de carte générique :

• Tickets de stationnement
• Cartes de bibliothèque
• Coupons
• Abonnements de gym
• Cartes d'assurance
• Réservations diverses

Vous pouvez utiliser cette catégorie générique pour tous les documents pouvant se présenter sous la forme d'une carte contenant jusqu'à trois lignes de texte, un code-barres (facultatif) et une section d'informations (également facultative), tant que cela reste conforme à notre Politique d'utilisation autorisée.

Avec l'API Google Wallet, vous pouvez créer ce qui suit :

• Des classes "carte". Les classes font office de modèles. Elles contiennent des informations communes qui figurent sur l'ensemble des cartes d'un programme ou d'un événement. Tous les objets "carte" appartiennent à une classe.
• Les objets "carte" ont un rôle bien précis qui dépend de l'activité de votre entreprise et de vos utilisateurs (par exemple, ticket de stationnement, abonnement de gym, etc.). Chacun de ces objets est associé à une classe précédemment définie et hérite des propriétés communes de celle-ci.

Dans cet atelier de programmation, vous utiliserez une classe prédéfinie et vous créerez peu à peu le fichier JSON d'un objet "carte". Vous ajouterez également un bouton "Ajouter à Google Wallet" à votre application Android. Les utilisateurs pourront ainsi enregistrer leur carte dans Google Wallet.

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

Prérequis

• Avoir un ordinateur équipé d'Android Studio
• Savoir créer et exécuter un projet dans Android Studio
• Avoir installé Git

Ce que vous allez apprendre

• Comment ajouter le SDK Google Wallet à votre application Android
• Comment vérifier si l'API Wallet est disponible
• Comment implémenter une UI permettant à l'utilisateur d'ajouter une carte à son compte Google Wallet

2. Configuration

Créer un compte d'émetteur temporaire

Pour créer des cartes pour votre utilisateur, vous devez d'abord créer un compte d'émetteur, activer l'API Wallet, puis créer une classe. Vous pouvez faire tout cela via la Business Console de Google Pay. Cependant, l'accès à cette console ne peut être accordé qu'une fois le processus d'approbation terminé. Nous allons donc créer un compte d'émetteur temporaire et une classe "carte" pour les besoins de cet atelier de programmation.

Veillez à créer le compte de test à l'aide d'une adresse e-mail que vous pourrez utiliser sur l'appareil mobile via lequel vous prévoyez de tester l'intégration.

1. Cliquez sur Créer un compte d'émetteur temporaire et un exemple de classe.

Remarque : N'utilisez pas ce compte ni cette classe à des fins de production. L'accès aux comptes temporaires est limité à sept jours.

2. Notez l'ID de l'émetteur et l'ID de la classe. Vous en aurez besoin aux prochaines étapes.

Cloner le dépôt Git

Clonez le dépôt Git qui contient le projet Android que vous allez modifier, à l'aide de la commande suivante :

git clone -b wallet-lab [e-mail]:google-pay/android-quickstart.git

Ouvrir dans Android Studio

Ouvrez Android Studio, cliquez sur "Ouvrir" sur l'écran d'accueil, puis sélectionnez le dossier kotlin dans le dépôt cloné pour l'ouvrir en tant que projet.

3. Ajouter le SDK Google Wallet à votre application

Le projet Android contient une activité vide que nous allons bientôt modifier, mais nous allons d'abord ajouter le SDK Google Wallet en tant que dépendance. Dans Android Studio, sélectionnez le script "build.gradle" au niveau du module, puis ajoutez les lignes suivantes à la section dependencies :

dependencies {
    ...
    implementation 'com.google.android.gms:play-services-pay:16.0.3'
}

Cliquez ensuite sur le bouton Gradle "Synchroniser le projet" en haut à droite d'Android Studio.

4. Ajouter un bouton "Ajouter à Google Wallet"

Vous allez maintenant ajouter un bouton "Ajouter à Google Wallet". Les éléments du bouton ont déjà été ajoutés au projet, il vous suffit de les ajouter à votre fichier de mise en page. Pour cela, nous vous recommandons de créer une mise en page distincte avec ce bouton :

add_to_google_wallet_button.xml

<?xml version="1.0" encoding="utf-8"?>
<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:clickable="true"
    android:focusable="true"
    android:layout_width="match_parent"
    android:layout_height="48sp"
    android:background="@drawable/add_to_google_wallet_button_background_shape"
    android:contentDescription="@string/add_to_google_wallet_button_content_description">
    <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>

Le bouton doit se présenter comme suit :

Si vous ajoutez ce bouton à votre propre application, consultez la page dédiée aux consignes concernant les boutons et téléchargez les fichiers SVG du bouton avec les thèmes de couleur et 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". Attribuez-lui un nom (par exemple, add_to_google_wallet_button) et localisez le fichier à importer sur votre disque local.

Vous devez ensuite l'inclure dans votre fichier de mise en page :

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

5. Vérifier si l'API est disponible

Passons maintenant au codage. Ouvrez le fichier où vous allez appeler l'API Google Wallet dans Android Studio (le fichier CheckoutActivity.kt si vous utilisez l'exemple d'application), puis instanciez un objet PayClient en tant que membre de votre classe. Cet objet vous permet d'appeler l'API Google Wallet. La méthode getClient reçoit le contexte de la classe d'instanciation (dans ce cas, l'activité d'appel).

private lateinit var walletClient: PayClient

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    walletClient = Pay.getClient(this)
    ...
}

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, placez la logique métier associée à l'UI dans votre activité ou fragment (par exemple, éléments d'UI, résultat d'activité) et la logique opérationnelle dans votre modèle de visualisation (par exemple, instanciation du client, déclencheurs d'appel réseau).

Assurez-vous ensuite que l'application et le SDK Google Wallet sont disponibles sur l'appareil. Créez une méthode dans votre classe (par exemple, fetchCanUseGoogleWalletApi) pour déterminer si l'API Google Wallet est disponible, puis une autre pour réagir au résultat en affichant un bouton "Ajouter à Google Wallet" si l'API est disponible :

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

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 actuellement indisponible dans le pays de l'utilisateur.

Enfin, appelez la méthode fetchCanUseGoogleWalletApi dans la méthode onCreate pour déterminer si l'API Google Wallet est disponible :

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    ...
    fetchCanUseGoogleWalletApi()
}

Vous devriez à présent voir le bouton "Ajouter à Google Wallet" dans l'interface utilisateur lorsque vous exécutez l'application :

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. Si l'API n'est pas disponible, n'affichez pas le bouton "Ajouter à Google Wallet" et utilisez plutôt une autre méthode pour ajouter une carte (par exemple, un lien JWT). Notez que l'utilisateur en question pourra peut-être utiliser l'API à l'avenir.

6. Ajouter une carte à Google Wallet

Maintenant que vous avez vérifié que l'API Google Wallet est disponible, vous pouvez inviter vos utilisateurs à ajouter des cartes à leur compte Google Wallet. Avant de commencer, prenez le temps de passer en revue la carte créée dans cet atelier :

Cette mise en page utilise la flexibilité des cartes génériques pour créer un objet fonctionnant comme un badge d'identité et qui permet l'ajout d'un défi qui invite les participants à collecter des points au cours de l'événement. Voici à quoi ressemble l'objet générique :

{
    "id": "999999.d1fa-4cca1...",
    "classId": "999999.a92b-129f...",
    "genericType": "GENERIC_TYPE_UNSPECIFIED",
    "hexBackgroundColor": "#4285f4",
    "logo": { ... },
    "cardTitle": { ... },
    "subheader": { ... },
    "header": { ... },
    "barcode": { ... },
    "heroImage": { ... },
    "textModulesData": []
}

Pour insérer l'objet, l'API attend un corps JWT non signé encapsulant le ou les nouveaux éléments :

{
    "iss": <owner-email-address>,
    "aud": "google",
    "typ": "savetowallet",
    "iat": <unix-time>,
    "origins": [],
    "payload": {
        "genericObjects": [],
        "genericClasses": [],
        ...
    }
}

Assemblez le tout (en utilisant les valeurs obtenues précédemment lorsque vous avez créé un compte d'émetteur temporaire) et affectez l'objet obtenu à une variable de votre classe :

private val issuerEmail = "<insert-your-issuer-email-address>"
private val issuerId = "<insert-your-issuer-id>"
private val passClass = "<insert-your-class-id>"
private val passId = UUID.randomUUID().toString()

private val newObjectJson = """
    {
      "iss": "$issuerEmail",
      "aud": "google",
      "typ": "savetowallet",
      "iat": ${Date().time / 1000L},
      "origins": [],
      "payload": {
        "genericObjects": [
          {
            "id": "$issuerId.$passId",
            "classId": "$passClass",
            "genericType": "GENERIC_TYPE_UNSPECIFIED",
            "hexBackgroundColor": "#4285f4",
            "logo": {
              "sourceUri": {
                "uri": "https://storage.googleapis.com/wallet-lab-tools-codelab-artifacts-public/pass_google_logo.jpg"
              }
            },
            "cardTitle": {
              "defaultValue": {
                "language": "en",
                "value": "Google I/O '22  [DEMO ONLY]"
              }
            },
            "subheader": {
              "defaultValue": {
                "language": "en",
                "value": "Attendee"
              }
            },
            "header": {
              "defaultValue": {
                "language": "en",
                "value": "Alex McJacobs"
              }
            },
            "barcode": {
              "type": "QR_CODE",
              "value": "$passId"
            },
            "heroImage": {
              "sourceUri": {
                "uri": "https://storage.googleapis.com/wallet-lab-tools-codelab-artifacts-public/google-io-hero-demo-only.jpg"
              }
            },
            "textModulesData": [
              {
                "header": "POINTS",
                "body": "${Random.nextInt(0, 9999)}",
                "id": "points"
              },
              {
                "header": "CONTACTS",
                "body": "${Random.nextInt(1, 99)}",
                "id": "contacts"
              }
            ]
          }
        ]
      }
    }
    """

Si vous consultez la définition de classe, vous constaterez que les informations sous textModulesData sont référencées dans la classe, ce qui, selon le modèle de classe, permet de définir la manière dont ces champs sont affichés sur la carte finale.

Il s'agit d'un objet de test créé à des fins pédagogiques. Ne créez pas vos propres cartes à partir d'un client public (applications mobiles, par exemple). Générez plutôt vos cartes et insérez-les à partir d'un client confidentiel (par exemple, un serveur backend) ou récupérez-les à partir de vos applications clientes via des requêtes authentifiées et sécurisées.

Enfin, revenez à la méthode onCreate et ajoutez un gestionnaire de clics à votre bouton "Ajouter à Google Wallet" pour lancer l'opération à l'aide de la méthode savePasses dans le client :

private val addToGoogleWalletRequestCode = 1000

private lateinit var layout: ActivityCheckoutBinding
private lateinit var addToGoogleWalletButton: View

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    // Use view binding to access the UI elements
    layout = ActivityCheckoutBinding.inflate(layoutInflater)
    setContentView(layout.root)

    addToGoogleWalletButton = layout.addToGoogleWalletButton.root
    addToGoogleWalletButton.setOnClickListener {
        walletClient.savePasses(newObjectJson, this, addToGoogleWalletRequestCode)
    }

    ...
}

Vous avez défini le fichier JSON du nouvel objet en utilisant l'ID d'émetteur et l'ID de classe créés précédemment. Lorsque l'utilisateur clique sur le bouton "Ajouter à Google Wallet", cela appelle payClient.savePasses, et on demande à l'utilisateur d'ajouter le nouvel objet "carte" à son compte Google Wallet :

7. Gérer le résultat

Vous avez presque terminé. Pour finir, gérez le résultat de l'opération, qu'elle aboutisse ou non. Forcez le code suivant à la place de la méthode onActivityResult :

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

            else -> {
                // Handle unexpected (non-API) exception
            }
        }
    }
}

Ce code vous permet de gérer les situations où la carte est bien ajoutée, où l'utilisateur annule l'action ainsi que les éventuelles erreurs susceptibles de se produire. Exécutez à nouveau votre application pour vérifier que vous pouvez ajouter la carte et gérer le résultat comme prévu.

8. Félicitations

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

En savoir plus

Consultez un exemple d'intégration complète dans l'exemple d'application dans GitHub.

Demander un compte d'émetteur

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