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.
- 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 git@github.com: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 :
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)
...
}
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
}
}
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 :
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"
}
]
}
]
}
}
"""
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.