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ą biletów na autobusy, promy, pociągi i inne środki transportu. Pojęcia omawiane w tym przewodniku pomagają lepiej poznać możliwości biletów na przejazdy.

Uwaga: ta dokumentacja dotyczy tylko integracji z biletami zawierającymi kod kreskowy lub kod QR. Informacje o integracji z innymi rodzajami biletów na przejazdy znajdziesz na stronie pomocy dotyczącej biletów na przejazdy.

Informacje o lotniczych kartach pokładowych znajdziesz w opisie kategorii kart pokładowych.

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

TransitClass i TransitObject

Tak jak w innych kategoriach w Google Pay API for Passes, dane biletów na przejazdy są przechowywane w 2 strukturach: TransitClass i TransitObject. Ten przewodnik wyjaśnia, jak używać tych struktur danych, aby obsługiwały Twoje bilety.

TransitClass

TransitClass określa szablon, który służy do wyświetlania obiektu powiązanego z klasą. Szablon określa pola, które mają wyświetlać się w poszczególnych sekcjach biletu. Określa też logo i nazwę wydawcy, które są używane przez różne obiekty.

Jeśli 2 typy biletów wymagają, aby w pewnych sekcjach wyświetlały się różne dane, można utworzyć 2 osobne klasy TransitClasses. Jedna klasa TransitClass może na przykład być używana z jednorazowymi biletami na połączenia bezpośrednie, a druga klasa TransitClass – z biletami sezonowymi.

TransitObject

TransitObject zawiera wszystkie dane powiązane z podróżą, przewoźnikiem i pasażerami. TransitObject może na przykład zawierać miejsce wyjazdu, cel podróży, czas wyjazdu, numer przewoźnika, imię i nazwisko pasażera, numer miejsca i inne dane. Niektóre z tych wartości są używane w wielu obiektach TransitObjects.

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

Obsługiwane kraje

Kraje obsługujące aplikację Google Pay 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 kupuje bilet.

Przypadki użycia

Poniższe przypadki użycia są dostępne tylko w kategorii biletów na przejazdy:

• Aktualizacja kart
• Ustawianie podróży z wieloma etapami
• Tworzenie przycisku do zapisywania wielu kart
• Grupowanie wielu biletów na przejazdy
• Odbiór powiadomień o nadchodzących podróżach
• 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ć sposób wyświetlania kart, np. gdy zmieni się logo, wystarczy wykonać wywołanie update lub patch w TransitClass albo skorzystać z Google Pay Merchant Center. Google przekaże te informacje do wszystkich obiektów TransitObject powiązanych ze zaktualizowaną klasą TransitClass. Dotyczy to wszystkich pól określonych na poziomie TransitClass.

Aby zaktualizować pojedynczy bilet (na przykład po zmianie czasu wyjazdu), musisz wykonać wywołanie update lub patch w 1 obiekcie TransitObject. Dotyczy to wszystkich pól określonych na poziomie TransitObject.

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

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ę TransitClass list. Aby znaleźć wszystkie obiekty danej klasy, wywołaj metodę TransitObject list.

Ustawianie podróży z wieloma etapami

Trasa podróży często nie prowadzi bezpośrednio do celu, tylko obejmuje kilka etapów. W takiej sytuacji operator biletu na przejazd może wydać 1 bilet na każdy etap podróży lub 1 bilet na całą podróż. Google Pay API for Passes naśladuje to zachowanie, używając 1 obiektu TransitObject na każdy etap lub 1 wieloetapowego obiektu TransitObject.

Użycie 1 obiektu TransitObject na etap jest bardzo łatwe. Etap możesz określić za pomocą object.ticketLeg. Każdy bilet możesz utworzyć i aktualizować osobno. Możesz jednak określić sposób grupowania biletów. Więcej informacji znajdziesz w sekcji Grupowanie wielu biletów. Jest to zalecana metoda ustawiania podróży z wieloma etapami.

Wieloetapowych obiektów TransitObject powinno się używać tylko wtedy, gdy tego typu połączony bilet jest zaakceptowany na każdym etapie oraz gdy dane biletu (np. kod QR) są takie same na każdym etapie. Etapy można określić za pomocą listy object.ticketLegs[]. Karta biletu wyświetla tylko miejsce wyjazdu 1. etapu i miejsce docelowe ostatniego etapu. Pełny plan podróży jest wyświetlany w sekcji szczegółów biletu.

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.

Więcej informacji o prezentowaniu kart w UI znajdziesz w sekcji Grupowanie wielu biletów.

Grupowanie wielu biletów

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 TransitObject są uznawane za grupę tylko wtedy, gdy używają tych samych wartości object.classId, object.ticketLeg.departureDateTime i jednej z tych właściwości (wymienionych według priorytetu):

1. object.tripId
2. object.purchaseDetails.confirmationCode

Ma to na celu zgrupowanie biletów różnych pasażerów podczas tej samej podróży.

Jeśli chcesz zgrupować bilety, zalecamy ustawienie spójnych wartości w tych polach, nawet jeśli dany obiekt TransitObject nie jest zgrupowany z innymi.

Odbiór powiadomień o nadchodzących podróżach

Godzinę przed rozpoczęciem podróży Google Pay wysyła do użytkownika powiadomienie. Czas podróży jest określony jako czas object.ticketLeg.departureDateTime lub 1. element tablicy object.ticketLegs[].departureDateTime.

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ć:

Ticket fot your upcoming trip to object.ticketLeg.destinationName
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 zapisanych wiele zgrupowanych biletów jako grupę wielu biletów, w powiadomieniu pojawi się tylko jeden z biletów należących 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 czasie object.ticketLeg.departureDateTime lub po 1. czasie określonym w object.ticketLegs[].departureDateTime.

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 upływu czasu object.ticketLeg.arrivalDateTime lub ostatniego czasu object.ticketLegs[].arrivalDateTime. Bilet przenosi się do sekcji kart, które straciły ważność, w ciągu 24–48 godzin po upływie czasu object.ticketLeg.arrivalDateTime lub ostatniego czasu określonego w object.ticketLegs[].arrivalDateTime.
• 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
              }
            }
    }
  }
  …
  …
  …
}