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 pass ou classe de pass est fourni avec des champs et des fonctionnalités spécifiques à un cas d'utilisation pour améliorer l'expérience utilisateur.

Toutefois, ces catégories ne sont pas adaptées à tous les cas d'utilisation. Pour créer une expérience plus personnalisée, vous pouvez utiliser le type de pass 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"

Exemple de pass Google Wallet pour une 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 Carte appartenant à cette classe.

Objet de carte

Instance d'une classe de pass unique à 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 Pass
  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

À la fin de cet atelier de programmation, vous saurez :

  • Créer des objets pass à 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 pour vous aider.

2. Configuration

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

S'inscrire pour obtenir 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 certains utilisateurs de test pourront ajouter les cartes que vous créez. Vous pouvez gérer les utilisateurs de test dans la Google Pay & Wallet Console.

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

  1. Ouvrez la Google Pay & Wallet Console.
  2. Suivez les instructions à l'écran pour créer un compte é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 de l'émetteur dans un éditeur de texte ou à un autre emplacement.
  6. Dans 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 et doit rester 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. N'oubliez pas où il se trouve.

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 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 d'ouverte.
    echo $GOOGLE_APPLICATION_CREDENTIALS

Autoriser le compte de service

Enfin, vous devrez autoriser le compte de service à gérer les pass 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. Sélectionnez Développeur ou Administrateur dans le menu déroulant Niveau d'accès.
  6. Sélectionnez Inviter.

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

Durée : 10:00

Dans 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 de backend utilisé pour provisionner des classes et des objets de pass. Vous allez les modifier pour inclure un bouton Ajouter à Google Wallet sur l'écran d'informations détaillées sur le produit.

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

  1. Ouvrez le dépôt cloné dans votre terminal ou votre invite de ligne 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. Installer les dépendances Node.js
    npm install .
  4. Démarrer 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 un pass, il ne se passera rien. Dans les étapes suivantes, vous allez configurer l'application pour créer une classe et un objet de pass.

4. Créer une classe de carte générique

Dans cette étape, vous allez créer la classe de base pour 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 au cours de cet atelier de programmation utilise la flexibilité des cartes génériques pour créer un objet fonctionnant à la fois comme un badge d'identité et comme un outil de suivi des points de défi. Lorsqu'un objet de carte est créé à partir de cette classe, il ressemble à l'illustration suivante.

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

  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. Localiser 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 pass.
    // 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 pass et affiche l'ID de la classe. L'ID de 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 classe ressemblerait à 1234123412341234123.codelab_class). Les journaux de sortie incluront également la réponse de l'API Google Wallet.

5. Créer un objet Carte générique

Dans 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 pass pour les utilisateurs.

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

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

Créer l'objet 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 fait référence au JWT. Lorsque l'utilisateur sélectionne le bouton, le jeton JWT est utilisé pour créer l'objet de carte. Cette option est idéale lorsque l'adoption par les utilisateurs est variable ou inconnue, car elle empêche la création d'objets Pass qui ne sont pas utilisés. Cette approche sera utilisée dans l'atelier de programmation.

  1. Ouvrez le fichier web/app.js.
  2. Localiser la fonction createPassObject
  3. Dans la fonction, définissez un nouvel objet de pass 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 rechargez l'application, saisissez votre adresse e-mail et envoyez le formulaire, vous ne verrez aucun résultat. L'objet pass 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 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 et 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. Actualisez l'application exécutée dans votre navigateur.
  3. Saisissez votre adresse e-mail dans le formulaire, puis sélectionnez Créer un pass.
  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 Console Google Pay et Wallet pour demander l'accès à la production.

Pour en savoir plus, consultez Conditions préalables de l'API Web.