Prawie wszystkie karty, które możesz wydać użytkownikowi końcowemu, aby zapisał je w Portfelu Google, składają się z 2 elementów: klasy karty i obiektu karty. Za każdym razem, gdy wydajesz dokument użytkownikowi, potrzebujesz instancji klasy dokumentów i obiektu dokumentów. Informują one Google Wallet API, jaki typ dokumentu ma zostać utworzony, oraz zawierają szczegóły, które mają być wyświetlane na dokumencie, np. wartość karty podarunkowej lub imię i nazwisko posiadacza biletu.
Google Wallet API udostępnia predefiniowany zestaw klas i obiektów kart, których instancje możesz tworzyć, a następnie używać do tworzenia kart wydawanych użytkownikom, takich jak GiftCardClass i GiftCardObject, GenericClass i GenericObject oraz inne.
Każda instancja klasy i obiektu kart jest zdefiniowana jako obiekt JSON, który ma zestaw wymaganych i opcjonalnych właściwości odpowiadających konkretnemu przypadkowi użycia przeznaczonemu dla danego typu karty.
Klasy kart niepłatniczych
Klasa kart to udostępniony szablon, który służy do tworzenia co najmniej jednej karty, którą wydasz użytkownikom. Klasa kart definiuje wspólny zestaw właściwości, które będą uwzględniane we wszystkich kartach, które się do niej odwołują.
Na przykład poniższy przykład EventTicketClass definiuje pola wspólne dla wszystkich wydanych biletów na nadchodzące wydarzenie(miejsce, nazwa wydarzenia, wydawca, data i godzina).
{
"id": "ISSUER_ID.EVENT_CLASS_ID",
"issuerName": "[TEST ONLY] Heraldic Event",
"localizedIssuerName": {
"defaultValue": {
"language": "en-US",
"value": "[TEST ONLY] Heraldic Event"
}
},
"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"
}
Każda instancja klasy kart wymaga właściwości id, którą określasz. Ten identyfikator klasy
jest unikalnym identyfikatorem, do którego będziesz się odwoływać za każdym razem, gdy użyjesz go do utworzenia nowej instancji obiektu karty.
Obiekty przekazywane
Instancja klasy kart określa zestaw wspólnych właściwości, które mają być używane w co najmniej jednej karcie, a obiekt karty określa unikalne szczegóły konkretnej karty wydanej dla konkretnego użytkownika.
Na przykład gdy za pomocą interfejsu Google Wallet API tworzona jest karta wstępu na wydarzenie, instancja EventTicketObject
zawiera właściwości miejsca przypisanego do tej karty, ponieważ wartości te będą unikalne dla każdej wydanej karty.
{
"id": "ISSUER_ID.OBJECT_ID",
"classId": "ISSUER_ID.EVENT_CLASS_ID",
"state": "ACTIVE",
"seatInfo": {
"seat": {
"defaultValue": {
"language": "en-us",
"value": "9"
}
},
"row": {
"defaultValue": {
"language": "en-us",
"value": "L"
}
},
"section": {
"defaultValue": {
"language": "en-us",
"value": "45"
}
},
"gate": {
"defaultValue": {
"language": "en-us",
"value": "7C"
}
}
},
"barcode": {
"type": "BARCODE_TYPE_UNSPECIFIED",
"value": "BARCODE_VALUE",
"alternateText": ""
}
}
Każde wystąpienie obiektu karty wymaga właściwości id, którą określasz. Ten identyfikator obiektu
pełni funkcję unikalnego identyfikatora, do którego będziesz się odwoływać podczas wydawania karty użytkownikowi.
Współpraca klas kart z obiektami kart
Obiekty kart muszą rozszerzać instancję klasy kart przez odwoływanie się do jej identyfikatora lub przez uwzględnienie pełnej definicji klasy kart. Ta relacja między klasą karty a instancją obiektu karty oznacza, że możesz ustawiać i aktualizować właściwości wspólne dla wszystkich wydanych kart za pomocą instancji klasy karty oraz właściwości unikalne dla poszczególnych kart w instancji obiektu karty.
Na przykład poniższy schemat prostej karty biletu na wydarzenie pokazuje, jak pola zdefiniowane w sekcji wspólnej EventTicketClass i pola dotyczące konkretnego biletu zdefiniowane w sekcji EventTicketObject łączą się, aby utworzyć ostateczną wydaną kartę. Zwróć uwagę, jak identyfikator klasy karty jest przywoływany we właściwości classId obiektu karty.
Zmiany wprowadzone w instancji klasy karty zostaną natychmiast rozpowszechnione we wszystkich instancjach obiektu karty, które się do niej odwołują. Wszelkie zmiany wprowadzone w instancji klasy karty zostaną odzwierciedlone na karcie w aplikacji Portfel Google przy następnej synchronizacji.
Dodawanie karty lub biletu do Portfela Google użytkownika
Aby dodać kartę do Portfela Google użytkownika, musisz utworzyć token sieciowy JSON (JWT), który zawiera deklaracje dotyczące instancji obiektu karty lub biletu, które zostaną zapisane w Portfelu Google użytkownika. Najważniejszy jest identyfikator obiektu instancji obiektu karty lub biletu, który wydajesz użytkownikowi. Token JWT jest następnie dostarczany do użytkownika za pomocą przycisku Dodaj do Portfela Google lub linku Dodaj do Portfela Google.
Gdy użytkownik kliknie przycisk lub link, aby dodać wydany dokument do Portfela Google, link do instancji obiektu dokumentów zakodowanej w tokenie JWT zostanie połączony z kontem Google tego użytkownika. Oznacza to, że gdy użytkownik kliknie przycisk jeszcze raz, link do obiektu karty już istnieje, więc duplikaty nie zostaną dodane do portfela użytkownika.
Jeśli użytkownik usunie kartę z aplikacji Portfel Google, odpowiednia instancja obiektu karty zostanie automatycznie odłączona od użytkownika, ale nie zostanie usunięta. Oznacza to, że użytkownik może ponownie kliknąć przycisk lub link Dodaj do Portfela Google, aby zapisać kartę bez konieczności tworzenia nowej instancji obiektu kart lub tokena JWT.