Karten/Tickets auf Android mit der Google Wallet API 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

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

Alle Kartenklassen und ‑objekte müssen der Richtlinie zur zulässigen Nutzung entsprechen.

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 in Ihrer Android-App einblenden
7. Ergebnis des Speicherns der Karte/des Tickets verarbeiten

Vorbereitung

• Android Studio
• Git
• Ein Google-Konto mit Zugriff auf die Google Cloud Console
• Node.js-Version 10 oder höher

Ziele

Nach Abschluss dieses Codelabs können Sie Folgendes:

• Google Wallet SDK in Ihre Android-App einbinden
• Prüfen, ob die Google Wallet API auf einem Android-Gerät verfügbar ist
• 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-android-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.

Es ist möglich, Karten-/Ticketklassen und -objekte in öffentlichen Clients wie mobilen Apps zu erstellen. Es ist jedoch sicherer, Karten auf einem privaten Client wie einem Backend-Server zu erstellen oder sie über authentifizierte und sichere Anfragen aus Ihren Clientanwendungen abzurufen.

Für ein Google Wallet API-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.

Seien Sie vorsichtig, wenn Sie ein vorhandenes Dienstkonto für dieses Codelab verwenden, da es möglicherweise Berechtigungen für andere Ressourcen hat, die nicht erforderlich sind.

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. [e-mail]).
5. Wählen Sie im Drop-down-Menü Zugriffsebene entweder Entwickler oder Administrator aus.
6. Wählen Sie Einladen aus.

3. 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:

In dieser Abbildung ist eine kleine Auswahl von Eigenschaften dargestellt, die für eine Karte oder ein Ticket festgelegt werden können. Im allgemeinen Vorlage für Karten/Tickets sehen Sie, wie sich verschiedene Eigenschaften von Karten/Tickets auf die Nutzerfreundlichkeit auswirken.

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. Klonen Sie das GitHub-Repository google-pay/wallet-android-codelab auf Ihre lokale Workstation.

   git clone https://github.com/google-pay/wallet-android-codelab.git
   

2. Geklontes Repository im Terminal oder in der Befehlszeile öffnen
3. Rufen Sie das Verzeichnis backend auf. Diese Skripts imitieren Backend-Serveraktionen.

   cd backend
   

4. Node.js-Abhängigkeiten installieren

   npm install .
   

5. Öffnen Sie im Verzeichnis backend die Datei generic_class.js.
6. Ersetzen Sie den Wert von issuerId durch Ihre Aussteller-ID aus der Google Pay & Wallet Console.

   // TODO: Define Issuer ID
   let issuerId = 'ISSUER_ID';
   

7. Führen Sie das generic_class.js-Skript im Terminal oder an der Befehlszeile aus.

   node generic_class.js
   

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.

4. Projekt in Android Studio öffnen

Das geklonte GitHub-Repository enthält ein Android-Projekt mit einer leeren Aktivität. In diesem Schritt bearbeiten Sie diese Aktivität, um auf einer Produktseite die Schaltfläche Zu Google Wallet hinzufügen einzufügen.

1. Android Studio öffnen
2. Wählen Sie Datei und dann Öffnen aus.
3. Wählen Sie im Repository das Verzeichnis android aus.
4. Wählen Sie Öffnen aus.

Google Wallet SDK in Ihre App einfügen

1. Gradle-Build-Datei auf Modulebene (android/app/build.gradle) öffnen
2. Google Wallet SDK zum Bereich dependencies hinzufügen

   // TODO: Add the "com.google.android.gms:play-services-pay" dependency to
   //       use the Google Wallet API
   implementation "com.google.android.gms:play-services-pay:16.0.3"
   

3. Speichern Sie die Datei.
4. Wählen Sie Datei und dann Projekt mit Gradle-Dateien synchronisieren aus.

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

In diesem Schritt erstellen Sie die Schaltfläche Zu Google Wallet hinzufügen und fügen sie einer vorhandenen Aktivität hinzu. Die Assets für die Schaltfläche wurden bereits in das Projekt aufgenommen. Um die Schaltfläche einzufügen, erstellen Sie eine separate Layoutdatei. Nach dem Hinzufügen sieht die Schaltfläche so aus:

Wenn Sie die Schaltfläche in Ihre eigene Anwendung einfügen, können Sie die SVG-Dateien für die Schaltfläche in der gewünschten Sprache in den Markenrichtlinien herunterladen. Füge nur Grafiken für die unterstützten Konfigurationen ein. Sie können Vektor-Assets in Android Studio unter File > New > Vector Asset importieren. Wählen Sie im Assistenten Lokale Datei aus, geben Sie einen Namen ein (z.B. add_to_google_wallet_button) und suchen Sie die Datei auf Ihrer Workstation.

