Tworzenie kart na Androidzie za pomocą interfejsu Google Wallet API

1. Wprowadzenie

Omówienie

Interfejs API Portfela Google umożliwia interakcję z użytkownikami za pomocą różnych typów kart: kart lojalnościowych, ofert, kart podarunkowych, biletów na wydarzenia, biletów transportu publicznego, kart pokładowych i innych. Każdy typ karty (czyli klasa) ma pola i funkcje związane z konkretnym przypadkiem użycia, które zwiększają wygodę użytkowników.

Mogą one jednak nie pasować do każdego zastosowania. Aby uzyskać bardziej spersonalizowane wrażenia, możesz użyć ogólnego typu karty. Oto kilka przykładów użycia ogólnego typu karty:

• bilety parkingowe.
• karty członkowskie biblioteczne,
• kupony ze środkami przedpłaconymi,
• karnety na siłownię,
• Rezerwacje

Standardowych kart możesz używać w każdym przypadku:

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

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

Wszystkie klasy i obiekty kart muszą być zgodne z Zasadami dopuszczalnego użytkowania.

Klasy i obiekty karty

Interfejs API Portfela Google udostępnia metody tworzenia:

Typ	Opis
Klasa biletu	Szablon pojedynczego obiektu karty. Zawiera on informacje wspólne dla wszystkich obiektów kart, które należą do tej klasy.
Obiekt karty	Instancja klasy karty, która jest unikalna dla identyfikatora użytkownika.

Informacje o tych ćwiczeniach z programowania

W ramach tego ćwiczenia w programie wykonasz poniższe zadania.

1. Utwórz nowe konto wydawcy w trybie demonstracyjnym
2. Utwórz konto usługi do wystawiania kart
3. Tworzenie nowej klasy ogólnej
4. Tworzenie nowego obiektu karty
5. Utwórz przycisk Dodaj do Portfela Google, aby zapisać kartę
6. Wyświetlaj przycisk 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 w programie będziesz wiedzieć, jak:

• Dodawanie pakietu SDK Portfela Google do aplikacji na Androida
• Sprawdź, czy interfejs API Portfela Google jest dostępny na urządzeniach z Androidem
• Utwórz przycisk Dodaj do Portfela Google

Pomoc

Jeśli utkniesz w którymś momencie ćwiczenia z programowania, w repozytorium GitHub google-pay/wallet-android-codelab znajdziesz kompletne rozwiązanie.

2. Konfiguracja

W tym kroku utworzysz konto wydawcy w trybie demonstracyjnym. Pozwoli Ci to tworzyć klasy i obiekty kart, które można dodać do portfeli użytkowników. Następnie utwórz projekt i konto usługi Google Cloud. Posłużą one do automatycznego tworzenia klas i obiektów kart w taki sam sposób jak na serwerze backendu. Na koniec autoryzujesz konto usługi Google Cloud do zarządzania kartami na Twoim koncie wydawcy Portfela Google.

Można tworzyć klasy i obiekty kart w klientach publicznych, takich jak aplikacje mobilne. Bezpieczniejsze jest jednak tworzenie kart w prywatnym kliencie, takim jak serwer backendu, lub pobieranie ich z aplikacji klienckich przy użyciu uwierzytelnionych i bezpiecznych żądań.

Rejestrowanie konta wydawcy Google Wallet API

Do tworzenia i dystrybucji kart w Portfelu Google niezbędne jest konto wydawcy. Możesz zarejestrować się za pomocą Google Pay & Konsola Portfela. Początkowo będziesz mieć dostęp do tworzenia kart w trybie demonstracyjnym. Oznacza to, że tylko określeni użytkownicy testowi będą mogli dodawać utworzone przez Ciebie karty. Użytkownikami testowymi można zarządzać w Google Pay Konsola Portfela.

Więcej informacji o trybie demonstracyjnym znajdziesz w artykule Ogólne wymagania wstępne.

