Mit der Google Wallet API Karten/Tickets im Web erstellen

1. Einführung

Übersicht

Die Google Wallet API bietet Ihnen die Möglichkeit, mit Nutzern über verschiedene Arten von Karten/Tickets zu interagieren: Kundenkarten, Angebote, Geschenkkarten, Veranstaltungstickets, Fahrkarten, Bordkarten und mehr. Jeder Kartentyp oder jede Kartenklasse enthält anwendungsfallspezifische Felder und Funktionen, um die Nutzerfreundlichkeit zu verbessern.

Diese sind jedoch möglicherweise nicht für jeden Anwendungsfall geeignet. Wenn Sie eine individuellere Lösung erstellen möchten, können Sie den generischen Ausweistyp verwenden. Hier sind einige Beispiele für Anwendungsfälle für den generischen Kartentyp:

  • Parkscheine
  • Mitgliedskarten für eine Bibliothek
  • Gutscheine für gespeicherte Werte
  • Mitgliedskarten für Fitnessstudios
  • Reservierungen

Sie können generische Karten für jeden Anwendungsfall verwenden, der mit Folgendem dargestellt werden kann:

  • Bis zu drei Informationszeilen
  • Optional: Barcode-Grafik
  • Optional: Detailabschnitt

Beispiel für eine Google Wallet-Karte/ein Google Wallet-Ticket für eine Konferenz

Weitere Informationen zur Google Wallet API oder zum Hinzufügen der Schaltfläche Zu Google Wallet hinzufügen auf einer Webseite finden Sie in der Google Wallet-Entwicklerdokumentation.

Karten-/Ticketklassen und ‑objekte

Die Google Wallet API bietet Methoden zum Erstellen der folgenden Elemente:

Typ

Beschreibung

Karten-/Ticketklasse

Eine Vorlage für ein einzelnes Karten-/Ticketobjekt. Sie enthält Informationen, die für alle Kartenobjekte dieser Klasse gelten.

Karten-/Ticketobjekt

Eine Instanz einer Kartenklasse, die für eine Nutzer-ID eindeutig ist.

Informationen zu diesem Codelab

In diesem Codelab führen Sie die folgenden Aufgaben aus.

  1. Neues Ausstellerkonto im Demomodus erstellen
  2. Dienstkonto zum Ausstellen von Karten/Tickets erstellen
  3. Neue generische Karten-/Ticketklasse erstellen
  4. Neues Pass-Objekt erstellen
  5. Schaltfläche Zu Google Wallet hinzufügen zum Speichern einer Karte / eines Tickets erstellen
  6. Schaltfläche auf Ihrer Webseite anzeigen
  7. Ergebnis des Speicherns der Karte/des Tickets verarbeiten

Vorbereitung

Ziele

Nach Abschluss dieses Codelabs können Sie Folgendes:

  • Kartenobjekte mit Google Wallet erstellen
  • Schaltfläche Zu Google Wallet hinzufügen erstellen

Support

Wenn Sie an einer Stelle im Codelab nicht weiterkommen, finden Sie im GitHub-Repository google-pay/wallet-web-codelab eine vollständige Lösung als Referenz.

2. Einrichtung

In diesem Schritt erstellen Sie ein Ausstellerkonto im Demomodus. So können Sie Karten-/Ticketklassen und ‑objekte erstellen, die Nutzer ihren Wallets hinzufügen können. Als Nächstes erstellen Sie ein Google Cloud-Projekt und ein Dienstkonto. Sie werden verwendet, um Karten-/Ticketklassen und Objekte programmatisch auf dieselbe Weise wie ein Backend-Server zu erstellen. Zuletzt autorisieren Sie das Google Cloud-Dienstkonto, um Karten in Ihrem Google Wallet-Ausstellerkonto zu verwalten.

Für ein Google Wallet-Ausstellerkonto registrieren

