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ą kart lojalnościowych. Pojęcia omawiane w tym przewodniku pomagają lepiej poznać możliwości zapisanych kart lojalnościowych.

Poniższe przypadki użycia są dostępne tylko w kategorii programów lojalnościowych:

• Aktualizacja kart
• Skanowanie w aplikacji Google Pay
• Powiązane oferty specjalne
• Powiadomienia z obsługą geofencingu
• Obsługa kart, które straciły ważność
• Łączenie z zapisaną kartą
• Odłączanie od zapisanej karty
• Rejestracja i logowanie się

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 LoyaltyClass albo skorzystać z Google Pay Merchant Center. Google przekaże te informacje do wszystkich obiektów LoyaltyObject powiązanych ze zaktualizowaną klasą LoyaltyClass. Dotyczy to wszystkich pól określonych na poziomie LoyaltyClass.

Aby zaktualizować pojedynczy bilet (na przykład po zmianie salda punktów karty lojalnościowej), musisz wykonać wywołanie update lub patch w pojedynczym LoyaltyObject. Dotyczy to wszystkich pól określonych na poziomie LoyaltyObject.

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

Skanowanie w aplikacji Google Pay

Użytkownicy mogą dodać kartę lojalnościową do aplikacji Google Pay, skanując ją lub ręcznie wpisując jej dane. Google Pay API for Passes tworzy LoyaltyObject, który nie odwołuje się do określonej wcześniej LoyaltyClass. Aby utworzyć nowy obiekt lub nową klasę, nie musisz nic robić. LoyaltyObject utworzony przez Google Pay API for Passes nie może jednak zostać zaktualizowany i zachowuje się jak karta statyczna.

Powiązane oferty specjalne

Powiązane oferty specjalne wyświetlają się w widoku karty lojalnościowej, dzięki czemu użytkownik może łatwiej znaleźć odpowiednią treść. Pole listy linkedOfferIds dostępne do zapisu w LoyaltyObject pokazuje oferty specjalne powiązane z kartą lojalnościową.

Tworzenie oferty specjalnej przed połączeniem

Zanim powiążesz ofertę specjalną, musisz utworzyć klasy i obiekty tej oferty połączone z odpowiednią kartą lojalnościową. 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 LoyaltyObject.

Łączenie ofert specjalnych z kartą lojalnościową

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

Gdy oferty specjalne są powiązane z kartą lojalnościową po utworzeniu karty za pomocą wywołania insert lub gdy są jednocześnie powiązane i rozłączone z dotychczasową kartą lojalnościową za pomocą wywołania update, pole linkedOfferIds może zostać zapisane z resztą LoyaltyObject w ustalonym formacie:

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

Gdy oferty specjalne są powiązane i rozłączone z obecną kartą lojalnościową 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 karty lojalnościowej z powiązanymi ofertami specjalnymi

Powiązane oferty specjalne wyświetlają się w widoku karty lojalnościowej 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 kartą lojalnościową jest powiązanych więcej ofert specjalnych, użytkownik może kliknąć przycisk Więcej na końcu karuzeli, aby wyświetlić wszystkie oferty.

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

Powiadomienia z obsługą geofencingu

Google może wyświetlać powiadomienia powiązane z zapisanym obiektem klienta zależnie od jego odległości od wskazanego przez Ciebie miejsca.

Informacje o geolokalizacji dodawane są na 2 sposoby:

1. Po utworzeniu konta Google Pay API for Passes Merchant Center używane są dane geolokalizacji z Map Google.
2. Do obiektu lub klasy można dodawać współrzędne za pomocą interfejsu API REST.

Instrukcje dodawania współrzędnych do obiektów lub klas znajdziesz w sekcji Dodawanie danych geolokalizacji za pomocą interfejsu API REST.

Pojęcia związane z geofencingiem

Dzięki geolokalizacji w Mapach Google algorytmy firmy Google ustalają, czy użytkownik znajduje się w sklepie lub w jego pobliżu. Ta funkcja dotyczy wszystkich klas i obiektów utworzonych na koncie Google Pay API for Passes Merchant Center.

