Przypadki użycia

Wybierz jedną z poniższych kategorii kart, by dowiedzieć się, jak z niej korzystać.

Karty pokładowe Bilety na wydarzenia Karty podarunkowe Programy lojalnościowe Oferty specjalne Bilety na przejazdy

---

Google Pay API for Passes umożliwia interakcję z użytkownikami za pomocą lotniczych kart pokładowych. Pojęcia omawiane w tym przewodniku pomagają lepiej poznać możliwości zapisanych lotniczych kart pokładowych.

Aby wdrożyć karty pokładowe, użyj metody żądania POST tokena JWT lub skróconych linków JWT – te metody wstawiają wcześniej klasy i obiekty.

FlightClasses i FlightObjects

Tak jak w innych kategoriach w Google Pay API for Passes, dane kart pokładowych są przechowywane w 2 strukturach: FlightObject i FlightClass. Ten przewodnik wyjaśnia, jak używać tych struktur danych, aby obsługiwały Twoje karty pokładowe.

FlightClass

FlightClass zawiera wspólne dane wszystkich pasażerów lub podzbiorów pasażerów konkretnego lotu w określonym dniu o określonej godzinie. Są to na przykład: przewoźnik, miejsce wylotu, cel podróży, numer lotu i czas wylotu. Wszyscy pasażerowie lotu mają na swoich kartach pokładowych takie same dane.

FlightClass może też zawierać wspólne dane podzbioru pasażerów w tym samym samolocie. Można na przykład utworzyć 3 różne struktury FlightClass dla 1. klasy, klasy biznesowej i klasy ekonomicznej. Dzięki temu w razie potrzeby w poszczególnych podzbiorach można użyć różnych pól. W tym przypadku wszystkie 3 klasy dotyczą tego samego samolotu, tej samej trasy lotu oraz tej samej daty i godziny.

FlightObject

FlightObject reprezentuje każdego pasażera w danym samolocie w określonym czasie. FlightObject może na przykład zawierać imię i nazwisko pasażera, numer miejsca oraz kod kreskowy karty pokładowej. Te dane różnią się w zależności od karty pokładowej pasażera.

Zasoby z obiektu FlightObject są zapisywane w aplikacji Google Pay użytkownika.

Obsługiwane kraje

Kraje obsługujące lotnicze karty pokładowe znajdziesz na liście obsługiwanych krajów. Zalecamy ograniczenie miejsca, w którym jest wyświetlany przycisk Zapisz w Google Pay, zależnie od tego, gdzie użytkownik kupił bilet.

Przypadki użycia

Poniższe przypadki użycia są dostępne tylko w kategorii lotniczych kart pokładowych:

• Aktualizacja kart
• Zapis trasy lotu z kilkoma etapami
• Tworzenie przycisku do zapisywania wielu kart
• Grupowanie wielu kart pokładowych
• Odbiór powiadomień o nadchodzących lotach
• Odbiór powiadomień o aktualizacjach lotów
• Obsługa kart, które straciły ważność
• Łączenie z zapisaną kartą
• Odłączanie od zapisanej karty

Uwaga: wszystkie kategorie kart mają takie same podstawowe funkcje. Więcej informacji znajdziesz w opisie funkcji Zapisywanie kart w Google Pay, w instrukcjach wykorzystywania kart w Google Pay i wskazówkach na temat angażowania użytkowników za pomocą Google Pay.

Aktualizacja kart

Jeśli po utworzeniu karty coś w niej zmieniono, użyj interfejsu API REST, aby przekazać te zmiany do użytkowników. Jeśli zmiany dotyczą tylko klas, możesz także skorzystać z Google Pay Merchant Center. Aktualizacje kart to ważna metoda angażowania użytkowników.

Aby zaktualizować pola wszystkich kart pokładowych na określony lot (na przykład po zmianie szacowanego czasu wylotu), wystarczy wykonać wywołanie update lub patch w FlightClass albo użyć Google Pay Merchant Center. Google przekaże te informacje do wszystkich obiektów FlightObject powiązanych ze zaktualizowaną klasą FlightClass. Dotyczy to wszystkich pól określonych na poziomie FlightClass.

Aby zaktualizować pojedynczą kartę (na przykład w przypadku zmiany numeru miejsca 1 pasażera), musisz wykonać wywołanie update lub patch w 1 obiekcie FlightObject. Dotyczy to wszystkich pól określonych na poziomie FlightObject.