Zum Erstellen und Verteilen von Karten/Tickets für Google Wallet ist ein Ausstellerkonto erforderlich. Sie können sich über die Google Pay & Wallet Console registrieren. Anfangs haben Sie Zugriff, um Karten im Demomodus zu erstellen. Das bedeutet, dass nur bestimmte Testnutzer die von Ihnen erstellten Karten/Tickets hinzufügen können. Testnutzer können in der Google Pay & Wallet Console verwaltet werden.

Weitere Informationen zum Demomodus finden Sie unter Allgemeine Voraussetzungen für Karten.

  1. Google Pay & Wallet Console öffnen
  2. Folgen Sie der Anleitung auf dem Bildschirm, um ein Ausstellerkonto zu erstellen.
  3. Wählen Sie die Google Wallet API aus.
  4. Bestätigen Sie, dass Sie die Nutzungsbedingungen und die Datenschutzerklärung verstanden haben.
  5. Kopieren Sie den Wert für Issuer ID in einen Texteditor oder an einen anderen Speicherort.
  6. Wählen Sie auf dem Tab Verwalten die Option Testkonten einrichten aus.
  7. Fügen Sie alle E‑Mail-Adressen hinzu, die Sie in diesem Codelab verwenden werden.

Google Wallet API aktivieren

  1. Melden Sie sich in der Google Cloud Console an.
  2. Wenn Sie noch kein Google Cloud-Projekt haben, erstellen Sie jetzt eines. Weitere Informationen finden Sie unter Projekte erstellen und verwalten.
  3. Aktivieren Sie die Google Wallet API (auch als Google Pay for Passes API bezeichnet) für Ihr Projekt.

Dienstkonto und Schlüssel erstellen

Zum Aufrufen der Google Wallet API sind ein Dienstkonto und ein Dienstkontoschlüssel erforderlich. Das Dienstkonto ist die Identität, die für den Aufruf der Google Wallet API verwendet wird. Der Dienstkontoschlüssel enthält einen privaten Schlüssel, über den Ihre Anwendung als Dienstkonto identifiziert wird. Dieser Schlüssel ist vertraulich und sollte geheim gehalten werden.

Dienstkonto erstellen

  1. Öffnen Sie in der Google Cloud Console Dienstkonten.
  2. Geben Sie einen Namen, eine ID und eine Beschreibung für das Dienstkonto ein.
  3. Wählen Sie ERSTELLEN UND FORTFAHREN aus.
  4. Wähle FERTIG aus.

Dienstkontoschlüssel erstellen

  1. Dienstkonto auswählen
  2. Wählen Sie das Menü SCHLÜSSEL aus.
  3. Wählen Sie SCHLÜSSEL HINZUFÜGEN und dann Neuen Schlüssel erstellen aus.
  4. Wählen Sie den Schlüsseltyp JSON aus.
  5. Klicken Sie auf ERSTELLEN.

Sie werden aufgefordert, die Schlüsseldatei auf Ihrer lokalen Workstation zu speichern. Merken Sie sich den Speicherort.

Legen Sie die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS fest.

Die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS wird von Google-SDKs verwendet, um sich als Dienstkonto zu authentifizieren und auf verschiedene APIs für ein Google Cloud-Projekt zuzugreifen.

  1. Folgen Sie der Anleitung in der Dokumentation zu Dienstkontoschlüsseln für Google Cloud, um die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS festzulegen.
  2. Prüfen Sie, ob die Umgebungsvariable in einem neuen Terminal (MacOS/Linux) oder einer neuen Befehlszeilensitzung (Windows) festgelegt ist. Möglicherweise müssen Sie eine neue Sitzung starten, wenn Sie bereits eine geöffnet haben.
    echo $GOOGLE_APPLICATION_CREDENTIALS

Dienstkonto autorisieren