1. Otwórz aplikację Google Pay & Konsola Portfela
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 jej politykę prywatności
5. Skopiuj wartość Issuer ID (Identyfikator wystawcy) do edytora tekstu lub innej lokalizacji.
6. Na karcie Zarządzaj kliknij Skonfiguruj konta testowe.
7. Dodaj adresy e-mail, których będziesz używać podczas tego ćwiczenia z programowania

Włączanie Google Wallet API

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

Tworzenie konta usługi i klucza

Do wywoływania interfejsu Google Wallet API wymagane 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, więc zachowaj go jako poufny.

Zachowaj ostrożność podczas korzystania z istniejącego konta usługi do tego ćwiczenia z programowania, 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. Wybierz UTWÓRZ I KONTYNUUJ.
4. Kliknij GOTOWE.

Tworzenie klucza konta usługi

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

Pojawi się prośba o zapisanie pliku z kluczem na lokalnej stacji roboczej. Zapamiętaj jego lokalizację.

Ustawianie zmiennej środowiskowej GOOGLE_APPLICATION_CREDENTIALS

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

1. Postępuj zgodnie z instrukcjami podanymi w dokumentacji kluczy konta usługi Google Cloud, aby ustawić zmienną środowiskową GOOGLE_APPLICATION_CREDENTIALS.
2. Sprawdź, czy zmienna środowiskowa jest ustawiona w nowym terminalu (macOS/Linux) lub sesji wiersza poleceń (Windows) (jeśli masz już otwartą sesję, konieczne może być rozpoczęcie nowej sesji).

   echo $GOOGLE_APPLICATION_CREDENTIALS
   

Autoryzuj konto usługi

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

1. Otwórz aplikację Google Pay & Konsola Portfela
2. Wybierz Użytkownicy.
3. Kliknij Zaproś użytkownika.
4. Wpisz adres e-mail konta usługi (np. [e-mail])
5. Z menu Poziom dostępu wybierz Programista lub Administrator.
6. Kliknij Zaproś.

3. Tworzenie ogólnej klasy karnetu

W tym kroku utworzysz klasę bazową karty. Za każdym razem, gdy zostanie utworzona nowa karta dla użytkownika, odziedziczy ona właściwości zdefiniowane w klasie karty.

Klasa karty utworzona podczas tego ćwiczenia w Codelabs wykorzystuje elastyczność kart ogólnych do utworzenia obiektu, który będzie pełnić funkcję plakietki tożsamości i śledzenia punktów wyzwania. Obiekt karty utworzony z tej klasy będzie wyglądać tak jak na ilustracji poniżej.

Ilustracja pokazująca mały podzbiór właściwości, które można ustawić na karcie. Zapoznaj się z ogólnym szablonem karty, aby sprawdzić, jak różne właściwości karty wpływają na wrażenia użytkownika.

Zajęcia wejściowe można tworzyć bezpośrednio w Google Pay Konsola Portfela lub interfejs API Portfela Google. W ramach tego ćwiczenia w Codelabs utworzysz klasę Ogólna za pomocą interfejsu API. Tak wygląda proces, którego używa prywatny serwer backendu do tworzenia klas kart.

1. Skopiuj repozytorium GitHub google-pay/wallet-android-codelab na lokalną stację roboczą

   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 (skrypty imitujące działania serwera backendu)

   cd backend
   

4. Zainstaluj zależności Node.js

   npm install .
   

5. W katalogu backend otwórz aplikację generic_class.js
6. Zastąp wartość issuerId swoim identyfikatorem wydawcy z Google Pay & Konsola Portfela

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

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

   node generic_class.js
   

Uruchomienie kodu spowoduje utworzenie nowej klasy karty i wyświetlenie identyfikatora klasy. Identyfikator klasy składa się z identyfikatora wydawcy, po którym następuje sufiks zdefiniowany przez programistę. W tym przypadku sufiks jest ustawiony na codelab_class (identyfikator klasy wygląda podobnie do 1234123412341234123.codelab_class). Logi wyjściowe będą też zawierać odpowiedź z interfejsu API Portfela Google.

