Tworzenie kart na Androidzie za pomocą interfejsu Google Wallet API

1. Wprowadzenie

Przegląd

Interfejs Google Wallet API umożliwia interakcję z użytkownikami za pomocą różnych rodzajów kart: kart lojalnościowych, ofert, kart podarunkowych, biletów na wydarzenia, biletów na przejazdy, kart pokładowych i innych. Każdy typ karty (klasa karty) zawiera pola i funkcje dostosowane do konkretnych zastosowań, aby zwiększyć wygodę użytkowników.

Nie wszystkie jednak nadają się do każdego zastosowania. Aby spersonalizować kartę, możesz użyć typu karty ogólnej. Oto kilka przykładowych zastosowań typu dokumentu ogólnego:

• bilety parkingowe.
• Karty wspierania biblioteki
• Bony z wartością do wykorzystania
• Karty członkostwa na siłownię
• Rezerwacje

Dokumenty ogólne możesz wykorzystać w dowolnym przypadku użycia, który może obejmować:

• Maksymalnie 3 wiersze informacji
• (Opcjonalnie) Grafika kodu kreskowego
• (Opcjonalnie) Sekcja szczegółów

Więcej informacji o Google Wallet API lub dodawaniu do aplikacji na Androida przycisku Dodaj do Portfela Google znajdziesz w dokumentacji dla programistów Portfela Google.

Wszystkie klasy i obiekty kart muszą być zgodne z zasadami dozwolonego użytku.

Przekazywanie klas i obiektów

Interfejs Google Wallet API udostępnia metody umożliwiające tworzenie tych elementów:

Typ	Opis
Klasa karty	Szablon obiektu pojedynczej karty. Zawiera informacje wspólne dla wszystkich obiektów pass należących do tej klasy.
Obiekt pass	instancja klasy karty, która jest unikalna dla identyfikatora użytkownika.

Informacje o tych ćwiczeniach z programowania

W tym ćwiczeniu będziesz wykonywać te czynności.

1. Tworzenie nowego konta wydawcy w trybie demonstracyjnym
2. Tworzenie konta usługi do wydawania kart
3. Tworzenie nowej klasy karty standardowej
4. Tworzenie nowego obiektu karty
5. Tworzenie przycisku Dodaj do Portfela Google, aby zapisać kartę
6. Wyświetlanie przycisku w aplikacji na Androida
7. Obsługa wyniku zapisania karty

Wymagania wstępne

• Android Studio
• Git
• Konto Google z dostępem do konsoli Google Cloud
• Node.js w wersji 10 lub nowszej.

Cele

Po ukończeniu tego ćwiczenia będziesz mieć możliwość:

• Dodawanie pakietu SDK Portfela Google do aplikacji na Androida
• Sprawdzanie, czy interfejs Google Wallet API jest dostępny na urządzeniu z Androidem
• Tworzenie przycisku Dodaj do Portfela Google

Pomoc

Jeśli utkniesz w jakimś miejscu w codelab, w repozytorium GitHub google-pay/wallet-android-codelab znajdziesz kompletne rozwiązanie.

2. Konfiguracja

W tym kroku utworzysz konto wydawcy w trybie demonstracyjnym. Umożliwi to tworzenie klas kart i obiektów, które można dodawać do portfeli użytkowników. Następnie utwórz projekt i konto usługi Google Cloud. Będą one służyć do tworzenia za pomocą programów klas i obiektów kart w taki sam sposób jak serwer backendu. Na koniec autoryzujesz konto usługi Google Cloud do zarządzania kartami na koncie wystawcy Portfela Google.

Klasy i obiekty kart można tworzyć w publicznych klientach, takich jak aplikacje mobilne. Bardziej bezpieczne jest jednak tworzenie kart na prywatnym kliencie, takim jak serwer zaplecza, lub pobieranie ich z aplikacji klienta za pomocą uwierzytelnionych i bezpiecznych żądań.

Rejestrowanie konta wydawcy Google Wallet API