Uwaga: więcej informacji na temat tych struktur danych można znaleźć w sekcjach FlightClass i FlightObject.

Uwaga: dokładniejszy opis różnicy między wywołaniem update a patch znajdziesz w opisie wywołania Patch (częściowa aktualizacja).

Każda logika wywołania update powinna rozpoczynać się od żądania GET pobierającego klasę lub obiekt. Dzięki temu zostanie użyta najnowsza wersja klasy lub obiektu. Pominięte pola są opróżniane.

Zwykle użycie wywołania patch jest dużo bezpieczniejsze, gdy podajesz tylko dane pól, które chcesz zmienić. Pominięte pola nie są opróżniane. Należy jednak zachować szczególną ostrożność podczas modyfikowania tablic. Żądania poprawki z tablicami zastępują dotychczasową tablicę tą podaną przez Ciebie. Nie możesz zmieniać, dodawać ani usuwać elementów tablicy stopniowo.

Czasami możesz nie zauważyć, że nastąpiła zmiana, lub nie wiedzieć, kiedy należy aktywować żądanie update lub patch. W takich sytuacjach zaplanuj okresowo żądania update lub patch dla każdej klasy i każdego obiektu. Aby znaleźć wszystkie klasy danego konta wydawcy, wywołaj metodę FlightClass list. Aby znaleźć wszystkie obiekty danej klasy, wywołaj metodę FlightObject list.

Źródła danych aktualizacji lotów

Jeśli czas podany w class.localScheduledDepartureDateTime jest z ostatnich 24 godzin lub najbliższych 48 godzin, użytkownicy mogą zobaczyć kartę stanu lotu. Wtedy Google Pay może wyświetlać dane z Lotów Google lub informacje z karty w Google Pay. Użyte źródło zależy od poniższych czynników:

• Jeśli nie podano class.localEstimatedOrActualDepartureDateTime, używane są Loty Google. W tym przypadku każdy ustawiony class.flightStatus jest ignorowany.

  Jeśli na przykład lot jest opóźniony, użytkownicy zobaczą kartę na stronie głównej Google Pay z nowym czasem wylotu. Podobna karta opóźnienia wyświetla się w sekcji kart.

• Jeśli podano class.localEstimatedOrActualDepartureDateTime, ale nie class.flightStatus, do sprawdzenia, czy lot jest opóźniony, używany jest podany czas. Użytkownicy zobaczą stan lotu na karcie zgodnie z poniższymi zasadami:
  • Jeśli class.localEstimatedOrActualDepartureDateTime ma większą wartość niż class.localScheduledDepartureDateTime, użytkownicy zobaczą kartę, na której lot będzie oznaczony jako opóźniony.
  • Jeśli class.localEstimatedOrActualDepartureDateTime nie ma większej wartości niż class.localScheduledDepartureDateTime, użytkownicy zobaczą kartę z informacjami o locie, ale bez komunikatu o stanie.

Jeśli nie chcesz, aby źródłem informacji o lotach były Loty Google, podaj flightStatus, localScheduledDepartureDateTime i localEstimatedOrActualDepartureDateTime w klasie FlightClass. Karta zawiera tylko Twoje dane. Jeśli zamiast kodu IATA w FlightClass użyjesz kodu przewoźnika ICAO, Loty Google nie będą źródłem informacji o lotach.

Gdy pola ulegną zmianie, użytkownik otrzyma powiadomienia push o zmianach. Więcej informacji znajdziesz w sekcji Odbiór powiadomień o aktualizacjach lotów.

Zapis trasy lotu z wieloma etapami

Trasa lotu często nie prowadzi bezpośrednio do celu, tylko obejmuje kilka etapów. W takich sytuacjach linie lotnicze wydają 1 kartę pokładową na każdy etap podróży. Google Pay API for Passes naśladuje to zachowanie, używając 1 obiektu FlightObject na każdy etap.

Oznacza to, że jeśli jest 2 pasażerów, którzy lecą z lotniska SFO przez lotnisko LAX na lotnisko TPE, zostaną użyte 2 struktury FlightClass i 4 obiekty FlightObject:

	FlightClass A (z SFO na LAX – przewoźnik, numer lotu, czas wylotu)	FlightClass B (z LAX na TPE – przewoźnik, numer lotu, czas wylotu)