4. Otwórz projekt w Android Studio

Sklonowane repozytorium GitHub zawiera projekt na Androida z pustym działaniem. W tym kroku zmodyfikujesz aktywność, dodając przycisk Dodaj do Portfela Google na stronie produktu.

1. Otwórz Android Studio
2. Wybierz Plik, a następnie Otwórz.
3. Wybierz katalog android w repozytorium
4. Wybierz Otwórz.

Dodaj pakiet SDK Portfela Google do aplikacji

1. Otwórz plik kompilacji 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. Wybierz Plik, a następnie Synchronizuj projekt z plikami Gradle.

5. Utwórz Przycisk Dodaj do Portfela Google

W tym kroku utworzysz przycisk Dodaj do Portfela Google i dodasz go do istniejącej aktywności. Zasoby przycisku zostały już uwzględnione w projekcie. Jeśli chcesz dodać przycisk, utworzysz oddzielny plik układu. Po dodaniu przycisk będzie wyglądać tak.

Jeśli dodajesz przycisk do swojej aplikacji, zapoznaj się ze wskazówkami dotyczącymi marki, aby pobrać pliki SVG dla tego przycisku w językach, które odpowiadają Twoim potrzebom. Pamiętaj, aby dołączyć grafikę tylko w przypadku obsługiwanych konfiguracji. Zasoby wektorowe możesz importować w Android Studio w sekcji Plik > Nowe > Zasób wektorowy. W kreatorze wybierz Plik lokalny, wpisz nazwę (np. add_to_google_wallet_button) i znajdź plik na swojej stacji roboczej.

