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 wydarzenia. Pojęcia omawiane w tym przewodniku pomagają lepiej poznać możliwości zapisanych biletów na wydarzenia.

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

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

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 biletów na określone wydarzenie (np. zmienić adres miejsca), wystarczy wykonać wywołanie update lub patch tylko w EventTicketClass albo użyć Google Pay Merchant Center. Google przekaże te informacje do wszystkich obiektów EventTicketObject powiązanych ze zaktualizowaną klasą EventTicketClass. Dotyczy to wszystkich pól określonych na poziomie EventTicketClass.

Aby zaktualizować jeden bilet (na przykład po zmianie numeru miejsca jednego posiadacza biletu), musisz wykonać wywołanie update lub patch w jednym EventTicketObject. Dotyczy to wszystkich pól określonych na poziomie EventTicketObject.

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

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 jednym 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.

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

Więcej informacji o reprezentacji kart w UI znajdziesz w sekcji Grupowanie biletów na wydarzenia.

Grupowanie biletów na wydarzenia

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.

Warunki, według których EventTicketObject są uznawane za grupę, zależą od tego, czy zdefiniowano właściwość class.eventID.

Grupowanie za pomocą class.eventId

Właściwość class.eventId może grupować bilety niezależnie od innych właściwości. Jeśli na przykład dwa obiekty EventTicketObject mają wartość class.eventId = "foo" (nawet wtedy, gdy ich class.eventName i class.dateTime.start są różne), oba są uznawane za należące do grupy.

Jeśli używasz class.eventID, obiekty są uznawane za grupę, gdy ich poniższe właściwości są spójne.

  • Identyfikator wydawcy (z Google Pay API for Passes Merchant Center)
  • class.eventId

Grupowanie bez class.eventId

Jeśli obiekty EventTicketObject nie mają ustawionego class.eventId, są uznawane za grupę wtedy, gdy wszystkie te właściwości są takie same:

  • Identyfikator wydawcy (z Google Pay API for Passes Merchant Center)
  • class.eventName
  • class.dateTime.start

Odbiór powiadomień o nadchodzących wydarzeniach

Trzy godziny przed rozpoczęciem wydarzenia Google Pay wysyła do użytkownika powiadomienie. Czas wydarzenia jest określony przez class.dateTime.start.

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

class.eventName
Expand for more options

Gdy 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 zapisaną grupę biletów na wydarzenia, w powiadomieniu pojawi się tylko jedna 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.dateTime.end. Jeśli nie podano czasu class.dateTime.end, zamiast tego jest używany class.dateTime.start.

Powiązane oferty specjalne

Powiązane oferty specjalne wyświetlają się w widoku biletu na wydarzenie, dzięki czemu użytkownik może łatwiej znaleźć odpowiednią treść. Pole listy linkedOfferIds dostępne do zapisu w EventTicketObject pokazuje oferty specjalne powiązane z biletem na wydarzenie.

Tworzenie oferty specjalnej przed połączeniem

Zanim utworzysz powiązaną ofertę specjalną, musisz utworzyć klasy i obiekty tej oferty połączone z odpowiednim biletem na wydarzenie. Więcej informacji o tworzeniu ofert specjalnych znajdziesz na stronie ofert specjalnych. W odróżnieniu od samodzielnych ofert specjalnych oferty powiązane nie muszą być zapisywane bezpośrednio przez użytkownika. Pole id w OfferObject wskazuje EventTicketObject.

Dotychczasowe oferty specjalne można łączyć z biletem na wydarzenie za pomocą wywołań interfejsu API REST insert, update, patch lub modifyLinkedOfferObjects.

Gdy oferty specjalne są powiązane z biletem na wydarzenie po utworzeniu biletu za pomocą wywołania insert lub gdy są jednocześnie powiązane i rozłączone z obecnym biletem na wydarzenie za pomocą wywołania update, pole linkedOfferIds może zostać zapisane z resztą EventTicketObject w ustalonym formacie:

{
  "id": "2945482443380251551.ExampleObject1",
  "classId": "2945482443380251551.ExampleClass1",
  ...
  "linkedOfferIds": [
    "2945482443380251551.OfferObject1",
    "2945482443380251551.OfferObject2"
  ]
}

Gdy oferty specjalne są powiązane i rozłączone z obecnym biletem na wydarzenie za pomocą wywołania patch, pole linkedOfferIds może być jedynym polem w żądaniu:

{
  "linkedOfferIds": [
    "2945482443380251551.OfferObject1",
    "2945482443380251551.OfferObject2"
  ]
}

Aby jednak uniknąć pomyłek w obsłudze tablic, wybierz, które powiązane oferty specjalne chcesz dodać, a które usunąć. Musisz też mieć możliwość pominięcia powiązanych ofert specjalnych, które powinny pozostać niezmienione. Zalecamy użycie metody modifyLinkedOfferObjects, jak w tym przykładzie:

{
  "linkedOfferObjectIds" {
    "addLinkedOfferObjectIds": [
      "2945482443380251551.OfferObject1",
      "2945482443380251551.OfferObject2"
    ],
    "removeLinkedOfferObjectIds": [
      "2945482443380251551.OfferObject3",
      "2945482443380251551.OfferObject4"
    ]
  }
}

Projektowanie biletu na wydarzenie z powiązanymi ofertami specjalnymi

Powiązane oferty specjalne wyświetlają się w widoku biletu na wydarzenie między sekcją karty a sekcją szczegółów, jak pokazano poniżej. Na karuzeli wyświetlanych jest maksymalnie 5 powiązanych ofert specjalnych. Jeśli z biletem na wydarzenie jest powiązanych więcej ofert specjalnych, użytkownik może kliknąć przycisk „Więcej” na końcu karuzeli, aby wyświetlić wszystkie oferty.

Powiązane oferty specjalne

Po kliknięciu powiązana oferta specjalna ma uproszczony wygląd, jak pokazano poniżej.

Kliknięto powiązaną ofertę specjalną

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 jeden z tych warunków:

  • Minęły już 72 godziny od utraty ważności class.dateTime.end. Jeśli class.dateTime.end nie został określony, a zamiast tego jest używany class.dateTime.start. Karta przenosi się do sekcji kart, które straciły ważność, w ciągu od 72 do 96 godzin od utraty ważności przez class.dateTime.end lub class.dateTime.start.
  • 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 po upływie czasu object.validTimeInterval.end.date.
  • Pole object.state jest oznaczone jako Expired, Inactive lub Completed.

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.

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 linka do aplikacji lub witryny poniżej karty 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 linka 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
              }
            }
    }
  }
  …
  …
  …
}