Pasażer Q	FlightObject: id_01	FlightObject: id_02
Pasażerka Z	FlightObject: id_03	FlightObject: id_04

Te pola odpowiadają fizycznym kartom pokładowym. Zarówno pasażer Q, jak i pasażerka Z mają po 2 papierowe karty pokładowe.

Tworzenie przycisku do zapisywania wielu kart

Jeśli użytkownik kupuje wiele kart i jest szansa, że zapisze każdą z nich w Google Pay, warto dać mu możliwość zapisu wielu obiektów 1 kliknięciem przycisku lub linku Zapisz w Google Pay. Obiekty lub klasy możesz zdefiniować przy podpisywaniu tokena sieciowego JSON (JWT).

Token JWT musi być w jednym z tych formatów:

• Używane są tylko wcześniej wstawione klasy i obiekty.
• Używane są tylko zasoby obiektów i klas, które mają pełne definicje w tokenie JWT.

Uwaga: token JWT musi być sformatowany w spójny sposób, aby uniknąć stosowania różnych formatów.

Przykład tworzenia przycisku dla wielu kart znajdziesz w sekcji Przycisk do zapisywania wielu pasażerów.

Więcej informacji o reprezentacji kart w UI znajdziesz w sekcji Grupowanie wielu kart pokładowych.

Grupowanie wielu kart pokładowych

Pewne funkcje działają różnie w grupach i pojedynczych obiektach. Są to na przykład powiadomienia o stanie lub układ wielu zapisanych biletów w interfejsie.

Obiekty FlightObject są uznawane za grupę tylko wtedy, gdy w każdym obiekcie wszystkie z tych właściwości są takie same:

• Identyfikator wydawcy (z Google Pay API for Passes Merchant Center)
• class.flightHeader.carrier.carrierIataCode
• class.flightHeader.flightNumber
• class.localScheduledDepartureDateTime
• object.reservationInfo.confirmationCode

Jeśli 2 obiekty FlightObject różnią się pod względem którejkolwiek z tych właściwości, nie można ich zgrupować.

Uwaga: niektóre z tych właściwości należą do klas, a niektóre do obiektów. Dzięki temu można FlightObject grupować obiekty różnych klas.

Odbiór powiadomień o nadchodzących lotach

Na 3 godziny przed lotem Google Pay wysyła do użytkownika powiadomienie. Godzina lotu jest określana przez class.localScheduledDepartureDateTime.

Jeśli użytkownik chce otrzymywać powiadomienia, muszą one być włączone. Aby potwierdzić włączenie powiadomień, wybierz Ustawienia > Powiadomienia i sprawdź, czy włączona jest opcja Najnowsze informacje dotyczące Twoich kart.

Powiadomienia wyświetlają się w obszarze powiadomień i na ekranie blokady, jeśli użytkownik ma włączone powiadomienia na ekranie blokady.

Powiadomienie ma taki format, którego nie można zmienić:

Boarding pass for your flight to class.destination.airportIataCode
Expand for more options

Gdy użytkownik dotknie powiadomienia i odblokuje urządzenie, karta pojawi się w aplikacji Google Pay.

Jeśli użytkownik ma kilka kart, wyświetli się tylko ta, która była używana jako ostatnia. Jeżeli ma zapisane karty jako grupę kart pokładowych, w powiadomieniu pojawi się tylko 1 z kart należąca do grupy. Jednak po jej dotknięciu użytkownik będzie mógł przesuwać palcem w lewo i prawo, by zobaczyć inne karty w grupie.

Powiadomienie jest przypięte i nie zamyka się automatycznie po otwarciu. Następuje to 60 minut po class.localScheduledDepartureDateTime.

Odbiór powiadomień o aktualizacjach lotów

Gdy pewne pola lotu ulegną zmianie, użytkownicy z zapisanymi kartami pokładowymi otrzymają na swoich urządzeniach powiadomienie push. Dzieje się tak tylko po spełnieniu pewnych warunków.

Terminal i bramka w miejscu wylotu

Jeśli zmienisz class.origin.terminal lub class.origin.gate i będzie spełniony poniższy warunek, zostanie wysłane powiadomienie o zmianie pola.

