Prawie wszystkie karty, które możesz wydać użytkownikowi, aby zapisać je w swoim Portfelu Google, są definiowane przez 2 komponenty: klasę kart i obiekt kart. Za każdym razem, gdy wydajesz użytkownikowi kartę, konieczne jest wystąpienie zarówno klasy karty, jak i obiektu Pass Object. Informuje on interfejs Google Wallet API o typie karty do utworzenia, a także szczegóły, które mają być widoczne na karcie, takie jak wartość karty podarunkowej lub imię i nazwisko posiadacza biletu.
Interfejs Google Wallet API udostępnia wstępnie zdefiniowany zestaw klas i obiektów kart, których możesz używać do tworzenia wystąpień kart, które są wydawane dla użytkowników, takich jak GiftCardClass, GiftCardObject, GenericClass i GenericObject.
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
Klasa kart to udostępniany szablon służący do tworzenia kart, które wystawiasz 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ższe wystąpienie obiektu EventTicketClass określa pola, które są wspólne dla wszystkich wystawionych biletów na nadchodzące wydarzenie(miejsce, nazwa wydarzenia, wydawca, data/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żde wystąpienie klasy kart wymaga określonej przez Ciebie właściwości id. Ten identyfikator klasy jest unikalnym identyfikatorem, do którego możesz się odwoływać podczas tworzenia nowej instancji obiektu karty.
Obiekty przesłane
Instancja klasy kart określa zbiór wspólnych właściwości, które mają być używane w co najmniej jednej karcie, obiekt karty określa unikalne szczegóły konkretnej karty wydanej konkretnemu użytkownikowi.
Jeśli na przykład za pomocą interfejsu Google Wallet API zostanie utworzony bilet na wydarzenie, instancja EventTicketObject będzie zawierać właściwości miejsca przypisanego do tego biletu, ponieważ wartości te będą unikalne dla każdego wystawionego biletu.
{
"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 kart wymaga określonej przez Ciebie właściwości id. Ten identyfikator obiektu działa jako unikalny identyfikator, do którego możesz się odwoływać, wystawiając kartę użytkownikowi.
Działanie klas kart z obiektami kart
Obiekty kart muszą rozszerzać instancję klasy kart, odwołując się do jej identyfikatora lub podając pełną definicję klasy kart. Ta relacja między klasą kart a instancją obiektu kart oznacza, że możesz ustawiać i aktualizować właściwości, które są wspólne dla wszystkich wystawionych kart za pomocą instancji klasy kart oraz właściwości unikalne dla poszczególnych kart w instancji obiektów Pass.
Na przykład ten schemat prostego biletu na wydarzenie pokazuje, jak pola zdefiniowane we wspólnym EventTicketClass oraz pola konkretnego biletu zdefiniowanego w EventTicketObject są łączone w celu utworzenia ostatecznej wersji karty. Zwróć uwagę na to, jak odwołuje się do identyfikatora klasy Pass we właściwości classId obiektu Pass.
Zmiany wprowadzone w instancji klasy kart zostaną natychmiast zastosowane we wszystkich instancjach obiektów kart, które się do niej odwołują. Przy następnej synchronizacji użytkownicy zobaczą w aplikacji Portfel Google wszystkie zmiany wprowadzone w instancji klasy kart widoczne na karcie.
Dodawanie karty do Portfela Google użytkownika
Aby dodać kartę do Portfela Google użytkownika, musisz utworzyć token sieciowy JSON (JWT) zawierający deklaracje na temat instancji obiektu kart zapisane przez Ciebie (wydawcy) i zapisane w Portfelu Google użytkownika. A przede wszystkim identyfikator obiektu instancji obiektu karty wystawianego 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 umożliwiający dodanie wydanej karty do Portfela Google, wystąpienie obiektu karty zakodowane w tokenie JWT zostanie połączone z kontem Google tego użytkownika. Oznacza to, że gdy użytkownik ponownie kliknie przycisk, powstanie już link do obiektu Karty, 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 karty lub tokena JWT.