Créer des cartes sur le Web à 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 carte, ou classe de carte, est associé à des champs et fonctionnalités spécifiques qui améliorent l'expérience utilisateur.

Toutefois, ces types de cartes 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 n'importe quel cas d'utilisation pouvant être présenté avec les éléments suivants :

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

Exemple de pass Google Wallet pour un événement de conférence

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 pour 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 unique pour un ID utilisateur.

À propos de 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 de carte
  5. Créer un bouton Ajouter à Google Wallet pour enregistrer une carte
  6. Afficher le bouton sur votre page Web
  7. Gérer le résultat de l'enregistrement de la carte

Prérequis

Objectifs

Après avoir effectué cet atelier de programmation, vous pourrez effectuer les opérations suivantes :

  • Créer des objets de carte à l'aide de Google Wallet
  • Créer un bouton Ajouter à Google Wallet

Assistance

Si vous êtes bloqué à 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

Lors de 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 qui pourront être ajoutés aux portefeuilles des utilisateurs. Ensuite, vous allez créer un projet et un compte de service Google Cloud. Ils serviront à créer par programmation 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.

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ébut, 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 prérequis pour les cartes génériques.

  1. Ouvrez la Google Pay & Wallet Console.
  2. Suivez les instructions à l'écran pour créer un compte d'é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 d'émetteur dans un éditeur de texte ou à un autre emplacement.
  6. Sous 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. Veillez donc à la garder confidentielle.

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. Veillez à 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.

  1. Suivez les instructions de la documentation 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 d'invite 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 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, test-svc@myproject.iam.gserviceaccount.com).
  5. Dans le menu déroulant Niveau d'accès , sélectionnez Développeur ou Administrateur.
  6. Sélectionnez Inviter.

3. Démarrer l'exemple d'application Node.js

Durée : 10:00

Lors de cette étape, vous allez exécuter un exemple d'application Node.js qui fait office 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 de détails du produit.

  1. Clonez 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

  1. Ouvrez le dépôt cloné dans votre terminal ou invite de commande.
  2. Accédez au répertoire web (il s'agit de l'application que vous allez modifier dans le reste de cet atelier de programmation).
    cd web
  3. Installez les dépendances Node.js.
    npm install .
  4. Démarrez l'application.
    node app.js
  5. Ouvrez l'application exécutée sur http://localhost:3000.

Exemple d'application Web avec un champ permettant de saisir une adresse e-mail et un bouton "Créer un pass"

Si vous saisissez votre adresse e-mail et sélectionnez Créer une carte, rien ne se passera. Lors des é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

Lors de cette étape, vous allez créer la classe de base pour votre carte. Chaque fois qu'une nouvelle 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 comme un outil de suivi des points de défi. Lorsqu'un objet de pass est créé à partir de cette classe, il ressemble à l'image suivante.

Les classes de carte 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 carte.

  1. Ouvrez le fichier web/app.js.
  2. Remplacez la valeur de issuerId par votre ID d'émetteur dans la Google Pay &Wallet Console.
    // TODO: Define Issuer ID
const issuerId = 'ISSUER_ID';
  3. Recherchez la fonction createPassClass.
  4. 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://codelabs.developers.google.com/static/add-to-wallet-web/images/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 nouvelle classe de pass et génère l'ID de la classe. L'ID de la 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 la classe ressemble à 1234123412341234123.codelab_class). Les journaux de sortie incluent également la réponse de l'API Google Wallet.

5. Créer un objet de carte générique

Lors de 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 carte est créé sur un serveur backend et renvoyé à l'application cliente sous la forme d'un jeton JWT signé. Cette approche est plus adaptée aux cas où 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 de 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 référence le jeton JWT. Lorsque l'utilisateur sélectionne le bouton, le jeton JWT est utilisé pour créer l'objet de carte. Cette approche est plus adaptée aux cas où l'adoption par les utilisateurs est variable ou inconnue, car elle empêche 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 web/app.js.
  2. Recherchez la fonction createPassObject.
  3. Dans la fonction, définissez un 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://developers.google.com/static/wallet/site-assets/images/pass-builder/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://developers.google.com/static/wallet/site-assets/images/pass-builder/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, vous ne verrez aucun résultat. L'objet de carte est défini par l'application backend, mais aucune sortie n'est renvoyée. Ensuite, vous allez 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 qui pourra être utilisé dans le bouton Ajouter à Google Wallet. Lorsque l'utilisateur sélectionne le bouton, il est invité à enregistrer la carte dans son portefeuille.

  1. 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>`);
  2. Rechargez l'application exécutée dans votre navigateur.
  3. Saisissez votre adresse e-mail dans le formulaire, puis sélectionnez Créer une carte.
  4. Lorsqu'il s'affiche, sélectionnez le bouton Ajouter à Google Wallet.

Le bouton &quot;Ajouter à Google Wallet&quot; s&#39;affiche correctement dans l&#39;interface utilisateur de l&#39;application.

7. Félicitations

Exemple d&#39;objet de carte générique

Félicitations ! Vous avez intégré l'API Google Wallet sur le Web.

En savoir plus

Consultez un exemple d'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 Google Pay & Wallet Console pour demander un accès en production.

Pour en savoir plus, consultez les prérequis pour l'API Web.