Angażowanie użytkowników za pomocą Google Pay

Dodawanie wiadomości podczas aktualizowania ważnych informacji

W każdej kategorii jest dostępna sekcja wiadomości. Można w niej przedstawiać ważne informacje, takie jak zmiany dotyczące kart lojalnościowych, kart podarunkowych, ofert specjalnych, biletów na wydarzenia, kart pokładowych i programów biletów na przejazdy. Więcej informacji znajdziesz na stronach szablonów dla Twojego typu karty:

Karty pokładowe Bilety na wydarzenia Karty podarunkowe Programy lojalnościowe Oferty specjalne Bilety na przejazdy

Wiadomości można dodawać do klas lub obiektów za pomocą metody insert, update lub patch, wypełniając właściwość tablicy messages[]. Można też dodawać treść do obecnych wiadomości (maksymalnie 10) za pomocą metody addMessage. Więcej informacji znajdziesz w dokumentacji.

Poniższy kod pobiera bieżącą datę ważności oferty specjalnej ( validTimeInterval.end), aktualizuje datę ważności i dodaje ją do tablicy messages[]. Dzięki temu użytkownik dowie się o zmianach informacji, gdy zobaczy zapisany Object w aplikacji Google Pay:

Java

// Get the specific Offer Object
OfferObject obj = client.offerobject().get("2945482443380251551.ExampleObject1").execute();

// Update the version, validTimeInterval.end, and add a message
obj.setVersion(obj.getVersion() + 1L);
obj.setValidTimeInterval(new TimeInterval().setEnd(new DateTime().setDate(new com.google.api.client.util.DateTime(new Date().getTime() + 263000000000L))));

// Get the current messages
List messages = obj.getMessages();

// Define new message
WalletObjectMessage message = new WalletObjectMessage()
  .setHeader("Important Notice")
  .setBody("Your offer has been extended!");

// Add the new message about updates to the Offer Object
messages.add(message);
obj.setMessages(messages);

// Update the Offer Object
OfferObject returnObj = client.offerobject().patch(obj.getId(), obj).execute();

PHP

// Get the specific Offer Object
Google_OfferObject $offerObj = $service->offerobject->get('2945482443380251551.ExampleObject1');

// Update the version, validTimeInterval.end, and add a message
$offerObj->setVersion($offerObj->getVersion() + 1);
$validTimeInterval = new Google_TimeInterval();
$startDateTime = new Google_DateTime();
$startDateTime->setDate('2013-06-12T23:20:50.52Z');
$validTimeInterval->setStart($startDateTime);
$endDateTime = new Google_DateTime();
$endDateTime->setDate('2013-12-12T23:20:50.52Z');
$validTimeInterval->setEnd($endDateTime);
$offerObj->setValidTimeInterval($validTimeInterval)

// Get the current messages
$messages = $offerObj->getMessages();

// Define new message
$newMessage = array(
  'header' => 'Important Notice',
  'body' => 'Your offer has been extended!',
  'kind' => 'walletobjects#walletObjectMessage'
);

// Add the new message about updates to the Offer Object
array_push($messages, $newMessage);
$offerObj->setMessages($messages);

// Update the Offer Object
Google_OfferObject offerObj = $service->offerobject->update('2945482443380251551.ExampleObject1',offerObj);

Python

# Get the specific Offer Object
offer_object = service.offerobject().get(resourceId='2945482443380251551.ExampleObject1')
# Update the version, validTimeInterval.end, and add a message
offer_object['version'] = str(int(offer_object['version']) + 1)
offer_object['validTimeInterval'] = {
     'start' : {'date':'2018-01-20T23:20:50.520Z'}
     ,'end' : {'date':'2018-01-24T23:20:50.520Z'}
    }

// Get the current messages
messages = offer_object['messages']

// Define new message
message = {
   'header': 'Important Notice',
   'body': 'Your offer has been extended!',
   'kind': 'walletobjects#walletObjectMessage'
 }

// Add the new message about updates to the Offer Object
messages.append(message)
offer_object['messages'] = messages

# Update the Offer Object
api_request = service.offerobject().update(resourceId='2945482443380251551.ExampleObject1',body=offer_object)
api_response = api_request.execute()

Uwaga: jeśli nie ustawiono startTime, wiadomość wyświetli się zaraz po wstawieniu Object. Jeśli nie podano endTime, wiadomość będzie wyświetlać się na liście bez ograniczeń czasowych. Więcej informacji znajdziesz w opisie właściwości messages[].

Aktualizacja stanu

Niezależnie od kategorii każdy obiekt ma właściwość state. Dzięki aktualizacji stanu obiektu klient wie, że jego karta została wykorzystana lub utraciła ważność.

Każda aktualizacja powinna rozpoczynać się od żądania GET pobierającego Object. Dzięki temu zostanie użyta najnowsza wersja obiektu. Po zmianie stanu wersja obiektu powinna zostać zwiększona. Aby zapisać zaktualizowany Object, wykonaj żądanie PUT.

Oto przykładowe identyfikatory URI REST używane w żądaniu GET obiektu i żądaniu PUT (aktualizacji) obiektu offerObject:

GET https://walletobjects.googleapis.com/walletobjects/v1/offerObject/resourceId
PUT https://walletobjects.googleapis.com/walletobjects/v1/offerObject/resourceId