1. Utwórz nowy plik układu: app/src/main/res/layout/add_to_google_wallet_button.xml
2. Dodaj tę treść do nowego pliku układu

   <?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 układu działań związanych z procesem płatności (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 interfejs Google Wallet API jest dostępny

Jeśli użytkownik otworzy aplikację na urządzeniu, które nie obsługuje interfejsu Google Wallet API, dodanie karty może negatywnie wpłynąć na wrażenia użytkownika. Jeśli urządzenie użytkownika nie obsługuje interfejsu Google Wallet API, ukrycie przycisku Dodaj do Portfela Google pozwala uniknąć nieporozumień. Istnieją różne powody, dla których interfejs API może być niedostępny, na przykład nieaktualne wersje Androida lub Usług Google Play lub Portfel Google jest niedostępny w kraju użytkownika.

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

Jeśli korzystasz z innych wzorców, rozważ odpowiednie umieszczenie logiki biznesowej związanej z konkretną domeną. Jeśli na przykład używasz wzorca Model-View-ViewModel (MVVM), umieść logikę biznesową związaną z interfejsem w swojej aktywności lub fragmencie (np. elementy interfejsu i wyniki działań) oraz logikę operacyjną w modelu ViewModel (np. wystąpienia klienta i aktywatory wywołań sieciowych).

1. Otwórz plik CheckoutActivity.kt w narzędziu 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. Utwórz instancję właściwości PayClient w metodzie onCreate

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

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

   // 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 metodzie onCreate, aby sprawdzić, czy interfejs Google Wallet API jest dostępny

   // 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 nie widzisz przycisku Dodaj do Portfela Google, sprawdź błąd zwrócony przez metodę getPayApiAvailabilityStatus oraz dzienniki, by dowiedzieć się więcej. Użytkownik, o którym mowa, może uzyskać możliwość korzystania z tego interfejsu w przyszłości.

7. Tworzenie obiektu Ogólna karta

Jeśli Twoje konto wydawcy jest w trybie demonstracyjnym, możesz wydawać karty tylko użytkownikom testowym. Jeśli uruchomisz aplikację przy użyciu innego adresu e-mail, nie będzie można dodać karty do portfela.

Po potwierdzeniu, że interfejs API Portfela Google jest dostępny, możesz utworzyć kartę i poprosić użytkownika o dodanie jej do portfela. Obiekty kart dla użytkowników można tworzyć na 2 sposoby.

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. Najlepiej sprawdza się w przypadku wysokiego rozpowszechnienia, ponieważ pozwala zapewnić istnienie obiektu, zanim użytkownik spróbuje dodać go do portfela.

Utwórz obiekt karty, gdy użytkownik doda go do swojego portfela

W tym podejściu obiekt karty jest zdefiniowany i zakodowany w podpisanym tokenie JWT na serwerze backendu. Następnie w aplikacji klienckiej, która odwołuje się do tokena JWT, renderowany jest przycisk Dodaj do Portfela Google. Gdy użytkownik kliknie przycisk, do utworzenia obiektu karty zostanie użyty token JWT. Najlepiej sprawdza się w przypadkach, gdy rozpowszechnienie użytkownika jest zmienne lub nieznane, ponieważ uniemożliwia tworzenie i nieużywanie obiektów kart. Ta metoda zostanie użyta w ćwiczeniach z programowania.

1. Otwórz plik backend/generic_pass.js.
2. Zastąp wartość issuerId swoim identyfikatorem wydawcy z Google Pay & Konsola Portfela

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

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

   node generic_pass.js
   

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

Gdy Twój kod zostanie uruchomiony, zdefiniuje nowy obiekt karty i umieścisz go w tokenie JWT. Token JWT jest następnie podpisywany za pomocą utworzonego wcześniej klucza konta usługi. Spowoduje to uwierzytelnienie żądania do interfejsu Google Wallet API, dzięki czemu dane logowania nie muszą być zapisywane w aplikacji klienckiej.

W środowisku produkcyjnym system backendu odpowiada za tworzenie tokenów JWT i zwracanie ich klientom. W tym ćwiczeniu w Codelabs skrypt generic_pass.js emuluje to zachowanie i metodę „returns” token, którego możesz używać w aplikacji klienckiej.

8. Dodaj kartę do Portfela Google

Po potwierdzeniu, że interfejs API Portfela Google jest dostępny, i utworzeniu podpisanego tokena JWT, możesz poprosić użytkownika o dodanie karty do portfela. W tym kroku dodasz detektor do przycisku Dodaj do Portfela Google, który za pomocą interfejsu API Portfela Google zapisuje kartę w portfelu użytkownika.

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

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

3. Utwórz właściwość klasy do przechowywania kodu żądania

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

4. Ustaw detektor 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 klika przycisk Dodaj do Portfela Google, wywoływana jest metoda walletClient.savePassesJwt. Ta metoda powoduje wyświetlenie użytkownikowi prośby o dodanie obiektu nowej karty do Portfela Google.

9. Wykonaj wynik savePassesJwt

W ostatnim kroku tego ćwiczenia w Codelabs skonfigurujesz aplikację tak, 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 następujący 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łużyć takie sytuacje:

• Karta została dodana
• Anulowanie przez użytkownika
• Nieoczekiwane błędy

Uruchom aplikację, aby potwierdzić, że możesz dodać kartę i obsługiwać wynik zgodnie z oczekiwaniami.

10. Gratulacje

Gratulujemy! Udało Ci się zintegrować interfejs API Portfela Google na Androidzie.

Więcej informacji

Całą integrację znajdziesz w repozytorium google-pay/wallet-android-codelab na GitHubie.

Tworzenie kart i prośba o dostęp produkcyjny

Jeśli chcesz wystawiać własne karty w wersji produkcyjnej, otwórz stronę Google Pay Konsola Portfela, by poprosić o dostęp produkcyjny i autoryzować aplikację na Androida.

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