Mit der Google Wallet API Karten/Tickets im Web erstellen

1. Einführung

Übersicht

Mit der Google Wallet API können Sie mit Nutzern über verschiedene Arten von Karten/Tickets interagieren: Kundenkarten, Angebote, Geschenkkarten, Veranstaltungstickets, Fahrkarten, Bordkarten und mehr. Jeder Karten-/Tickettyp oder -klasse sind nutzungsspezifische Felder und Funktionen zugewiesen, um die Nutzerfreundlichkeit zu verbessern.

Diese eignen sich jedoch möglicherweise nicht für jeden Anwendungsfall. Wenn Sie die Karte/das Ticket noch weiter anpassen möchten, können Sie den generischen Karten-/Tickettyp verwenden. Hier sind einige Anwendungsfälle für den generischen Kartentyp:

  • Parkscheine
  • Bibliotheksausweise
  • Gutscheine für gespeicherte Werte
  • Mitgliedskarten für Fitnessstudios
  • Reservierungen

Sie können generische Karten/Tickets für alle Anwendungsfälle verwenden, die mit folgenden Optionen präsentiert werden können:

  • Bis zu drei Zeilen mit Informationen
  • Optional: Barcodegrafik
  • Optional: Abschnitt „Details“

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 stellt Methoden zum Erstellen folgender Elemente bereit:

Typ

Beschreibung

Karten-/Ticketklasse

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

Karten-/Ticketobjekt

Eine Instanz einer Karten-/Ticketklasse, 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 für die Ausstellung von Karten/Tickets erstellen
  3. Neue generische Karten-/Ticketklasse erstellen
  4. Neues Karten-/Ticketobjekt erstellen
  5. Schaltfläche Zu Google Wallet hinzufügen zum Speichern einer Karte/eines Tickets erstellen
  6. Schaltfläche auf Ihrer Website anzeigen
  7. Ergebnis des Speicherns der Karte/des Tickets verarbeiten

Vorbereitung

Lernziele

Nach Abschluss dieses Codelabs können Sie Folgendes:

  • Karten-/Ticketobjekte 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/Ticket-Klassen und -Objekte erstellen, die den Brieftaschen der Nutzer hinzugefügt werden können. Als Nächstes erstellen Sie ein Google Cloud-Projekt und ein Dienstkonto. Mit diesen werden Karten-/Ticketklassen und -objekte auf die gleiche Weise wie auf einem Backend-Server programmatisch erstellt. Als Nächstes autorisieren Sie das Google Cloud-Dienstkonto zum Verwalten von Karten/Tickets in Ihrem Google Wallet-Ausstellerkonto.

Für ein Google Wallet-Ausstellerkonto registrieren

Zum Erstellen und Verteilen von Karten/Tickets für Google Wallet ist ein Ausstellerkonto erforderlich. Du kannst dich über die Google Pay & Wallet Console registrieren. Zuerst haben Sie Zugriff auf die Erstellung von Karten/Tickets im Demomodus. Das bedeutet, dass nur bestimmte Testnutzer von Ihnen erstellte Karten/Tickets hinzufügen können. Testnutzer können in der Google Pay & Wallet Console verwaltet werden.

Weitere Informationen zum Demomodus finden Sie unter Voraussetzungen für generische Karten/Tickets.

  1. Öffnen Sie die Google Pay & Wallet Console.
  2. Folgen Sie der Anleitung auf dem Bildschirm, um ein Ausstellerkonto zu erstellen.
  3. Wählen Sie Google Wallet API aus.
  4. Bestätigen Sie, dass Sie die Nutzungsbedingungen und die Datenschutzerklärung gelesen und verstanden haben.
  5. Kopieren Sie den Wert für die Aussteller-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ähle ERSTELLEN UND FORTFAHREN aus.
  4. Wähle FERTIG aus.

Dienstkontoschlüssel erstellen

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

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

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 Google Cloud-Dienstkontoschlüsseln, um die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS festzulegen.
  2. Prüfen Sie, ob die Umgebungsvariable in einer neuen Terminalsitzung (MacOS/Linux) oder Befehlszeilensitzung (Windows) festgelegt ist. Möglicherweise müssen Sie eine neue Sitzung starten, wenn bereits eine geöffnet ist.
    echo $GOOGLE_APPLICATION_CREDENTIALS

Dienstkonto autorisieren