Aby tworzyć i rozpowszechniać karty w Google Wallet, musisz mieć konto Issuer. Możesz się zarejestrować w Konsoli usług Google Pay i Portfela Google. Na początku będziesz mieć dostęp do tworzenia kart w trybie demonstracyjnym. Oznacza to, że tylko wybrani użytkownicy testowi będą mogli dodawać utworzone przez Ciebie karty. Użytkownikami testowymi można zarządzać w Konsoli usług Google Pay i Portfela Google.

Więcej informacji o trybie demonstracyjnym znajdziesz w wymaganiach wstępnych dotyczących ogólnego dokumentu przejściowego.

1. Otwórz Konsolę usług Google Pay i Portfela Google.
2. Aby utworzyć konto wystawcy, postępuj zgodnie z instrukcjami wyświetlanymi na ekranie
3. Wybierz Google Wallet API.
4. Potwierdź, że rozumiesz warunki korzystania z usługi i politykę prywatności
5. Skopiuj wartość Issuer ID do edytora tekstu lub innego miejsca.
6. Na karcie Zarządzaj wybierz Skonfiguruj konta testowe.
7. Dodaj adresy e-mail, których będziesz używać w tym CodeLab.

Włączanie interfejsu Google Wallet API

1. Zaloguj się w konsoli Google Cloud.
2. Jeśli nie masz jeszcze projektu Google Cloud, utwórz go (więcej informacji znajdziesz w artykule Tworzenie projektów i zarządzanie nimi).
3. Włącz w projekcie interfejs Google Wallet API (nazywany też interfejsem Google Pay for Passes API).

Tworzenie konta usługi i klucza

Do wywołania interfejsu Google Wallet API potrzebne są konto usługi i klucz konta usługi. Konto usługi to tożsamość, która wywołuje interfejs Google Wallet API. Klucz konta usługi zawiera klucz prywatny, który identyfikuje Twoją aplikację jako konto usługi. Ten klucz jest poufny, dlatego zachowaj go w tajemnicy.

Używając w tym ćwiczeniu istniejącego konta usługi, zachowaj ostrożność, ponieważ może ono mieć uprawnienia do innych zasobów, które nie są wymagane.

Tworzenie konta usługi

1. W konsoli Google Cloud otwórz Konta usługi.
2. Wpisz nazwę, identyfikator i opis konta usługi
3. Kliknij UTWÓRZ I KONTYNUUJ.
4. Kliknij GOTOWE.

Tworzenie klucza konta usługi

1. Wybierz konto usługi
2. Wybierz menu KEYS.
3. Kliknij DODAJ KLUCZ, a następnie Utwórz nowy klucz.
4. Wybierz typ klucza JSON.
5. Kliknij UTWÓRZ.

Wyświetli się prośba o zapisanie pliku klucza na lokalnej stacji roboczej. Zapamiętaj jego lokalizację.

Ustaw zmienną środowiskową GOOGLE_APPLICATION_CREDENTIALS

Zmienna środowiskowa GOOGLE_APPLICATION_CREDENTIALS jest używana przez pakiety SDK Google do uwierzytelniania się jako konto usługi i do uzyskiwania dostępu do różnych interfejsów API w ramach projektu Google Cloud.

1. Aby ustawić zmienną środowiskową GOOGLE_APPLICATION_CREDENTIALS, wykonaj instrukcje podane w dokumentacji dotyczącej kluczy do kont usługi Google Cloud.
2. Sprawdź, czy zmienna środowiskowa jest ustawiona w nowej sesji terminala (MacOS/Linux) lub linii komend (Windows) (jeśli masz już otwartą sesję, może być konieczne rozpoczęcie nowej).

   echo $GOOGLE_APPLICATION_CREDENTIALS
   

Autoryzowanie konta usługi

Na koniec musisz autoryzować konto usługi do zarządzania kartami Google Wallet.