Schließlich müssen Sie das Dienstkonto autorisieren, Google Wallet-Karten zu verwalten.

  1. Google Pay & Wallet Console öffnen
  2. Wählen Sie Nutzer aus.
  3. Wählen Sie Nutzer einladen aus.
  4. Geben Sie die E‑Mail-Adresse des Dienstkontos ein (z. B. test-svc@myproject.iam.gserviceaccount.com).
  5. Wählen Sie im Drop-down-Menü Zugriffsebene entweder Entwickler oder Administrator aus.
  6. Wählen Sie Einladen aus.

3. Node.js-Beispielanwendung starten

Dauer: 10:00

In diesem Schritt führen Sie eine Beispiel-Node.js-Anwendung aus, die als Shopping-Website und Backend-Server fungiert.

Beispiel-Repository klonen

Das Repository google-pay/wallet-web-codelab enthält ein Node.js-basiertes Beispielprojekt und verschiedene Skriptdateien, die einen Back-End-Server imitieren, der zum Bereitstellen von Passklassen und ‑objekten verwendet wird. Sie bearbeiten diese, um auf einem Produktdetailbildschirm die Schaltfläche Zu Google Wallet hinzufügen einzufügen.

  1. Repository auf Ihre lokale Workstation klonen
    git clone https://github.com/google-pay/wallet-web-codelab.git

Projektabhängigkeiten installieren

  1. Geklontes Repository im Terminal oder in der Befehlszeile öffnen
  2. Wechseln Sie in das Verzeichnis web. Das ist die App, die Sie im weiteren Verlauf dieses Codelabs ändern werden.
    cd web
  3. Node.js-Abhängigkeiten installieren
    npm install .
  4. App starten
    node app.js
  5. Öffnen Sie die App, die unter http://localhost:3000 ausgeführt wird.

Beispiel für eine Web-App mit einem Feld zum Eingeben einer E-Mail-Adresse und einer Schaltfläche zum Erstellen eines Passes

Wenn Sie Ihre E‑Mail-Adresse eingeben und Karte erstellen auswählen, passiert nichts. In den nächsten Schritten konfigurieren Sie die App so, dass eine neue Pass-Klasse und ein neues Objekt erstellt werden.

4. Generische Karten-/Ticketklasse erstellen

In diesem Schritt erstellen Sie die Basisklasse für Ihre Karte oder Ihr Ticket. Jedes Mal, wenn eine neue Karte bzw. ein neues Ticket für einen Nutzer erstellt wird, werden die in der Karten-/Ticketklasse definierten Eigenschaften übernommen.

Die Passklasse, die Sie in diesem Codelab erstellen, nutzt die Flexibilität generischer Karten und Tickets, um ein Objekt zu erstellen, das sowohl als Ausweis als auch als Tracker für Challenge-Punkte dient. Wenn ein Karten-/Ticketobjekt aus dieser Klasse erstellt wird, sieht es so aus:

Karten-/Ticketklassen können direkt in der Google Pay & Wallet Console oder über die Google Wallet API erstellt werden. In diesem Codelab erstellen Sie die Klasse für generische Karten bzw. Tickets mithilfe der API. Dies entspricht dem Prozess, den ein privater Back-End-Server zum Erstellen von Kartenklassen verwenden würde.

  1. Öffnen Sie die Datei web/app.js.
  2. Ersetzen Sie den Wert von issuerId durch Ihre Aussteller-ID aus der Google Pay & Wallet Console.
    // TODO: Define Issuer ID
const issuerId = 'ISSUER_ID';
  3. Funktion createPassClass suchen
  4. Erstellen Sie in der Funktion einen authentifizierten HTTP-Client und verwenden Sie die Google Wallet API, um eine neue Kartenklasse zu erstellen.
    // 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!');
  }
}

Wenn Ihr Code ausgeführt wird, wird eine neue Passklasse erstellt und die Klassen-ID ausgegeben. Die Klassen-ID besteht aus der Aussteller-ID, gefolgt von einem vom Entwickler definierten Suffix. In diesem Fall wird das Suffix auf codelab_class festgelegt (die Klassen-ID würde ähnlich wie 1234123412341234123.codelab_class aussehen). Die Ausgabelogs enthalten auch die Antwort der Google Wallet API.