Als Nächstes müssen Sie das Dienstkonto zum Verwalten von Google Wallet-Karten/-Tickets autorisieren.

  1. Öffnen Sie die Google Pay & Wallet Console.
  2. Wählen Sie Nutzer aus.
  3. Wähle 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. Beispiel-Node.js-Anwendung starten

Dauer: 10:00

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

Beispiel-Repository klonen

Das Repository google-pay/wallet-web-codelab enthält ein Node.js-basiertes Beispielprojekt und verschiedene Scriptdateien, die einen Back-End-Server simulieren, der für die Bereitstellung von Karten-/Ticketklassen 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. Rufen Sie das Verzeichnis web auf. Dies ist die App, die Sie im restlichen Teil dieses Codelabs ändern werden.
    cd web
  3. Node.js-Abhängigkeiten installieren
    npm install .
  4. App starten
    node app.js
  5. Öffnen Sie die Anwendung, die unter http://localhost:3000 ausgeführt wird.

Beispiel für eine Webanwendung mit einem Feld zum Eingeben einer E-Mail-Adresse und einer Schaltfläche „Karte/Ticket erstellen“

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

4. Generische Karten-/Ticketklasse erstellen

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

Die Karte/das Ticket-Klasse, die Sie in diesem Codelab erstellen, nutzt die Flexibilität von generischen Karten/Tickets, um ein Objekt zu erstellen, das sowohl als Ausweis als auch als Punkte-Tracker für Herausforderungen dient. Wenn ein Karten-/Ticketobjekt aus dieser Klasse erstellt wird, sieht es so aus wie in der folgenden Abbildung.

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 „Generic pass“ (Generisch – Karte/Ticket) mithilfe der API. Dies entspricht dem Verfahren, das ein privater Back-End-Server zum Erstellen von Karten-/Ticketklassen 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. createPassClass-Funktion suchen
  4. Erstellen Sie in der Funktion einen authentifizierten HTTP-Client und verwenden Sie die Google Wallet API, um eine neue Karten-/Ticketklasse 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 der Code ausgeführt wird, wird eine neue Karten-/Ticketklasse erstellt und die Klassen-ID ausgegeben. Die Klassen-ID besteht aus der Aussteller-ID gefolgt von einem vom Entwickler definierten Suffix. In diesem Fall ist das Suffix auf codelab_class festgelegt (die Kurs-ID würde in etwa 1234123412341234123.codelab_class lauten). Die Ausgabeprotokolle enthalten auch die Antwort der Google Wallet API.

5. Generisches Karten-/Ticketobjekt erstellen

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

Karten-/Ticketobjekt auf dem Backend-Server erstellen

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

Das Karten-/Ticketobjekt wird erstellt, wenn der Nutzer es seinem 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 Karten-/Ticketobjekt zu erstellen. Diese Option eignet sich am besten für Fälle, in denen die Akzeptanz der Nutzer variiert oder unbekannt ist, da so verhindert wird, dass Karten-/Ticketobjekte erstellt und nicht verwendet werden. Dieser Ansatz wird im Codelab verwendet.

  1. Öffnen Sie die Datei web/app.js.
  2. createPassObject-Funktion suchen
  3. Definiere 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 einreichen, wird keine Ausgabe angezeigt. Das Karten-/Ticketobjekt wird von der Backend-Anwendung definiert, es wird jedoch keine Ausgabe zurückgegeben. Als Nächstes wandeln Sie die Karte bzw. das Ticket in einen Link vom Typ Zu Google Wallet hinzufügen um.

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

Im letzten Schritt erstellst du ein signiertes JWT und gibst 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 seinem Wallet zu speichern.

  1. Erstelle die JWT-Beanspruchungen, codiere sie mit dem privaten Schlüssel des Dienstkontos und gib die 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. Die im Browser ausgeführte App neu laden
  3. Geben Sie Ihre E-Mail-Adresse in das Formular ein und wählen Sie Karte/Ticket erstellen aus.
  4. Wählen Sie die Schaltfläche Zu Google Wallet hinzufügen aus.

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

7. Glückwunsch

Beispiel für ein generisches Karten-/Ticketobjekt

Sie haben die Google Wallet API erfolgreich in Ihre Webanwendung eingebunden.

Weitere Informationen

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

Karten/Tickets erstellen und Produktionszugriff anfordern

Wenn du bereit bist, eigene Karten/Tickets in der Produktionsumgebung auszustellen, rufe die Google Pay & Wallet Console auf, um Produktionszugriff anzufordern.

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