Więcej informacji o metodach GET i metodach aktualizacji w różnych kategoriach znajdziesz w dokumentacji.

Uwaga: metody PUT (aktualizacji) zastępują cały obiekt nową definicją PUT. Aby zaktualizować tylko wybrane pola i zachować obecne dane Object, użyj metod PATCH zgodnie z instrukcjami z dokumentacji. Informacje o różnicach między PUT i PATCH znajdziesz w sekcji na temat semantyki poprawki dotyczącej różnic między PUT a PATCH.

Poniższe przykłady kodu pokazują, jak zaktualizować offerObject w różnych językach. Kod obiektów w innych kategoriach wygląda podobnie:

Java

// Get the specific Offer Object
OfferObject obj = client.offerobject().get("2945482443380251551.ExampleObject1").execute();
// Update the version and state
obj.setVersion(obj.getVersion() + 1L);
obj.setState("expired"); //see the Reference API for valid "state" options
// Update the Offer Object
OfferObject returnObj = client.offerobject().update(obj.getId(), obj).execute();

PHP

// Get the specific Offer Object
Google_OfferObject offerObj = $service->offerobject->get('2945482443380251551.ExampleObject1');
// Update the version and points
offerObj.setVersion(offerObj.getVersion() + 1);
offerObj.setState("state"); // see the Reference API for valid "state" options
// Update the Offer Object
Google_OfferObject offerObj = $service->offerobject->update('2945482443380251551.ExampleObject1',offerObj);

Python

# Get the specific Offer Object
offer_object = service.offerobject().get(resourceId='2945482443380251551.ExampleObject1')
# Update the version and state
offer_object['version'] = str(int(offer_object['version']) + 1)
offer_object['state'] = 'expired' # see the Reference API for valid "state" options
# Update the Offer Object
api_request = service.offerobject().update(resourceId='2945482443380251551.ExampleObject1',body=offer_object)
api_response = api_request.execute()

Lokalizacja

Google Pay API for Passes pozwala sprzedawcom dodawać zlokalizowaną treść, która będzie wyświetlana użytkownikom w zależności od ich ustawień języka. Interfejs API zawiera dodatkowe pola przeznaczone do tego celu. Każde zlokalizowane pole jest zagnieżdżonym obiektem LocalizedString, który wygląda tak:

{
  "kind": "walletobjects#localizedString",
  "translatedValues": [
    {
      "kind": "walletobjects#translatedString",
      "language": string,
      "value": string
    }
  ],
  "defaultValue": [
    {
      "kind": "walletobjects#translatedString",
      "language": string,
      "value": string
    }
  ]
}

Wszystkie LocalizedStrings muszą mieć pole defaultValue. Wszystkie translatedStrings muszą zawierać język i wartość.

Pole językowe musi odwoływać się do tagu języka BCP 47 (np. „en-US”, „en-GB”, „es-419” itp.). Wartość to przetłumaczona wartość ciągu tekstowego, którą użytkownik zobaczy, jeśli używany przez niego język będzie się zgadzać.

Zlokalizowane ciągi tekstowe będą wyświetlane użytkownikowi na podstawie najbliższego dopasowania do jego ustawień języka. Jeśli nie będzie odpowiedniej wartości translatedValue, zostanie użyta DefaultValue. Jeśli odpowiednie zlokalizowane pole zostanie ustawione, niezlokalizowane pola nie będą używane.

Sprawdzanie, czy użytkownik usunął kartę

Aby sprawdzić, czy użytkownik usunął kartę (np. lojalnościową) z Google Pay, pobierz jego Object za pomocą podanego poniżej wywołania „get” i sprawdź atrybut hasUsers.

Aby na przykład sprawdzić loyaltyObject za pomocą wywołania GET:

GET https://walletobjects.googleapis.com/walletobjects/v1/loyaltyObject/objectId

Jeśli wszyscy użytkownicy usunęli kartę lub karta lojalnościowa została usunięta, Google nie usuwa obiektu. Atrybut hasUsers obiektu zostaje ustawiony na fałsz.

Atrybut hasUsers można sprawdzić w czasie rzeczywistym, gdy użytkownik loguje się w Twojej witrynie lub aplikacji, albo w ramach przetwarzania wsadowego dla wielu użytkowników równocześnie.

Identyfikator obiektu, za pomocą którego jest pobierany LoyaltyObject, wybierasz podczas tworzenia obiektu. Aby udostępnić użytkownikom spersonalizowane informacje o ich bieżącej liczbie punktów, zapisz identyfikatory w swoim repozytorium.

Więcej informacji o różnych metodach GET znajdziesz w dokumentacji. Google nie wysyła powiadomień o usunięciu obiektu w czasie rzeczywistym. Wymagałoby to od użytkownika wdrożenia detektora i zapewnienia odpowiedniej gwarancji jakości usług.

Sposoby interakcji w różnych kategoriach

Niektóre metody interakcji występują tylko w konkretnych kategoriach kart. Szczegóły implementacji znajdziesz na stronach „Przypadki użycia” dotyczących poszczególnych kategorii:

Karty pokładowe Bilety na wydarzenia Karty podarunkowe Programy lojalnościowe Oferty specjalne Bilety na przejazdy