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
Tworzenie przycisku do zapisywania wielu kart
Grupowanie biletów na wydarzenia
Odbiór powiadomień o nadchodzących wydarzeniach
Powiązane oferty specjalne
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ć 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ć pojedynczy bilet (na przykład po zmianie numeru miejsca posiadacza biletu), musisz wykonać wywołanie update lub patch w pojedynczym 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 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.

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 2 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

Jeśli jest ustawiony class.eventId, ma on pierwszeństwo przy ustalaniu, które obiekty należą do grupy.

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

Uwaga: właściwość class.dateTime.start jest opcjonalna. Jeśli nie jest ustawiona, grupy są ustalane tylko na podstawie class.eventName i identyfikatora wydawcy.

Odbiór powiadomień o nadchodzących wydarzeniach

Na 3 godziny przed rozpoczęciem wydarzenia Google Pay wysyła do użytkownika powiadomienie. Godzina wydarzenia jest określona 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 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 zapisaną grupę biletów na wydarzenia, 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.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.

Łączenie ofert specjalnych z biletem na wydarzenie

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"
  ]
}

Uwaga: jeśli wykonasz żądanie update dla bieżącego EventTicketObject bez pola linkedOfferIds dostępnego do zapisu, wszystkie oferty specjalne zostaną rozłączone.

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"
  ]
}

Uwaga: aby rozłączyć wszystkie powiązane oferty specjalne za pomocą wywołania patch, musisz samodzielnie ustawić pole linkedOfferIds na null lub [].

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.

Uwaga: jeśli w powiązanym OfferClass nie ma baneru powitalnego, powiązana oferta specjalna używa koloru tła EventTicketClass w tym widoku.

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

Uwaga: ten obraz zawiera wszystkie pola, które trzeba wypełnić w uproszczonym projekcie oferty specjalnej. Jednak nie wszystkie z nich są niezbędne do poprawnego utworzenia OfferClass lub OfferObject. Listę wymaganych pól znajdziesz w opisie metod OfferClass insert i OfferObject insert.

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