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

Poniższe przypadki użycia są dostępne tylko w kategorii ofert specjalnych:

Aktualizacja kart
Powiadomienia o wygaśnięciu oferty specjalnej
Powiadomienia z obsługą geofencingu
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 OfferClass albo skorzystać z Google Pay Merchant Center. Google przekaże te informacje do wszystkich obiektów OfferObject powiązanych ze zaktualizowaną klasą OfferClass. Dotyczy to wszystkich pól określonych na poziomie OfferClass.

Aby zaktualizować pojedynczą kartę (na przykład w przypadku zmiany daty ważności oferty specjalnej), musisz wykonać wywołanie update lub patch w 1 obiekcie OfferObject. Dotyczy to wszystkich pól określonych na poziomie OfferObject.

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

Powiadomienia o wygaśnięciu oferty specjalnej

Na 48 godzin przed wygaśnięciem oferty specjalnej do użytkowników jest wysyłane domyślne przypomnienie o tym, by ją wykorzystali. Aby aktywować powiadomienie, oferta musi spełniać te kryteria:

Na urządzeniu użytkownika nie mogło być wcześniej wyświetlone powiadomienie o wygaśnięciu oferty.
W datetime musi być ustawiony prawidłowy czas wygaśnięcia validTimeInterval.end.date przypadający w przyszłości.
Oferta musi być zapisana na urządzeniu użytkownika od ponad 12 godzin.
Pole disableExpirationNotification dostępne do zapisu nie może być ustawione na True. Domyślnie to pole jest ustawione na false.

Poniższy zrzut ekranu przedstawia przykładowe domyślne powiadomienie, którego nie można zmienić:

Oferta specjalna wygasa (dzisiaj, jutro, za [x] dni)

`class.title`

`class.titleImage`

Nagłówka powiadomienia o wygaśnięciu oferty specjalnej nie można dostosować.

Godziny niedostępności

Jeśli powiadomienie o wygaśnięciu oferty specjalnej jest ustawione na okres między 22:00 a 6:00 czasu lokalnego u użytkownika, oferta będzie się wyświetlać przed tym okresem lub po nim.

Niestandardowy czas powiadomienia o wygaśnięciu oferty specjalnej

Aby dostosować czas, w którym wyświetla się powiadomienie o wygaśnięciu Offer, użyj pola message.displayInterval.start.date w OfferObjects lub OfferClasses. Gdy to zrobisz, powiadomienie o wygaśnięciu wyświetli się zgodnie z czasem message.displayInterval.start.date, a nie zgodnie z domyślną logiką obliczoną na podstawie validTimeInterval.end.date. Poniższy przykład przedstawia dostosowany czas powiadomienia o wygaśnięciu:

{
  “message”: {
   “messageType”: “expirationNotification”,
   “displayInterval”: {
     “start”: {
      “date”: datetime
     }
   }
  }
}

displayInterval.start.date ustawia czas wyświetlenia powiadomienia. Może to być do 30 dni przed datą wygaśnięcia oferty. Jeśli podasz dłuższy okres, powiadomienie wyświetli się przy 30 dniach. Wiadomość nie musi mieć pola nagłówka ani treści. Jeśli będą one obecne, nie zostaną użyte.

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:

Po utworzeniu konta Google Pay API for Passes Merchant Center używane są dane geolokalizacji z Map Google.
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:

Zasób

{
  ... //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
  }]
}

Java

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

PHP

$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
  )
);

Python

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