Algorytm uwzględnia dane GPS, Wi-Fi i Bluetooth, informacje o ruchu, czas kontaktu oraz inne czynniki. Jeśli ustali, że użytkownik jest fizycznie obecny w określonym miejscu, wyświetlone zostanie powiadomienie z obsługą geofencingu.

Jeśli Object ma ręcznie dodane współrzędne, powiadomienie z obsługą geofencingu wyświetli się, gdy użytkownik znajdzie się w odległości 150 metrów od określonego przez te współrzędne miejsca.

Częstotliwość, ograniczanie i wyłączenie powiadomień z obsługą geofencingu

Użytkownik może otrzymać do 4 powiadomień dziennie.

Jeśli geofence ma zapisanych wiele obiektów, dla każdego konta Google Pay API for Passes Merchant Center wyświetli się 1 powiadomienie z karuzelą, którego nie można zmienić. Możesz przechodzić kolejno między obiektami karuzeli:

Aby powiadomienia z obsługą geofencingu działały, użytkownik musi włączyć Najnowsze informacje o Twoich rzeczach w ustawieniach powiadomień aplikacji Google Pay oraz mieć włączone usługi lokalizacyjne na swoim urządzeniu.

Dodawanie danych geolokalizacji za pomocą interfejsu API REST

W klasach lub obiektach możesz podawać tablicę miejsc (pod postacią szerokości i długości geograficznej). Google porównuje obecną geolokalizację użytkownika z listą miejsc powiązaną z klasą lub obiektem i wysyła powiadomienie, gdy użytkownik znajduje się w odległości 150 metrów (lub mniejszej) od jednego z ustawionych miejsc. Przykłady kodu pokazują, jak podać miejsca w klasach lub obiektach:

{
  ... //Class or Object content

  "locations": [{
    "kind": "walletobjects#latLongPoint",
    "latitude": 37.422087,
    "longitude": -161446
  }, {
    "kind": "walletobjects#latLongPoint",
    "latitude": 37.429379,
    "longitude": -121.12272999999999
  }, {
    "kind": "walletobjects#latLongPoint",
    "latitude": 37.333646,
    "longitude": -122.884853
  }]
}

List<LatLongPoint> locations = new ArrayList<LatLongPoint>();
locations.add(new LatLongPoint().setLatitude(37.422087).setLongitude(
    -122.161446));
locations.add(new LatLongPoint().setLatitude(37.429379).setLongitude(
    -121.12272999999999));
locations.add(new LatLongPoint().setLatitude(37.333646).setLongitude(
    -122.884853));

yourClassOrObject.setLocations(locations);

$locations = array(
  array(
    'kind' => 'walletobjects#latLongPoint',
    'latitude' => 37.442087,
    'longitude' => -122.161446
  ),
  array(
    'kind' => 'walletobjects#latLongPoint',
    'latitude' => 37.429379,
    'longitude' => -122.12272999999999
  ),
  array(
    'kind' => 'walletobjects#latLongPoint',
    'latitude' => 37.333646,
    'longitude' => -121.884853
  )
);

offer_class_object = {
  # class or object content
  'locations': [{
    'kind': 'walletobjects#latLongPoint',
    'latitude': 37.442087,
    'longitude': -122.161446
    },{
    'kind': 'walletobjects#latLongPoint',
    'latitude': 37.429379,
    'longitude': -122.12272999999999
    },{
    'kind': 'walletobjects#latLongPoint',
    'latitude': 37.333646,
    'longitude': -121.884853
  }]
}

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:

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

Rejestracja i logowanie się

Funkcja rejestracji i logowania się w programie lojalnościowym pozwala użytkownikom wyszukać program lojalnościowy i dołączyć do niego lub zalogować się na swoim koncie za pomocą Google Pay. Więcej informacji znajdziesz w artykule Rejestracja i logowanie się.