Tworzenie kart w przeglądarce za pomocą interfejsu API Portfela Google

Tworzenie kart w internecie za pomocą interfejsu Google Wallet API

Informacje o tym ćwiczeniu (w Codelabs)

Ostatnia aktualizacja: sty 19, 2023

Autorzy: Nick Alteen

1. Wprowadzenie

Omówienie

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) ma pola i funkcje dostosowane do konkretnych zastosowań, aby zwiększyć wygodę użytkowników.

Nie wszystkie jednak mogą być odpowiednie do każdego przypadku użycia. Aby stworzyć bardziej spersonalizowane rozwiązanie, możesz użyć ogólnego typu karty. Oto kilka przykładowych zastosowań typu ogólnego:

• Karty parkingowe
• karty biblioteczne,
• Bony z wartością do wykorzystania
• Karty członkowskie 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 interfejsie API Portfela Google lub dodawaniu do strony internetowej przycisku Dodaj do Portfela Google znajdziesz w dokumentacji dla programistów Portfela Google.

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

Przekazywanie klas i obiektów

Interfejs Google Wallet API udostępnia metody do tworzenia:

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 wykonasz te zadania.

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 na stronie internetowej
7. 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 będziesz mieć możliwość:

• Tworzenie obiektów kart w Portfelu Google
• Tworzenie przycisku Dodaj do Portfela Google

Pomoc

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

2. Konfiguracja

Na tym etapie utworzysz konto wydawcy w trybie demonstracyjnym. Dzięki temu możesz tworzyć klasy i obiekty kart, 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 programowo klas i obiektów kart w taki sam sposób jak serwer backendu. Na koniec autoryzujesz konto usługi Google Cloud, aby mogło zarządzać kartami na koncie wystawcy Google Wallet.

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

Rejestracja konta płatnika w Portfelu Google

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 utworzonego 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 API Portfela Google (nazywany też interfejsem API Google Pay for Passes).

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 KLUC, 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 Google SDK do uwierzytelniania się jako konto usługi i uzyskiwania dostępu do różnych interfejsów API w projekcie Google Cloud.

1. Aby ustawić zmienną środowiskową GOOGLE_APPLICATION_CREDENTIALS, wykonaj instrukcje podane w dokumentacji dotyczącej kluczy kont usługi Google Cloud.
2. Sprawdź, czy zmienna środowiskowa jest ustawiona w nowej sesji terminala (MacOS/Linux) lub wiersza poleceń (Windows) (jeśli masz już otwartą sesję, może być konieczne uruchomienie 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. Uruchom przykładową aplikację Node.js

Czas trwania: 10:00

W tym kroku uruchomisz przykładową aplikację Node.js, która pełni funkcję strony sklepu internetowego i serwera backendu.

Klonowanie przykładowego repozytorium

Repozytorium google-pay/wallet-web-codelab zawiera przykładowy projekt oparty na Node.js oraz różne pliki skryptu, które naśladują serwer zaplecza używany do obsługi klas i obiektów kart. Musisz je edytować, aby na ekranie ze szczegółami produktu pojawił się przycisk Dodaj do Portfela Google.

1. Klonowanie repozytorium na lokalnym komputerze roboczym

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

Instalowanie zależności projektu

1. Otwórz sklonowane repozytorium w terminalu lub w wierszu poleceń.
2. Przejdź do katalogu web (to aplikacja, którą zmodyfikujesz w dalszej części tego ćwiczenia).

   cd web
   

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

   npm install .
   

4. Uruchom aplikację

   node app.js
   

5. Otwórz aplikację działającą pod adresem http://localhost:3000.

Jeśli wpiszesz swój adres e-mail i klikniesz Utwórz kartę, nic się nie stanie. W kolejnych krokach skonfigurujesz aplikację, aby utworzyć nową klasę i obiekt dokumentu.

4. Tworzenie klasy dokumentu ogólnego

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 licznik punktów za wyzwania. Gdy obiekt karty zostanie utworzony z tej klasy, będzie wyglądać tak jak na poniższej grafice.

Grafika przedstawiająca niewielką podgrupę właściwości, które można ustawić w przepustce. Zapoznaj się z uniwersalnym szablonem karty, aby dowiedzieć się, jak różne właściwości karty wpływają na wrażenia użytkowników.

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

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

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

3. Znajdź funkcję createPassClass.
4. W ramach funkcji utwórz uwierzytelnionego klienta HTTP i użyciem interfejsu Google Wallet API utwórz nową klasę 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!');
     }
   }
   

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). Logi wyjściowe będą zawierać również odpowiedź z Google Wallet API.

5. Tworzenie obiektu ogólnego dokumentu

W tym kroku skonfigurujesz aplikację Node.js, aby tworzyła obiekt Generic pass za pomocą utworzonej wcześniej klasy. 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 dokumentu, gdy użytkownik doda go 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 przejścia. Tego podejścia użyjemy w tym laboratorium.

1. Otwórz plik web/app.js.
2. Znajdź funkcję createPassObject.
3. 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 ponownie wczytasz aplikację, wpiszesz swój adres e-mail i prześlesz formularz, nie zobaczysz żadnego wyniku. Obiekt pass jest definiowany przez aplikację serwera, ale nie zwraca żadnego wyjścia. Następnie przekształcisz kartę w link Dodaj do Portfela Google.

6. Tworzenie przycisku „Dodaj do Portfela Google”

Ostatnim krokiem jest utworzenie podpisanego tokena JWT i zwrócenie linku, który można użyć w przycisku Dodaj do Portfela Google. Gdy użytkownik kliknie przycisk, zostanie poproszony o zapisanie karty w portfelu.

1. Utwórz roszczenia JWT, zakoduj je za pomocą klucza prywatnego konta usługi i zwróć przycisk Dodaj do Portfela Google z wbudowanym 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>`);
   

2. Załaduj ponownie aplikację w przeglądarce
3. Wpisz swój adres e-mail w formularzu i kliknij Utwórz kartę.
4. Gdy pojawi się przycisk, wybierz Dodaj do Portfela Google.

Jeśli konto wydawcy jest w trybie demonstracyjnym, możesz wydawać karty tylko dla użytkowników testowych. Jeśli wpiszesz inny adres e-mail, nie będzie można dodać karty do Portfela.

7. Gratulacje

Gratulacje! Udało Ci się zintegrować interfejs Google Wallet API w internecie.

Więcej informacji

Zapoznaj się z pełną integracją w repozytorium GitHub google-pay/wallet-web-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.

Więcej informacji znajdziesz w wymaganiach wstępnych interfejsu Web API.