Przypadki użycia

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

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.

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

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.

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.

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

object.tripId
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.

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.

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
              }
            }
    }
  }
  …
  …
  …
}