1. Otwórz Konsolę usług Google Pay i Portfela Google.
2. Wybierz Użytkownicy.
3. Kliknij Zaproś użytkownika.
4. Wpisz adres e-mail konta usługi ([e-mail]).
5. W menu Poziom dostępu kliknij Deweloper lub Administrator.
6. Kliknij Zaproś.

3. Tworzenie klasy karty standardowej

W tym kroku utworzysz klasę podstawową dla dokumentu. Za każdym razem, gdy dla użytkownika zostanie utworzony nowy dokument, odziedziczy on właściwości zdefiniowane w klasie dokumentu.

Klasa dokumentu, którą utworzysz w ramach tego ćwiczenia, korzysta z elastyczności dokumentów ogólnych, aby utworzyć obiekt, który działa zarówno jako identyfikator, jak i śledzik punktów wyzwań. Gdy obiekt karty zostanie utworzony z tej klasy, będzie wyglądać tak jak na poniższej grafice.

Grafika przedstawia niewielką podgrupę właściwości, które można ustawić w przesyłaniu. Aby dowiedzieć się, jak różne właściwości karty wpływają na wrażenia użytkownika, zapoznaj się ze szablonem ogólnej karty.

Klasy kart można tworzyć bezpośrednio w Konsoli usług Google Pay i Portfela Google lub za pomocą interfejsu Google Wallet API. W tym ćwiczeniu w Codelab utworzysz klasę Generic pass za pomocą interfejsu API. Jest to proces, którego używa prywatny serwer zaplecza do tworzenia klas kart.

1. Sklonuj repozytorium GitHub google-pay/wallet-android-codelab na swojej stacji roboczej

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

2. Otwórz sklonowane repozytorium w terminalu lub w wierszu poleceń.
3. Przejdź do katalogu backend (te skrypty naśladują działania serwera w tle).

   cd backend
   

4. Zainstaluj zależności Node.js:

   npm install .
   

5. W katalogu backend otwórz generic_class.js.
6. Zastąp wartość issuerId identyfikatorem wydawcy z Konsoli usług Google Pay i Portfela Google

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

7. W terminalu lub w wierszu poleceń uruchom skrypt generic_class.js.

   node generic_class.js
   

Gdy kod zostanie uruchomiony, utworzy nową klasę karty i wyświetli identyfikator klasy. Identyfikator klasy składa się z identyfikatora wydawcy i sufiksa zdefiniowanego przez dewelopera. W tym przypadku sufiks ma wartość codelab_class (identyfikator klasy będzie wyglądał podobnie do 1234123412341234123.codelab_class). Dzienniki wyjściowe będą zawierać również odpowiedź z Google Wallet API.

4. Otwórz projekt w Android Studio.

Sklonowane repozytorium GitHub zawiera projekt na Androida z pustą aktywnością. W tym kroku zmodyfikujesz tę aktywność, aby dodać przycisk Dodaj do Portfela Google na stronie produktu.

1. Otwórz Android Studio
2. Kliknij kolejno Plik i Otwórz.
3. W repozytorium wybierz katalog android.
4. Wybierz Otwórz.

Dodawanie pakietu SDK Portfela Google do aplikacji

1. Otwórz plik Gradle na poziomie modułu (android/app/build.gradle).
2. Dodaj pakiet SDK Portfela Google do sekcji dependencies

   // 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. Zapisz plik.
4. Kliknij kolejno Plik i Synchronizuj projekt z plikami Gradle.

5. Tworzenie przycisku „Dodaj do Portfela Google”

W tym kroku utworzysz przycisk Dodaj do Portfela Google i dodasz go do istniejącej aktywności. Komponenty przycisku zostały już uwzględnione w projekcie. Aby uwzględnić przycisk, utwórz osobny plik układu. Dodany przycisk będzie wyglądał tak:

Jeśli dodajesz przycisk do własnej aplikacji, zapoznaj się z wytycznymi dotyczącymi marki, aby pobrać pliki SVG przycisku w odpowiednich językach. Pamiętaj, aby uwzględnić tylko grafiki dla obsługiwanych konfiguracji. Zasoby wektorowe możesz importować w Android Studio w sekcji Plik > Nowy > Zasób wektorowy. W kreatorze kliknij Plik lokalny, wpisz nazwę (np. add_to_google_wallet_button) i wskaż plik na stacji roboczej.