1. Erstellen Sie eine neue Layoutdatei: app/src/main/res/layout/add_to_google_wallet_button.xml
2. Fügen Sie der neuen Layoutdatei den folgenden Inhalt hinzu.

   <?xml version="1.0" encoding="utf-8"?>
   <FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
       android:layout_width="match_parent"
       android:layout_height="48sp"
       android:background="@drawable/add_to_google_wallet_button_background_shape"
       android:clickable="true"
       android:contentDescription="@string/add_to_google_wallet_button_content_description"
       android:focusable="true">
     <ImageView
         android:layout_width="227dp"
         android:layout_height="26dp"
         android:layout_gravity="center"
         android:duplicateParentState="true"
         android:src="@drawable/add_to_google_wallet_button_foreground" />
   </FrameLayout>
   

3. Fügen Sie das add_to_google_wallet_button.xml-Layout in die Layoutdatei der Checkout-Aktivität (app/src/main/res/layout/activity_checkout.xml) ein.

   <!--
       TODO: Create the button under `add_to_google_wallet_button.xml`
             and include it in your UI
   -->
   <include
       android:id="@+id/addToGoogleWalletButton"
       layout="@layout/add_to_google_wallet_button"
       android:layout_width="match_parent"
       android:layout_height="48dp"
       android:layout_marginTop="10dp" />
   

6. Prüfen, ob die Google Wallet API verfügbar ist

Wenn ein Nutzer Ihre App auf einem Gerät öffnet, das die Google Wallet API nicht unterstützt, kann es zu Problemen kommen, wenn er versucht, die Karte/das Ticket hinzuzufügen. Wenn das Gerät des Nutzers die Google Wallet API nicht unterstützt, wird durch das Ausblenden der Schaltfläche Zu Google Wallet hinzufügen potenzielle Verwirrung vermieden. Es gibt verschiedene Gründe, warum die API möglicherweise nicht verfügbar ist, z. B. eine veraltete Version von Android oder der Google Play-Dienste oder wenn Google Wallet im Land des Nutzers nicht verfügbar ist.

In diesem Schritt fügen Sie Ihrer App Logik hinzu, mit der geprüft wird, ob die Google Wallet API auf dem Gerät verfügbar ist. Wenn ja, wird die Schaltfläche in der Aktivität gerendert. Andernfalls wird die Schaltfläche ausgeblendet.

Sie sollten die domainspezifische Geschäftslogik entsprechend platzieren, wenn Sie andere Designmuster verwenden. Wenn Sie beispielsweise das MVVM-Muster (Model-View-ViewModel) verwenden, platzieren Sie die UI-bezogene Geschäftslogik in Ihrer Aktivität oder Ihrem Fragment (z.B. UI-Elemente und Aktivitätsergebnisse) und die operative Logik im ViewModel (z.B. Client-Instanziierung und Trigger für Netzwerkaufrufe).

1. Öffnen Sie CheckoutActivity.kt in app/src/main/java/com/google/android/gms/samples/wallet/activity/
2. Klassenattribut für die PayClient-Instanz erstellen

   // TODO: Create a client to interact with the Google Wallet API
   private lateinit var walletClient: PayClient
   

3. Instanziieren Sie das Attribut PayClient in der Methode onCreate.

   // TODO: Instantiate the client
   walletClient = Pay.getClient(this)
   

4. Methode erstellen, die prüft, ob das Google Wallet SDK und die API auf dem Gerät verfügbar sind, und das Ergebnis verarbeitet

   // TODO: Create a method to check for the Google Wallet SDK and API
   private fun fetchCanUseGoogleWalletApi() {
     walletClient
       .getPayApiAvailabilityStatus(PayClient.RequestType.SAVE_PASSES)
       .addOnSuccessListener { status ->
         if (status == PayApiAvailabilityStatus.AVAILABLE)
           layout.passContainer.visibility = View.VISIBLE
       }
       .addOnFailureListener {
         // Hide the button and optionally show an error message
       }
   }
   

5. Rufen Sie die Methode fetchCanUseGoogleWalletApi in der Methode onCreate auf, um zu prüfen, ob die Google Wallet API verfügbar ist.

   // TODO: Check if the Google Wallet API is available
   fetchCanUseGoogleWalletApi()
   

Wenn Sie die App ausführen, sollte die Schaltfläche Zu Google Wallet hinzufügen jetzt in der Benutzeroberfläche angezeigt werden.

Wenn die Schaltfläche Zu Google Wallet hinzufügen nicht angezeigt wird, sehen Sie sich den von der Methode getPayApiAvailabilityStatus zurückgegebenen Fehler und die Logs an, um weitere Informationen zu erhalten. Der betreffende Nutzer kann die API möglicherweise in Zukunft verwenden.

7. Generisches Karten-/Ticketobjekt erstellen

Wenn sich Ihr Ausstellerkonto im Demomodus befindet, können Sie nur Karten oder Tickets für Ihre Testnutzer ausstellen. Wenn Sie die App mit einer anderen E-Mail-Adresse ausführen, können Sie die Karte oder das Ticket nicht Ihrem Wallet hinzufügen.

