Proces tworzenia karty w Portfelu Google
Interfejs API Portfela Google udostępnia wstępnie zdefiniowany zestaw typów kart zoptymalizowanych pod kątem konkretnych przypadków użycia, takich jak karty podarunkowe, karty pokładowe czy bilety na wydarzenia. Istnieje też ogólny typ karty przeznaczony do sytuacji, w których określony typ karty jest niedostępny.
W tym artykule opisujemy podstawowe czynności, które należy wykonać, aby utworzyć i wystawić kartę za pomocą Google Wallet API. Opisane poniżej kroki można wykonać na kilka sposobów, ale ogólnie rzecz biorąc, wszystkie typy kart są tworzone w ramach tego samego podstawowego procesu programowania.
Szczegółową instrukcję tworzenia karty znajdziesz w przewodnikach dotyczących internetu, e-maili i SMS-ów lub aplikacji na Androida.
1. Utwórz klasę kart
Przeznaczenie
Klasa kart definiuje zestaw właściwości, które są wspólne dla wielu kart, podobnie jak szablon. Jeśli na przykład wydajesz bilety na wydarzenie, klasa kart zdefiniuje takie same pola we wszystkich biletach, takie jak nazwa, data i godzina wydarzenia.
Każdy wydany dokument musi odwoływać się do klasy kart. Do każdej utworzonej klasy karty musisz przypisać unikalny identyfikator, który będzie używany podczas tworzenia kart.
Jak to się robi
Klasa kart jest zdefiniowana w formacie JSON i można ją utworzyć za pomocą interfejsu API Portfela Google typu REST, pakietu SDK na Androida lub w konsoli biznesowej Portfela Google.
Pokaż przykładową klasę kart
{ "id": "ISSUER_ID.EVENT_CLASS_ID", "issuerName": "[TEST ONLY] Heraldic Event", "localizedIssuerName": { "defaultValue": { "language": "en-US", "value": "[TEST ONLY] Heraldic Event" } }, "logo": { "sourceUri": { "uri": "https://images.unsplash.com/photo-1475721027785-f74eccf877e2?ixlib=rb-4.0.3&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=660&h=660" }, "contentDescription": { "defaultValue": { "language": "en-US", "value": "LOGO_IMAGE_DESCRIPTION" } } }, "eventName": { "defaultValue": { "language": "en-US", "value": "Google Live" } }, "venue": { "name": { "defaultValue": { "language": "en-US", "value": "Shoreline Amphitheater" } }, "address": { "defaultValue": { "language": "en-US", "value": "ADDRESS_OF_THE_VENUE" } } }, "dateTime": { "start": "2023-04-12T11:30" }, "reviewStatus": "UNDER_REVIEW", "hexBackgroundColor": "#264750", "heroImage": { "sourceUri": { "uri": "https://images.unsplash.com/photo-1501281668745-f7f57925c3b4?ixlib=rb-4.0.3&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=1032&h=336" }, "contentDescription": { "defaultValue": { "language": "en-US", "value": "HERO_IMAGE_DESCRIPTION" } } } }
2. Tworzenie obiektu kart
Przeznaczenie
Obiekt kart definiuje właściwości unikalnej karty, która zostanie wydana konkretnemu użytkownikowi. Na przykład obiekt karty biletu na wydarzenie będzie definiować pola unikalne dla konkretnego biletu, takie jak numer miejsca lub kod QR tego biletu.
Po utworzeniu obiektu karty interfejs Google Wallet API przechowuje nową kartę i wiąże ją z Twoim kontem wydawcy. Ta karta zapisana jest kombinacją unikalnych właściwości obiektu z kartami i właściwości szablonu powiązanej klasy kart.
Każdemu obiektowi karty musisz też przypisać unikalny identyfikator, który posłuży do odwoływania się do niego podczas wystawiania karty.
Jak to się robi
Obiekt karty jest zdefiniowanym w formacie JSON i można go utworzyć za pomocą interfejsu API Portfela Google typu REST lub pakietu SDK na Androida.
Pokaż przykładowy obiekt z kartami
{ "id": "ISSUER_ID.OBJECT_ID", "classId": "ISSUER_ID.EVENT_CLASS_ID", "state": "ACTIVE", "seatInfo": { "seat": { "defaultValue": { "language": "en-us", "value": "5" } }, "row": { "defaultValue": { "language": "en-us", "value": "G" } }, "section": { "defaultValue": { "language": "en-us", "value": "40" } }, "gate": { "defaultValue": { "language": "en-us", "value": "3A" } } }, "barcode": { "type": "QR_CODE", "value": "BARCODE_VALUE", "alternateText": "" } }
3. Zakoduj kartę w tokenie sieciowym JSON (JWT)
Przeznaczenie
Aby wydać kartę użytkownikowi, obiekt klasy i kart musi być zakodowany w tokenie sieciowym JSON (JWT). Format JWT jest wspólnym i otwartym standardem do przedstawiania roszczeń między 2 stronami. W przypadku wystawiania kart za pomocą interfejsu Google Wallet API, tokeny JWT są używane do wysłania deklaracji, że użytkownik ma prawo dostępu do określonej karty powiązanej z Twoim kontem wydawcy.
Gdy token JWT jest wysyłany do interfejsu Google Wallet API, zakodowane dane służą do identyfikowania konkretnej karty i wydania jej użytkownikowi. Jeśli karta została już wystawiona, dane te pozwalają interfejsowi Google Wallet API na zidentyfikowanie, że karta jest duplikatem, dzięki czemu nie zostanie ona dodana do Portfela Google użytkownika więcej niż raz.
Jak to się robi
Tokeny JWT są zdefiniowane w formacie JSON na podstawie specyfikacji JWT. Aby zdefiniować token JWT na potrzeby wydania karty przy użyciu interfejsu Google Wallet API, podaj we właściwości payload
tego tokena informacje o karcie.
Pokaż przykładowy token JWT
{ "iss": "issuer@example.com", "aud": "google", "typ": "savetowallet", "iat": 1696877738, "origins": [ "www.example.com" ], "payload": { "eventTicketObjects": [ { "id": "ISSUER_ID.LOYALTY_OBJECT_SUFFIX" } ] } }
4. Podpisywanie tokena JWT za pomocą danych logowania
Przeznaczenie
Wszystkie tokeny JWT wysyłane do interfejsu API Portfela Google w celu wystawienia karty muszą być podpisane za pomocą danych logowania podanych wcześniej w konsoli biznesowej Portfela Google. Podpisywanie używa Twoich danych logowania do szyfrowania tokena JWT, dzięki czemu karty pozostają bezpieczne, a interfejs API Portfela Google może uwierzytelniać, czy zakodowane w niej dane karty są prawidłowe i powiązane z Twoim kontem wydawcy.
Jak to się robi
Biblioteki klienta Portfela Google i pakiet SDK Androida zapewniają wygodne metody podpisywania tokenów JWT. Istnieją również liczne biblioteki open source, które obsługują złożoność podpisywania kodu.
Osoby używające interfejsu API typu REST Portfela Google do wystawiania kart token JWT jest podpisany kluczem konta usługi Google Cloud. W przypadku pakietu SDK Portfela Google na Androida pakiet SDK automatycznie obsługuje podpisywanie JWT za pomocą odcisku cyfrowego SHA-1 certyfikatu podpisywania aplikacji.
Aby chronić swoje dane logowania, tokeny JWT powinny być podpisane tylko na serwerze lub za pomocą pakietu SDK Portfela Google na Androida w aplikacji.
Pokaż przykładowy kod podpisywania
Java
// Create the JWT as a HashMap object HashMapclaims = new HashMap (); claims.put("iss", ((ServiceAccountCredentials) credentials).getClientEmail()); claims.put("aud", "google"); claims.put("origins", Arrays.asList("www.example.com")); claims.put("typ", "savetowallet"); // Create the Google Wallet payload and add to the JWT HashMap payload = new HashMap (); payload.put("eventTicketObjects", Arrays.asList(newObject)); claims.put("payload", payload); // Google Cloud service account credentials are used to sign the JWT Algorithm algorithm = Algorithm.RSA256( null, (RSAPrivateKey) ((ServiceAccountCredentials) credentials).getPrivateKey()); String token = JWT.create().withPayload(claims).sign(algorithm);
Node.JS
// Create the JWT claims let claims = { iss: this.credentials.client_email, aud: 'google', origins: ['www.example.com'], typ: 'savetowallet', payload: { eventTicketObjects: [newObject] }, }; // The service account credentials are used to sign the JWT let token = jwt.sign(claims, this.credentials.private_key, { algorithm: 'RS256' });
Python
# Create the JWT claims claims = { 'iss': self.credentials.service_account_email, 'aud': 'google', 'origins': ['www.example.com'], 'typ': 'savetowallet', 'payload': { # The listed classes and objects will be created 'eventTicketObjects': [new_object] } } # The service account credentials are used to sign the JWT signer = crypt.RSASigner.from_service_account_file(self.key_file_path) token = jwt.encode(signer, claims).decode('utf-8')
5. Wydaj kartę, używając przycisku lub linku „Dodaj do Portfela Google”
Przeznaczenie
Gdy utworzysz podpisany token JWT, możesz wydać kartę użytkownikowi Portfela Google. Użytkownik ma do dyspozycji przycisk lub link „Dodaj do Portfela Google”. Gdy użytkownik kliknie przycisk lub hiperlink, podpisany token JWT jest wysyłany do interfejsu Google Wallet API, który odszyfrowuje go przy użyciu zapisanych danych logowania. Po uwierzytelnieniu podpisu JWT użytkownik otrzymuje kartę, którą może zapisać w Portfelu Google.
Jak to się robi
Aby utworzyć przycisk „Dodaj do Portfela Google” dla aplikacji na Androida, skorzystaj z pakietu SDK Portfela Google na Androida, który udostępnia metody jego generowania. Na wszystkich innych platformach, w tym w internecie, e-mailach i SMS-ach, utwórz hiperlink w formacie https://pay.google.com/gp/v/save/<signed_jwt>
. Jeśli jest to możliwe, najlepiej dostarczyć użytkownikowi ten link jako przycisk „Dodaj do Portfela Google”.
Więcej informacji o korzystaniu z przycisku „Dodaj do Portfela Google” znajdziesz we wskazówkach dotyczących marki interfejsu API Portfela Google
Pokaż przykładowy kod
Hiperlink
https://pay.google.com/gp/v/save/<signed_jwt>
Android SDK
private lateinit var walletClient: PayClient private val addToGoogleWalletRequestCode = 1000 private lateinit var addToGoogleWalletButton: View override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) walletClient = Pay.getClient(this) addToGoogleWalletButton.setOnClickListener { walletClient.savePasses(newObjectJson, this, addToGoogleWalletRequestCode) } }
6. Wyświetl w Portfelu Google
Gdy użytkownik zapisze wydaną kartę, pojawi się ona w aplikacji Portfel Google wraz ze wszystkimi innymi zapisanymi przez niego kartami.
Tworzenie obiektów kart i klas kart w tokenie JWT
Klasy i obiekty kart można tworzyć z wyprzedzeniem za pomocą interfejsu API Portfela Google typu REST lub pakietu SDK na Androida. Po utworzeniu są one używane do wystawiania kart, podając ich identyfikator.
Klasy i karty kart możesz też tworzyć „w odpowiedniej chwili”, umieszczając ich elementy JSON bezpośrednio w tokenie JWT, który służy do wydania karty użytkownikowi. W tej metodzie obiekty kart i kart są tworzone przez interfejs Google Wallet API, gdy podpisany token JWT zostanie wysłany za pomocą przycisku lub linku „Dodaj do Portfela Google”.
Poniżej znajduje się przykład tokena JWT z nową klasą kart i obiektem kart zdefiniowanym za pomocą właściwości payload.eventTicketClasses
i payload.eventTicketObjects
. Zwróć uwagę, że te właściwości są tablicami, więc mogą akceptować co najmniej jedną klasę lub obiekt kart. Możesz też podać w tokenie JWT tylko nowy obiekt kart, który odwołuje się do istniejącej klasy kart, używając identyfikatora.
Pokaż przykładowy token JWT
{ "iss": "issuer@example.com", "aud": "google", "typ": "savetowallet", "iat": 1696877738, "origins": [ "www.example.com" ], "payload": { "eventTicketClasses": [{ "id": "ISSUER_ID.EVENT_CLASS_ID", "issuerName": "[TEST ONLY] Heraldic Event", "localizedIssuerName": { "defaultValue": { "language": "en-US", "value": "[TEST ONLY] Heraldic Event" } }, "logo": { "sourceUri": { "uri": "https://images.unsplash.com/photo-1475721027785-f74eccf877e2?ixlib=rb-4.0.3&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=660&h=660" }, "contentDescription": { "defaultValue": { "language": "en-US", "value": "LOGO_IMAGE_DESCRIPTION" } } }, "eventName": { "defaultValue": { "language": "en-US", "value": "Google Live" } }, "venue": { "name": { "defaultValue": { "language": "en-US", "value": "Shoreline Amphitheater" } }, "address": { "defaultValue": { "language": "en-US", "value": "ADDRESS_OF_THE_VENUE" } } }, "dateTime": { "start": "2023-04-12T11:30" }, "reviewStatus": "UNDER_REVIEW", "hexBackgroundColor": "#264750", "heroImage": { "sourceUri": { "uri": "https://images.unsplash.com/photo-1501281668745-f7f57925c3b4?ixlib=rb-4.0.3&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=1032&h=336" }, "contentDescription": { "defaultValue": { "language": "en-US", "value": "HERO_IMAGE_DESCRIPTION" } } } }], "eventTicketObjects": [{ "id": "ISSUER_ID.OBJECT_ID", "classId": "ISSUER_ID.EVENT_CLASS_ID", "state": "ACTIVE", "seatInfo": { "seat": { "defaultValue": { "language": "en-us", "value": "5" } }, "row": { "defaultValue": { "language": "en-us", "value": "G" } }, "section": { "defaultValue": { "language": "en-us", "value": "40" } }, "gate": { "defaultValue": { "language": "en-us", "value": "3A" } } }, "barcode": { "type": "QR_CODE", "value": "BARCODE_VALUE", "alternateText": "" } }] } }