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:
{ i"d:" 2"945482443380251551.ExampleObject1," c"lassId:" 2"945482443380251551.ExampleClass1," ... l"inkedOfferIds:" [ 2"945482443380251551.OfferObject1," 2"945482443380251551.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:
{ l"inkedOfferIds:" [ 2"945482443380251551.OfferObject1," 2"945482443380251551.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:
{ l"inkedOfferObjectIds " { a"ddLinkedOfferObjectIds:" [ 2"945482443380251551.OfferObject1," 2"945482443380251551.OfferObject2 " ], r"emoveLinkedOfferObjectIds:" [ 2"945482443380251551.OfferObject3," 2"945482443380251551.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:
- 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:
![](https://developers-dot-devsite-v2-prod.appspot.com/static/pay/passes/images/geofenced-notification-example.png?authuser=5&hl=pl)
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 przezobject.validTimeInterval.end.date
. - Pole
object.state
jest oznaczone jakoExpired
,Inactive
lubCompleted
.
Łą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ę.