5. Generisches Karten-/Ticketobjekt erstellen

In diesem Schritt konfigurieren Sie Ihre Node.js-App so, dass ein generisches Ticketobjekt mit der Klasse erstellt wird, die Sie zuvor erstellt haben. Es gibt zwei Abläufe zum Erstellen von Karten- und Ticketobjekten für Nutzer.

Kartenobjekt auf dem Backend-Server erstellen

Bei diesem Ansatz wird das Kartenobjekt auf einem Backend-Server erstellt und als signiertes JWT an die Client-App zurückgegeben. Diese Methode eignet sich am besten für Fälle, in denen die Nutzerakzeptanz hoch ist, da so sichergestellt wird, dass das Objekt vorhanden ist, bevor der Nutzer versucht, es seinem Wallet hinzuzufügen.

Karten-/Ticketobjekt erstellen, wenn der Nutzer es seiner Wallet hinzufügt

Bei diesem Ansatz wird das Karten-/Ticketobjekt auf dem Backend-Server definiert und in ein signiertes JWT codiert. In der Client-App wird dann die Schaltfläche Zu Google Wallet hinzufügen gerendert, die auf das JWT verweist. Wenn der Nutzer die Schaltfläche auswählt, wird das JWT verwendet, um das Ticketobjekt zu erstellen. Diese Methode eignet sich am besten für Fälle, in denen die Nutzerakzeptanz variabel oder unbekannt ist, da sie verhindert, dass Pass-Objekte erstellt und nicht verwendet werden. Dieser Ansatz wird im Codelab verwendet.

  1. Öffnen Sie die Datei web/app.js.
  2. Funktion createPassObject suchen
  3. Definieren Sie in der Funktion ein neues Karten-/Ticketobjekt für den Nutzer.
    // 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!");

Wenn Sie die App neu laden, Ihre E-Mail-Adresse eingeben und das Formular absenden, wird keine Ausgabe angezeigt. Das Pass-Objekt wird von der Backend-Anwendung definiert, aber es wird keine Ausgabe zurückgegeben. Als Nächstes wandeln Sie die Karte / das Ticket in einen Zu Google Wallet hinzufügen-Link um.

6. Schaltfläche „Zu Google Wallet hinzufügen“ erstellen

Im letzten Schritt erstellen Sie ein signiertes JWT und geben einen Link zurück, der in der Schaltfläche Zu Google Wallet hinzufügen verwendet werden kann. Wenn der Nutzer die Schaltfläche auswählt, wird er aufgefordert, die Karte/das Ticket in seiner Wallet zu speichern.

  1. Erstellen Sie die JWT-Ansprüche, codieren Sie sie mit dem privaten Schlüssel des Dienstkontos und geben Sie eine Schaltfläche Zu Google Wallet hinzufügen mit dem eingebetteten Link zurück.
    // 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. Aktualisieren Sie die im Browser ausgeführte App.
  3. Geben Sie Ihre E-Mail-Adresse in das Formular ein und wählen Sie Karte erstellen aus.
  4. Wählen Sie die Schaltfläche Zu Google Wallet hinzufügen aus, wenn sie angezeigt wird.

Die Schaltfläche „Zu Google Wallet hinzufügen“ wird im App-Frontend gerendert.

7. Glückwunsch

Beispiel für ein generisches Karten-/Ticketobjekt

Sie haben die Google Wallet API für das Web erfolgreich eingebunden.

Weitere Informationen

Eine vollständige Integration finden Sie im GitHub-Repository google-pay/wallet-web-codelab.

Karten/Tickets erstellen und Produktionszugriff anfordern

Wenn Sie bereit sind, eigene Karten/Tickets in der Produktion auszustellen, rufen Sie die Google Pay & Wallet Console auf, um Produktionszugriff anzufordern.

Weitere Informationen finden Sie unter Voraussetzungen für die Web-API.