Typowe przepływy interfejsu API

Poniższy diagram przedstawia typowy przepływ komunikacji podczas wstawiania klasy, zapisu obiektu i aktualizacji obiektu. Wdrożenie wszystkich działań między serwerem, przeglądarką i Google Pay API for Passes jest Twoim zadaniem. Poniższy diagram przedstawia jako przykład kartę lojalnościową, ale pozostałe karty mają podobny przepływ.

Rysunek 1. Diagram przepływu interfejsu API.

Typowy przepływ interfejsu API w przyciskach JS i internetowych linkach JWT

Poniżej przedstawiono bardziej szczegółowy opis tego samego procesu co na rysunku 1. Obejmuje on typowy przepływ interfejsu API w przyciskach JavaScript (JS) i tokenach sieciowych JSON (JWT):

1. Wydawca karty lojalnościowej tworzy LoyaltyClass.
1. Serwer określa LoyaltyClass.
2. Serwer wykonuje żądanie POST, aby wstawić LoyaltyClass na serwerze Google Pay API for Passes.
Uwaga: jeśli używasz przycisku JS, ten krok nie jest potrzebny. Nie ma limitu znaków, więc nie trzeba wstawiać wcześniej klasy. Warto to jednak zrobić, aby móc używać klasy wiele razy. Jest to często najlepsza metoda obsługi kart lojalnościowych.
2. Serwer używa usługi, która tworzy token JWT dla LoyaltyObject w określonej LoyaltyClass. Ten obiekt reprezentuje kartę lojalnościową użytkownika.
1. Serwer renderuje przycisk Zapisz w Google Pay za pomocą tokena JWT:
• W witrynach użyj naszego przycisku w JavaScript.
• W e-mailach, SMS-ach i aplikacjach użyj linku JWT z przyciskiem Zapisz w Google Pay.
3. Użytkownik klika lub naciska Zapisz w Google Pay w witrynie, e-mailu, aplikacji lub SMS-ie wydawcy karty lojalnościowej.
1. Użytkownik trafia na stronę docelową, na której może zapisać obiekt LoyaltyClass. Obiekt do zapisania jest renderowany na stronie docelowej zgodnie z tokenem JWT. Jeśli użytkownik naciśnie przycisk w aplikacji, wyświetli się prośba o zapisanie w aplikacji Google Pay.
2. Użytkownik klika Zapisz w Google Pay w usłudze wydawcy, aby zapisać LoyaltyObject.
3. LoyaltyObject jest wstawiany na serwerze Google i przekazywany do aplikacji Google Pay. LoyaltyObject jest nazywany ofertą Loyalty Pass.
Uwaga: gdy zapis przez użytkownika lub żądanie REST serwera wstawi LoyaltyClass lub LoyaltyObject po raz pierwszy, następne tokeny JWT z tym samym classID lub objectID będą renderować to, co już zostało wstawione na serwerze Google. Jeśli zmienisz informacje w tokenie JWT z obecnym classID lub objectID, zmiana nie zostanie zaktualizowana. Informacje o tym, jak aktualizować obecne klasy i obiekty, znajdziesz w kroku 4.
4. Wydawca karty aktualizuje dane karty:
1. Wydawca karty lojalnościowej wykonuje żądanie GET dotyczące LoyaltyObject przy użyciu Object.id.
2. Wydawca karty lojalnościowej aktualizuje LoyaltyObject.
3. Wydawca karty lojalnościowej wykonuje żądanie PUT lub PATCH, aby wstawić zaktualizowany LoyaltyObject na serwerze Google Pay API for Passes.
4. LoyaltyObject jest przekazywany do aplikacji Google Pay.

Skrócona odmiana tokena JWT

Ze względu na limity długości w przeglądarkach tokeny JWT w linkach internetowych nie mogą być dłuższe niż 1800 znaków. Jeśli jest to problem, być może warto wstawić klasę i obiekt wcześniej. Wtedy token JWT będzie musiał zawierać tylko pole identyfikatora obiektu.

Uwaga: klasę i obiekt wstaw dopiero wtedy, gdy użytkownik pokaże, że chce zapisać kartę w Google Pay. Aby zainicjować przepływ zapisywania skróconego tokena JWT, zalecamy zdefiniowanie własnego linku zapisu.

Poniższy diagram przedstawia przepływ interfejsu API, który ma na celu dodanie przycisku Zapisz w Google Pay do e-maila lub SMS-a.

Rysunek 2. Diagram skróconego tokena JWT.

Przepływ interfejsu API z żądaniem POST tokena JWT

Często trudno jest wdrożyć backend niezbędny do utworzenia i wstawienia klasy przed zapisem obiektu, ale tokeny JWT zwykle przekraczają limit 1800 znaków. Ta metoda najlepiej sprawdza się przy biletach na wydarzenia i kartach pokładowych, ponieważ dla nich można tworzyć wiele klas.

Uwaga: metody żądania POST tokena JWT możesz użyć przy zapisie z aplikacji, ale nie możesz jej użyć w wiadomości SMS ani e-mailu, ponieważ używa wywołania POST.

Oto przykładowy przepływ z klasą lotu:

1. Serwer tworzy token JWT dla FlightObject i FlightClass. Oba są zdefiniowane w kodzie JSON, a FlightObject odwołuje się do FlightClass.
2. Token JWT jest wysyłany z serwera do aplikacji klienckiej, w której wyświetla się przycisk Zapisz w Google Pay. Przycisk musi być zgodny ze wskazówkami dotyczącymi marki.
3. Użytkownik klika przycisk Zapisz w Google Pay w aplikacji klienckiej.
   1. Wysyłane jest żądanie POST do punktu końcowego tokena JWT. Powoduje to wstawienie identyfikatorów klas i obiektów. Jeśli identyfikatory klas lub obiektów w tokenie JWT są już obecne w systemie, nie zostaną wstawione ponownie. Informacje o tym, jak aktualizować obecne klasy i obiekty, znajdziesz w dokumentacji API. Jeśli zostały już one wstawione, wystąpi błąd.
   2. Zwrócona odpowiedź identyfikatora URI otwiera się u użytkownika, dzięki czemu może on zapisać kartę. Ten identyfikator jest ważny tylko przez tydzień po zwróceniu.

Aby wdrożyć interfejs API, przeczytaj artykuł Użycie metody żądania POST tokena JWT.

Rysunek 3. Diagram żądania POST tokena JWT.

Na rysunku 3 nie ma strzałek między Twoim serwerem i serwerem Google w przepływie zapisywania. To podstawowa różnica między żądaniem POST tokena JWT a linkiem JWT i metodą intencji. Zalecamy jednak wdrożenie aktualizacji kart z użyciem komunikacji między serwerami.