Nachdem Sie überprüft haben, dass die Google Wallet API verfügbar ist, können Sie eine Karte bzw. ein Ticket erstellen und den Nutzer auffordern, sie zu seiner Wallet hinzuzufügen. 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 Passobjekte erstellt und nicht verwendet werden. Dieser Ansatz wird im Codelab verwendet.

1. Öffnen Sie die Datei backend/generic_pass.js.
2. Ersetzen Sie den Wert von issuerId durch Ihre Aussteller-ID aus der Google Pay & Wallet Console.

   // TODO: Define Issuer ID
   let issuerId = 'ISSUER_ID';
   

3. Führen Sie die generic_pass.js-Datei im Terminal oder in der Befehlszeile aus.

   node generic_pass.js
   

4. Ausgabetoken in die Zwischenablage oder einen Texteditor kopieren

Wenn Ihr Code ausgeführt wird, wird ein neues Pass-Objekt definiert und in ein JWT eingebettet. Das JWT wird dann mit dem Dienstkontoschlüssel signiert, den Sie zuvor erstellt haben. Dadurch wird die Anfrage an die Google Wallet API authentifiziert, sodass keine Anmeldedaten in der Client-App gespeichert werden müssen.

aside In einer Produktionsumgebung ist Ihr Backend-System für das Erstellen von JWTs und das Zurückgeben an Clients verantwortlich. In diesem Codelab emuliert das Skript generic_pass.js dieses Verhalten und „gibt“ ein Token zurück, das Sie in der Client-App verwenden können.

8. Karte/Ticket zu Google Wallet hinzufügen

Nachdem Sie überprüft haben, ob die Google Wallet API verfügbar ist, und ein signiertes JWT erstellt haben, können Sie den Nutzer auffordern, die Karte bzw. das Ticket zu seiner Wallet hinzuzufügen. In diesem Schritt fügen Sie der Schaltfläche Zu Google Wallet hinzufügen einen Listener hinzu, der die Google Wallet API verwendet, um die Karte bzw. das Ticket im Wallet des Nutzers zu speichern.

1. Öffnen Sie die Datei app/src/main/CheckoutActivity.kt.
2. Ersetzen Sie den Wert von token durch das zuvor erstellte JWT.

   // TODO: Save the JWT from the backend "response"
   private val token = "TOKEN"
   

3. Klassenattribut zum Speichern des Anforderungscodes erstellen

   // TODO: Add a request code for the save operation
   private val addToGoogleWalletRequestCode = 1000
   

4. Listener für die Schaltfläche Zu Google Wallet hinzufügen festlegen

   // TODO: Set an on-click listener on the "Add to Google Wallet" button
   addToGoogleWalletButton = layout.addToGoogleWalletButton.root
   
   addToGoogleWalletButton.setOnClickListener {
     walletClient.savePassesJwt(token, this, addToGoogleWalletRequestCode)
   }
   

Wenn ein Nutzer die Schaltfläche Zu Google Wallet hinzufügen auswählt, wird die Methode walletClient.savePassesJwt aufgerufen. Mit dieser Methode wird der Nutzer aufgefordert, das neue Karten-/Ticketobjekt zu Google Wallet hinzuzufügen.

9. savePassesJwt-Ergebnis verarbeiten

Im letzten Schritt dieses Codelabs konfigurieren Sie Ihre App so, dass sie das Ergebnis des walletClient.savePassesJwt-Vorgangs verarbeitet.

1. Öffnen Sie die Datei app/src/main/CheckoutActivity.kt.
2. Überschreiben Sie die Methode onActivityResult mit dem folgenden Code.

   // TODO: Handle the result
   override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
     super.onActivityResult(requestCode, resultCode, data)
   
     if (requestCode == addToGoogleWalletRequestCode) {
       when (resultCode) {
         RESULT_OK -> {
           // Pass saved successfully. Consider informing the user.
         }
   
         RESULT_CANCELED -> {
           // Save canceled
         }
   
         PayClient.SavePassesResult.SAVE_ERROR ->
           data?.let { intentData ->
             val errorMessage = intentData.getStringExtra(PayClient.EXTRA_API_ERROR_MESSAGE)
             // Handle error. Consider informing the user.
             Log.e("SavePassesResult", errorMessage.toString())
           }
   
         else -> {
           // Handle unexpected (non-API) exception
         }
       }
     }
   }
   

Ihre App kann jetzt die folgenden Szenarien verarbeiten:

• Karte bzw. Ticket wurde hinzugefügt
• Kündigung durch Nutzer
• Unerwartete Fehler

Führen Sie Ihre App aus, um zu bestätigen, dass Sie die Karte oder das Ticket hinzufügen und das Ergebnis wie erwartet verarbeiten können.

10. Glückwunsch

Sie haben die Google Wallet API erfolgreich in Android eingebunden.

Weitere Informationen

Die vollständige Integration finden Sie im GitHub-Repository google-pay/wallet-android-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 und Ihre Android-App zu autorisieren.

Weitere Informationen finden Sie unter Voraussetzungen für das Android SDK.