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 na stronie internetowej znajdziesz w dokumentacji dla programistów Portfela Google.
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.
- Utwórz nowe konto wydawcy w trybie demonstracyjnym
- Utwórz konto usługi do wystawiania kart
- Tworzenie nowej klasy ogólnej
- Tworzenie nowego obiektu karty
- Utwórz przycisk Dodaj do Portfela Google, aby zapisać kartę
- Wyświetl przycisk na swojej stronie internetowej
- Obsługa wyniku zapisania karty
Wymagania wstępne
- 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:
- Tworzenie obiektów karty za pomocą Portfela Google
- Utwórz przycisk Dodaj do Portfela Google
Pomoc
Jeśli utkniesz w którymś momencie ćwiczenia z programowania, w repozytorium GitHub google-pay/wallet-web-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.
Zakładanie konta wydawcy Portfela Google
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.
- Otwórz aplikację Google Pay & Konsola Portfela
- Aby utworzyć konto wystawcy, postępuj zgodnie z instrukcjami wyświetlanymi na ekranie.
- Wybierz Google Wallet API.
- Potwierdź, że rozumiesz warunki korzystania z usługi i jej politykę prywatności
- Skopiuj wartość Issuer ID (Identyfikator wystawcy) do edytora tekstu lub innej lokalizacji.
- Na karcie Zarządzaj kliknij Skonfiguruj konta testowe.
- Dodaj adresy e-mail, których będziesz używać podczas tego ćwiczenia z programowania
Włączanie Google Wallet API
- Zaloguj się w konsoli Google Cloud.
- 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).
- 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.
Tworzenie konta usługi
- W konsoli Google Cloud otwórz Konta usługi.
- Wpisz nazwę, identyfikator i opis konta usługi
- Wybierz UTWÓRZ I KONTYNUUJ.
- Kliknij GOTOWE.
Tworzenie klucza konta usługi
- Wybierz konto usługi
- Wybierz menu KEYS.
- Wybierz DODAJ KLUCZ, a następnie Utwórz nowy klucz.
- Wybierz typ klucza JSON.
- 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.
- Postępuj zgodnie z instrukcjami podanymi w dokumentacji kluczy konta usługi Google Cloud, aby ustawić zmienną środowiskową
GOOGLE_APPLICATION_CREDENTIALS
. - 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.
- Otwórz aplikację Google Pay & Konsola Portfela
- Wybierz Użytkownicy.
- Kliknij Zaproś użytkownika.
- Wpisz adres e-mail konta usługi (np.
test-svc@myproject.iam.gserviceaccount.com
) - Z menu Poziom dostępu wybierz Programista lub Administrator.
- Kliknij Zaproś.
3. Uruchamianie przykładowej aplikacji Node.js
Czas trwania: 10:00
W tym kroku uruchomisz przykładową aplikację Node.js, która będzie działać jako witryna zakupów i serwer backendu.
Klonowanie przykładowego repozytorium
Repozytorium google-pay/wallet-web-codelab zawiera przykładowy projekt oparty na Node.js oraz różne pliki skryptów, które imitują serwer backendu używany do udostępniania klas i obiektów kart. Możesz je edytować, dodając przycisk Dodaj do Portfela Google na ekranie ze szczegółami produktu.
- Klonowanie repozytorium na lokalną stację roboczą
git clone https://github.com/google-pay/wallet-web-codelab.git
Zainstaluj zależności projektu
- Otwórz sklonowane repozytorium w terminalu lub w wierszu poleceń
- Przejdź do katalogu
web
(to aplikację, którą zmienisz w pozostałej części tego ćwiczenia z programowania).cd web
- Zainstaluj zależności Node.js
npm install .
- Uruchom aplikację
node app.js
- Otwórz aplikację uruchomioną na http://localhost:3000
Jeśli wpiszesz adres e-mail i klikniesz Utwórz kartę, nic się nie wydarzy. W następnych krokach skonfigurujesz aplikację tak, aby tworzyła nową klasę i obiekt karty.
4. 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.
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.
- Otwórz plik
web/app.js
. - Zastąp wartość
issuerId
swoim identyfikatorem wydawcy z Google Pay & Konsola Portfela// TODO: Define Issuer ID const issuerId = 'ISSUER_ID';
- Znajdź funkcję
createPassClass
- W tej funkcji utwórz uwierzytelnionego klienta HTTP i użyj interfejsu Google Wallet API do utworzenia nowej klasy karty.
// 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!'); } }
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.
5. Tworzenie obiektu ogólnej karty
W tym kroku skonfigurujesz aplikację Node.js tak, aby utworzyć obiekt karty ogólnej za pomocą utworzonej wcześniej klasy. 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.
- Otwórz plik
web/app.js
. - Znajdź funkcję
createPassObject
- W funkcji zdefiniuj nowy obiekt karty dla użytkownika
// 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!");
Jeśli załadujesz ponownie aplikację, wpisz swój adres e-mail i prześlij formularz, nie zobaczysz żadnych danych wyjściowych. Obiekt karty jest definiowany przez aplikację backendu, ale nie są zwracane żadne dane wyjściowe. Następnie zmienisz kartę w link Dodaj do Portfela Google.
6. Utwórz Przycisk Dodaj do Portfela Google
W ostatnim kroku utworzysz podpisany token JWT i zwrócisz link, którego można użyć, klikając przycisk Dodaj do Portfela Google. Gdy użytkownik kliknie przycisk, zostanie poproszony o zapisanie karty w portfelu.
- Utwórz żądania JWT, zakoduj je za pomocą klucza prywatnego konta usługi i zwróć przycisk Dodaj do Portfela Google z umieszczonym linkiem
// 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>`);
- Załaduj ponownie aplikację uruchomioną w przeglądarce
- Wpisz swój adres e-mail w formularzu i wybierz Utwórz kartę.
- Kliknij przycisk Dodaj do Portfela Google, gdy się pojawi.
7. Gratulacje
Gratulujemy! Udało Ci się zintegrować interfejs API Portfela Google w przeglądarce.
Więcej informacji
Pełną integrację znajdziesz w repozytorium GitHub google-pay/wallet-web-codelab.
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.
Więcej informacji znajdziesz w wymaganiach wstępnych dotyczących interfejsu Web API.