• Pozostało mniej niż 3 godziny do class.localScheduledDepartureDateTime.

Powiadomienie ma taki format: „Linia lotnicza Przykładowe Linie Lotnicze zmieniła bramkę na A1”. Nie można go zmienić.

Czas wejścia na pokład i czas wylotu

Jeśli zmienisz class.localBoardingDateTime lub class.localEstimatedOrActualDepartureDateTime i będą spełnione poniższe warunki, zostanie wysłane powiadomienie o zmianie pola.

• Pozostało mniej niż 24 godziny do class.localScheduledDepartureDateTime.
• Czas zmieni się przynajmniej o 10 minut.

Powiadomienie ma taki format: „Linia lotnicza Przykładowe Linie Lotnicze zmieniła czas wejścia na pokład na 18:00”. Nie można go zmienić.

Obsługa kart, które straciły ważność

Gdy klikniesz „Karty” w aplikacji Google Pay, znajdziesz sekcję „Karty, które straciły ważność”. Zawiera ona wszystkie karty zarchiwizowane i nieaktywne. Bilet przenosi się do sekcji kart, które straciły ważność, jeśli jest spełniony przynajmniej 1 z tych warunków:

• Minęły co najmniej 24 godziny od utraty ważności przez class.localScheduledDepartureDateTime lub class.localEstimatedOrActualDepartureDateTime. Karta przenosi się do sekcji kart, które straciły ważność, w dowolnym momencie w ciągu 24–48 godzin od utraty ważności przez class.localScheduledDepartureDateTime lub class.localEstimatedOrActualDepartureDateTime.
• Upłynął czas object.validTimeInterval.end.date. Karta przenosi się do sekcji kart, które straciły ważność, w ciągu maksymalnie 24 godzin od utraty ważności przez object.validTimeInterval.end.date.
• Pole object.state jest oznaczone jako Expired, Inactive lub Completed.

Łączenie z zapisaną kartą

Gdy użytkownik zapisze kartę, odwołaj się do jej objectId, aby połączyć z tą kartą.

Aby odwołać się do karty, użyj tego linku:

https://pay.google.com/gp/v/object/{<issuerId>}.{<ObjectId>}

Kartę można wyświetlić za pomocą aplikacji Google Pay lub przeglądarki.

Uwaga: jeśli użytkownik nie zapisał karty, zobaczy błąd „Nie znaleziono elementu”. Jeśli użytkownik ma zainstalowaną aplikację Google Pay, link działa w trybie offline.

Link zewnętrzny w zapisanej karcie Google Pay

Możesz dodać link do swojej aplikacji lub witryny pod nagłówkiem zapisanej karty Google Pay. Ta funkcja jest dostępna dla wszystkich rodzajów kart Google Pay.

Uwaga: ta funkcja jest dostępna tylko po zrealizowaniu co najmniej 2 integracji z Google Pay API for Passes. Muszą to być integracje aplikacji, aplikacji internetowej lub poczty e-mail.

Zgłaszanie wniosku o dostęp

Poproś o dostęp za pomocą formularza wsparcia dla sprzedawców w sklepie. O czym musisz pamiętać:

• W formularzu musisz podać swój identyfikator wydawcy.
• Jako Typ problemu wybierz „Techniczny / Integracja interfejsu API”.
• Wybierz Dodawanie linku do aplikacji lub witryny poniżej karty Google Pay.

Ustawianie linku do aplikacji na karcie Google Pay

Dla danej karty Google Pay zdefiniuj appLinkData, aby ustawić identyfikator URI swojej aplikacji lub witryny. Identyfikator URI może mieć dowolny format, ale zalecamy użycie linku dynamicznego.

Format i kontekst pola appLinkData można sprawdzić w poniższym kodzie źródłowym:

{
  "id": string,
  "classId": string,
  …
  …
  …
  "appLinkData": {
    "androidAppLinkInfo": {
      "appLogoImage": {
        "sourceUri": {
          "uri": string
        }
      },
        "title": {
          "defaultValue": {
            "language": string,
              "value": string
          }
        },
          "description": {
            "defaultValue": {
              "language": string,
                "value": string
            }
          },
            "appTarget": {
              "targetUri": {
                "uri": string,
                  "description": string
              }
            }
    }
  }
  …
  …
  …
}