À propos de cet atelier de programmation
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 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 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),
- 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 page Web, consultez la documentation pour les développeurs Google Wallet.
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 appartenant à 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 :
- Créer un compte d'émetteur en mode démo
- Créer un compte de service pour l'émission de cartes
- Créer une classe de carte générique
- Créer un objet carte
- Créer un bouton Ajouter à Google Wallet pour enregistrer une carte
- Afficher le bouton sur votre page Web
- Gérer le résultat de l'enregistrement de la carte
Prérequis
- 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:
- Créer des objets de carte à l'aide de Google Wallet
- 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-web-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 des classes et des objets de carte de manière programmatique, 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.
Ouvrir un compte d'émetteur 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é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.
- Ouvrez la Google Pay & Wallet Console.
- Suivez les instructions à l'écran pour créer un compte d'émetteur.
- Sélectionnez API Google Wallet.
- Confirmer que vous comprenez les conditions d'utilisation et les règles de confidentialité
- Copiez la valeur de l'ID de l'émetteur dans un éditeur de texte ou ailleurs.
- Dans l'onglet Gérer, sélectionnez Configurer des comptes de test.
- Ajoutez toutes les adresses e-mail que vous utiliserez dans cet atelier de programmation.
Activer l'API Google Wallet
- Connectez-vous à la console Google Cloud.
- 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).
- 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.
Créer un compte de service
- Dans la console Google Cloud, ouvrez Comptes de service.
- Saisissez un nom, un ID et une description pour votre compte de service.
- Sélectionnez CRÉER ET CONTINUER.
- Sélectionnez OK.
Créer une clé de compte de service
- Sélectionnez votre compte de service.
- Sélectionnez le menu KEYS (CLÉS).
- Sélectionnez AJOUTER UNE CLÉ, puis Créer une clé.
- Sélectionnez le type de clé JSON.
- Sélectionnez CRÉER.
Vous serez invité à enregistrer le fichier de clé sur votre poste de travail local. N'oubliez pas de vous souvenir de son emplacement.
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.
- 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. - 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.
- Ouvrez la Google Pay & Wallet Console.
- Sélectionnez Utilisateurs.
- Sélectionnez Inviter un utilisateur.
- Saisissez l'adresse e-mail du compte de service (par exemple,
test-svc@myproject.iam.gserviceaccount.com). - Sélectionnez Développeur ou Administrateur dans le menu déroulant Niveau d'accès.
- Sélectionnez Inviter.
3. Démarrer l'exemple d'application Node.js
Durée : 10:00
À cette étape, vous allez exécuter un exemple d'application Node.js qui sert de site Web d'achat et de serveur backend.
Cloner l'exemple de dépôt
Le dépôt google-pay/wallet-web-codelab contient un exemple de projet basé sur Node.js et différents fichiers de script qui imitent un serveur backend utilisé pour provisionner des classes et des objets de carte. Vous allez les modifier pour inclure un bouton Ajouter à Google Wallet sur un écran d'informations produit.
- Cloner le dépôt sur votre poste de travail local
git clone https://github.com/google-pay/wallet-web-codelab.git
Installer les dépendances du projet
- Ouvrez le dépôt cloné dans votre terminal ou votre invite de ligne de commande.
- Accédez au répertoire
web(c'est l'application que vous allez modifier dans la suite de cet atelier de programmation).cd web - Installer les dépendances Node.js
npm install . - Démarrer l'application
node app.js - Ouvrez l'application exécutée sur http://localhost:3000.
Si vous saisissez votre adresse e-mail et sélectionnez Créer une carte, rien ne se passe. Dans les étapes suivantes, vous allez configurer l'application pour créer une classe et un objet de carte.
4. 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 fonctionne à la fois comme un badge d'identité et un outil 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.
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.
- Ouvrez le fichier
web/app.js. - Remplacez la valeur de
issuerIdpar votre ID d'émetteur dans la Google Pay & Wallet Console.// TODO: Define Issuer ID
const issuerId = 'ISSUER_ID'; - Localiser la fonction
createPassClass - Dans la fonction, créez un client HTTP authentifié et utilisez l'API Google Wallet pour créer une classe de carte.
// TODO: Create a Generic pass class
let genericClass = {
'id': `${classId}`,
'classTemplateInfo': {
'cardTemplateOverride': {
'cardRowTemplateInfos': [
{
'twoItems': {
'startItem': {
'firstValue': {
'fields': [
{
'fieldPath': 'object.textModulesData["points"]'
}
]
}
},
'endItem': {
'firstValue': {
'fields': [
{
'fieldPath': 'object.textModulesData["contacts"]'
}
]
}
}
}
}
]
},
'detailsTemplateOverride': {
'detailsItemInfos': [
{
'item': {
'firstValue': {
'fields': [
{
'fieldPath': 'class.imageModulesData["event_banner"]'
}
]
}
}
},
{
'item': {
'firstValue': {
'fields': [
{
'fieldPath': 'class.textModulesData["game_overview"]'
}
]
}
}
},
{
'item': {
'firstValue': {
'fields': [
{
'fieldPath': 'class.linksModuleData.uris["official_site"]'
}
]
}
}
}
]
}
},
'imageModulesData': [
{
'mainImage': {
'sourceUri': {
'uri': 'https://storage.googleapis.com/wallet-lab-tools-codelab-artifacts-public/google-io-2021-card.png'
},
'contentDescription': {
'defaultValue': {
'language': 'en-US',
'value': 'Google I/O 2022 Banner'
}
}
},
'id': 'event_banner'
}
],
'textModulesData': [
{
'header': 'Gather points meeting new people at Google I/O',
'body': 'Join the game and accumulate points in this badge by meeting other attendees in the event.',
'id': 'game_overview'
}
],
'linksModuleData': {
'uris': [
{
'uri': 'https://io.google/2022/',
'description': 'Official I/O \'22 Site',
'id': 'official_site'
}
]
}
};
let response;
try {
// Check if the class exists already
response = await httpClient.request({
url: `${baseUrl}/genericClass/${classId}`,
method: 'GET'
});
console.log('Class already exists');
console.log(response);
} catch (err) {
if (err.response && err.response.status === 404) {
// Class does not exist
// Create it now
response = await httpClient.request({
url: `${baseUrl}/genericClass`,
method: 'POST',
data: genericClass
});
console.log('Class insert response');
console.log(response);
} else {
// Something else went wrong
console.log(err);
res.send('Something went wrong...check the console logs!');
}
}
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.
5. Créer un objet de carte générique
À cette étape, vous allez configurer votre application Node.js pour créer un objet de carte générique à l'aide de la classe que vous avez créée précédemment. 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 de la 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.
- Ouvrez le fichier
web/app.js. - Localiser la fonction
createPassObject - Dans la fonction, définissez un nouvel objet de carte pour votre utilisateur.
// TODO: Create a new Generic pass for the user
let objectSuffix = `${req.body.email.replace(/[^\w.-]/g, '_')}`;
let objectId = `${issuerId}.${objectSuffix}`;
let genericObject = {
'id': `${objectId}`,
'classId': classId,
'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'
}
},
'subheader': {
'defaultValue': {
'language': 'en',
'value': 'Attendee'
}
},
'header': {
'defaultValue': {
'language': 'en',
'value': 'Alex McJacobs'
}
},
'barcode': {
'type': 'QR_CODE',
'value': `${objectId}`
},
'heroImage': {
'sourceUri': {
'uri': 'https://storage.googleapis.com/wallet-lab-tools-codelab-artifacts-public/google-io-hero-demo-only.jpg'
}
},
'textModulesData': [
{
'header': 'POINTS',
'body': '1234',
'id': 'points'
},
{
'header': 'CONTACTS',
'body': '20',
'id': 'contacts'
}
]
};
// TODO: Create the signed JWT and link
res.send("Form submitted!");
Si vous actualisez l'application, saisissez votre adresse e-mail et envoyez le formulaire, aucune sortie ne s'affichera. L'objet carte est défini par l'application backend, mais aucune sortie n'est renvoyée. Vous allez ensuite transformer la carte en lien Ajouter à Google Wallet.
6. Créer un bouton "Ajouter à Google Wallet"
Pour la dernière étape, vous allez créer un jeton JWT signé et renvoyer un lien pouvant être utilisé dans le bouton Ajouter à Google Wallet. Lorsque l'utilisateur sélectionne le bouton, il est invité à enregistrer la carte dans son portefeuille.
- Créez les revendications JWT, encodez-les à l'aide de la clé privée du compte de service, puis renvoyez un bouton Ajouter à Google Wallet avec le lien intégré.
// TODO: Create the signed JWT and link
const claims = {
iss: credentials.client_email,
aud: 'google',
origins: [],
typ: 'savetowallet',
payload: {
genericObjects: [
genericObject
]
}
};
const token = jwt.sign(claims, credentials.private_key, { algorithm: 'RS256' });
const saveUrl = `https://pay.google.com/gp/v/save/${token}`;
res.send(`<a href='${saveUrl}'><img src='wallet-button.png'></a>`); - Actualisez l'application exécutée dans votre navigateur.
- Saisissez votre adresse e-mail dans le formulaire, puis sélectionnez Créer une carte.
- Lorsque celui-ci s'affiche, sélectionnez le bouton Ajouter à Google Wallet.
7. Félicitations
Félicitations, vous avez intégré l'API Google Wallet sur le Web !
En savoir plus
Consultez une intégration complète dans le dépôt GitHub google-pay/wallet-web-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 en production.
Pour en savoir plus, consultez la section Conditions préalables pour les API Web.