1. Utwórz nowy plik układu: app/src/main/res/layout/add_to_google_wallet_button.xml
2. Dodaj do nowego pliku układu te elementy:

   <?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. Uwzględnij układ add_to_google_wallet_button.xml w pliku z układem aktywności związanej z płatnościami (app/src/main/res/layout/activity_checkout.xml).

   <!--
       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. Sprawdzanie, czy Google Wallet API jest dostępne

Jeśli użytkownik otworzy Twoją aplikację na urządzeniu, które nie obsługuje interfejsu Google Wallet API, może mieć problemy z dodaniem karty. Jeśli urządzenie użytkownika nie obsługuje interfejsu Google Wallet API, ukrycie przycisku Dodaj do Portfela Google zapobiegnie potencjalnym nieporozumieniom. Interfejs API może być niedostępny z różnych powodów, np. gdy wersje Androida lub Usług Google Play są nieaktualne lub gdy Google Wallet jest niedostępny w kraju użytkownika.

W tym kroku dodasz do aplikacji logikę, która sprawdza, czy interfejs Google Wallet API jest dostępny na urządzeniu. Jeśli tak, przycisk zostanie wyświetlony w aktywności. W przeciwnym razie przycisk będzie ukryty.

Jeśli używasz innych wzorów projektowania, rozważ odpowiednie umieszczenie logiki biznesowej specyficznej dla danej domeny. Jeśli na przykład używasz wzorca Model-View-ViewModel (MVVM), umieść logikę biznesową związaną z interfejsem użytkownika w aktywności lub fragmencie (np. elementy interfejsu użytkownika i wyniki aktywności) oraz logikę operacyjną w Twoim widoku modelu (np. instancjowanie klienta i wyzwalacze wywołań sieci).

1. Otwórz plik CheckoutActivity.kt w app/src/main/java/com/google/android/gms/samples/wallet/activity/
2. Utwórz właściwość klasy dla instancji PayClient.

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

3. Tworzenie wystąpienia właściwości PayClient w metodie onCreate

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

4. Utwórz metodę, która sprawdza, czy na urządzeniu są dostępne SDK i interfejs API Portfela Google, oraz obsługuje wynik.

   // 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. Wywołaj metodę fetchCanUseGoogleWalletApi w ramach metody onCreate, aby sprawdzić, czy Google Wallet API jest dostępne

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

Po uruchomieniu aplikacji w interfejsie powinien pojawić się przycisk Dodaj do Portfela Google.

Jeśli przycisk Dodaj do Portfela Google nie pojawia się, sprawdź błąd zwrócony przez metodę getPayApiAvailabilityStatus i dzienniki, aby dowiedzieć się więcej. Użytkownik, którego dotyczy problem, może w przyszłości uzyskać uprawnienia do korzystania z interfejsu API.

7. Tworzenie obiektu ogólnego dokumentu

Jeśli Twoje konto wydawcy jest w trybie demonstracyjnym, możesz wydawać karty tylko dla użytkowników testowych. Jeśli uruchomisz aplikację, używając innego adresu e-mail, nie będzie można dodać karty do portfela.

Po zweryfikowaniu, że interfejs Google Wallet API jest dostępny, możesz utworzyć kartę i poprosić użytkownika o dodanie jej do portfela. Istnieją 2 metody tworzenia obiektów kart dla użytkowników.

Tworzenie obiektu karty na serwerze backendu

W tym podejściu obiekt karty jest tworzony na serwerze backendu i zwracany do aplikacji klienckiej jako podpisany token JWT. Ta opcja najlepiej sprawdza się w przypadkach, gdy wskaźnik korzystania przez użytkowników jest wysoki, ponieważ zapewnia, że obiekt istnieje, zanim użytkownik spróbuje go dodać do portfela.

