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.
![](https://developers-dot-devsite-v2-prod.appspot.com/static/wallet/images/ticket-class.png?authuser=9&%3Bhl=pl&hl=pl)
1. Utwórz klasę kart
Do czego służy
Klasa kart definiuje zbiór właściwości, które są wspólne dla wielu kart (podobnie jak w przypadku szablonu). Jeśli np. wystawiasz bilety na wydarzenie, klasa kart definiuje pola, które są takie same dla wszystkich biletów, np. nazwa, data i godzina wydarzenia.
Każdy wydanie karty musi odwoływać się do klasy kart. Do każdej utworzonej klasy kart musisz też przypisać unikalny identyfikator, który będzie służyć do odwoływania się do niej podczas tworzenia kart.
Jak to się robi
Klasa kart jest zdefiniowana w formacie JSON i można ją utworzyć za pomocą interfejsu API REST Portfela Google, pakietu Android SDK lub w konsoli Business Console w Portfelu 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" } } } }
![](https://developers-dot-devsite-v2-prod.appspot.com/static/wallet/images/ticket-object.png?authuser=9&%3Bhl=pl&hl=pl)
2. Tworzenie obiektu kart
Do czego służy
Obiekt kart określa właściwości unikalnej karty, która zostanie wydana konkretnemu użytkownikowi. Na przykład obiekt Karty dla biletu na wydarzenie definiuje pola unikalne dla konkretnego biletu, takie jak numer miejsca lub kod QR biletu.
Po utworzeniu obiektu kart Google Wallet API przechowuje nową kartę i powiązuje ją z Twoim kontem wydawcy. Ta przechowywana karta stanowi połączenie unikalnych właściwości obiektu Karty i właściwości szablonu powiązanej klasy kart.
Do każdego obiektu kart musisz też przypisać unikalny identyfikator, który będzie używany do odwoływania się do niego podczas wystawiania karty.
Jak to się robi
Obiekt kart jest zdefiniowany w formacie JSON i można go utworzyć za pomocą interfejsu API REST Portfela Google lub pakietu Android SDK.
Pokaż przykładowe karty
{ "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": "" } }
![](https://developers-dot-devsite-v2-prod.appspot.com/static/wallet/images/ticket-jwt.png?authuser=9&%3Bhl=pl&hl=pl)
3. Zakoduj kartę w tokenie sieciowym JSON (JWT)
Do czego służy
Aby przekazać kartę użytkownikowi, obiekt klasy kart i karty musi być zakodowany w tokenie sieciowym JSON (JWT). Format JWT to powszechny i otwarty standard służący do przedstawiania roszczeń między dwiema stronami. W przypadku wystawiania kart za pomocą interfejsu API Portfela Google tokeny JWT służą do wysyłania deklaracji, że użytkownik ma prawo dostępu do konkretnej karty powiązanej z Twoim kontem wydawcy.
Gdy do interfejsu API Portfela Google jest wysyłany token JWT, zakodowane dane służą do identyfikacji konkretnej karty i wydania jej użytkownikowi. Jeśli karta została już wydana, te dane umożliwiają też interfejsowi Google Wallet API rozpoznanie, że karta jest duplikatem, dzięki czemu nie zostanie 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 do wystawienia karty za pomocą interfejsu Google Wallet API, musisz podać informacje o karcie, którą chcesz wydać, we właściwości payload
tokena JWT.
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" } ] } }
![](https://developers-dot-devsite-v2-prod.appspot.com/static/wallet/images/ticket-jwt-signed.png?authuser=9&%3Bhl=pl&hl=pl)
4. Podpisywanie tokena JWT za pomocą danych logowania
Do czego służy
Wszystkie tokeny JWT wysyłane do interfejsu API Portfela Google w celu wydania karty muszą być podpisane danymi logowania podanymi wcześniej w Google Wallet Business Console. Podczas podpisywania używane są Twoje dane logowania, aby szyfrować token JWT, aby Twoje karty były bezpieczne, i umożliwić interfejsowi Google Wallet API uwierzytelnianie, czy zakodowane w nim szczegóły karty są prawidłowe i powiązane z Twoim kontem wydawcy.
Jak to się robi
Biblioteki klienta Portfela Google oraz pakiet Android SDK zapewniają wygodne metody podpisywania tokenów JWT. Dostępnych jest też wiele bibliotek open source, które obsługują złożoność podpisywania kodu.
W przypadku użytkowników korzystających z interfejsu API typu REST Portfela Google do wystawiania kart token JWT jest podpisany za pomocą klucza konta usługi Google Cloud. W przypadku użytkowników korzystających z pakietu SDK Portfela Google na Androida pakiet SDK automatycznie obsługuje podpisywanie tokena JWT za pomocą odcisku cyfrowego SHA-1 certyfikatu podpisywania aplikacji.
Aby chronić Twoje dane logowania, tokeny JWT należy podpisywać tylko na serwerze lub w aplikacji za pomocą pakietu SDK Portfela Google na Androida.
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')
![](https://developers-dot-devsite-v2-prod.appspot.com/static/wallet/images/ticket-add-to-wallet.png?authuser=9&%3Bhl=pl&hl=pl)
5. Wydaj kartę, używając przycisku lub linku „Dodaj do Portfela Google”
Do czego służy
Po utworzeniu podpisanego tokena JWT możesz przesłać kartę użytkownikowi Portfela Google. Aby to zrobić, wyświetl użytkownikowi opcję „Dodaj do Portfela Google”. przycisk lub link. Gdy użytkownik kliknie przycisk lub hiperlink, podpisany token JWT zostanie wysłany do interfejsu Google Wallet API, który odszyfruje go przy użyciu zapisanych danych logowania. Po uwierzytelnieniu podpisu JWT użytkownik otrzyma kartę i zapisać ją w Portfelu Google.
Jak to się robi
Aby utworzyć opcję „Dodaj do Portfela Google” w przypadku aplikacji na Androida, użyj pakietu SDK Portfela Google na Androida, który udostępnia metodę generowania przycisku. Na wszystkich innych platformach, w tym w internecie, w e-mailach i wiadomościach tekstowych, utwórz hiperlink w formacie https://pay.google.com/gp/v/save/<signed_jwt>
. W miarę możliwości najlepiej dostarczyć użytkownikowi ten link jako „Dodaj do Portfela Google”. Przycisk
Więcej informacji o korzystaniu z opcji „Dodaj do Portfela Google” przycisk, zobacz wskazówki dotyczące marki dotyczące interfejsu Google Wallet API.
Pokaż przykładowy kod
Hiperlink
https://pay.google.com/gp/v/save/<signed_jwt>
Pakiet SDK do Androida
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) } }
![](https://developers-dot-devsite-v2-prod.appspot.com/static/wallet/images/ticket-enduser-view.png?authuser=9&%3Bhl=pl&hl=pl)
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
Obiekty klas i kart kart można utworzyć z wyprzedzeniem za pomocą interfejsu API typu REST Portfela Google lub pakietu SDK na Androida. Następnie są używane do wystawiania kart, podając ich identyfikatory.
Możesz też utworzyć klasy kart i obiekty kart „w odpowiednim momencie” umieszczając plik JSON bezpośrednio w tokenie JWT, który jest używany do wydania karty użytkownikowi. W tej metodzie klasy i obiekty kart są tworzone przez interfejs Google Wallet API, gdy podpisany token JWT jest wysyłany przy użyciu opcji „Dodaj do Portfela Google”. przycisk lub link.
Na przykład poniżej pokazujemy token JWT z nowym obiektem klasy i karty 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ą przyjmować jedną lub więcej klas lub obiektów Pass. Możesz też podać w tokenie JWT tylko nowy obiekt kart, który odwołuje się do istniejącej klasy kart za pomocą 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": "" } }] } }