Utwórz obiekt karty, gdy użytkownik doda ją do portfela

W tym podejściu obiekt karty jest definiowany i kodowany w podpisanym tokenie JWT na serwerze zaplecza. W aplikacji klienckiej, która odwołuje się do tokena JWT, wyświetla się przycisk Dodaj do Portfela Google. Gdy użytkownik kliknie przycisk, token JWT jest używany do tworzenia obiektu karty. Ta opcja najlepiej sprawdza się w przypadkach, gdy stosowanie przez użytkowników jest zmienne lub nieznane, ponieważ zapobiega tworzeniu i nieużywaniu obiektów pass. To podejście zostanie wykorzystane w ćwiczeniach z programowania.

1. Otwórz plik backend/generic_pass.js.
2. Zastąp wartość issuerId identyfikatorem wydawcy z Konsoli usług Google Pay i Portfela Google

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

3. W terminalu lub w wierszu poleceń uruchom plik generic_pass.js.

   node generic_pass.js
   

4. Skopiuj token wyjściowy do schowka lub edytora tekstu.

Gdy kod zostanie uruchomiony, zdefiniuje nowy obiekt pass i wstawi go do tokena JWT. Następnie token JWT jest podpisywany kluczem konta usługi utworzonym wcześniej. Dzięki temu żądanie jest uwierzytelniane w interfejsie Google Wallet API, co pozwala uniknąć przechowywania danych logowania w aplikacji klienta.

W środowisku produkcyjnym Twój system backendowy będzie odpowiedzialny za tworzenie tokenów JWT i przekazywanie ich klientom. W tym laboratorium kodu skrypt generic_pass.js emuluje to zachowanie i „zwraca” token do użycia w aplikacji klienta.

8. Dodawanie karty do Portfela Google

Po zweryfikowaniu, że interfejs Google Wallet API jest dostępny, i utworzeniu podpisanego tokena JWT możesz poprosić użytkownika o dodanie karty do portfela. W tym kroku dodasz do przycisku Dodaj do Portfela Google listenera, który używa interfejsu Google Wallet API do zapisywania karty w portfelu użytkownika.

1. Otwórz plik app/src/main/CheckoutActivity.kt.
2. Zastąp wartość token utworzonym wcześniej tokenem JWT.

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

3. Tworzenie właściwości klasy na potrzeby przechowywania kodu żądania

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

4. Ustaw listenera dla przycisku Dodaj do Portfela Google.

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

Gdy użytkownik kliknie przycisk Dodaj do Portfela Google, zostanie wywołana metoda walletClient.savePassesJwt. Ta metoda powoduje wyświetlenie użytkownikowi prośby o dodanie nowego obiektu karty do Portfela Google.

9. Obsługa wyniku savePassesJwt

W ostatnim kroku tego ćwiczenia skonfigurujesz aplikację, aby obsługiwała wynik operacji walletClient.savePassesJwt.

1. Otwórz plik app/src/main/CheckoutActivity.kt.
2. Zastąp metodę onActivityResult, aby zawierała ten kod:

   // 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
         }
       }
     }
   }
   

Teraz aplikacja może obsługiwać te scenariusze:

• Dodano kartę
• Anulowanie przez użytkownika
• Nieoczekiwane błędy

Uruchom aplikację, aby sprawdzić, czy możesz dodać kartę i otrzymać oczekiwany wynik.

10. Gratulacje

Gratulacje! Udało Ci się zintegrować interfejs Google Wallet API na Androidzie.

Więcej informacji

Zapoznaj się z pełną integracją w repozytorium GitHub google-pay/wallet-android-codelab.

Tworzenie kart i zgłaszanie prośby o dostęp produkcyjny

Gdy będziesz gotowy do wydawania własnych kart w wersji produkcyjnej, otwórz Konsolę Google Pay i Portfela Google, aby poprosić o dostęp produkcyjny i autoryzować aplikację na Androida.

Więcej informacji znajdziesz w wymaganiach wstępnych pakietu Android SDK.