Примеры использования

Чтобы посмотреть примеры использования, выберите категорию.

С Google Pay API for Passes можно использовать карты постоянного клиента для взаимодействия с пользователями. Из этого руководства вы узнаете, как это делать.

В этом разделе описаны примеры использования, применимые только к картам постоянного клиента.

• Обновление информации в картах
• Сканирование в приложении Google Pay.
• Связанные предложения.
• Настройка уведомлений с учетом местоположения
• Действия с картами, у которых истек срок действия
• Создание ссылки на сохраненную карту постоянного клиента
• Добавление к сохраненной карте ссылки на стороннее приложение или сайт
• Регистрация и аутентификация

Обновление информации в картах

Иногда необходимо изменить сведения, указанные на карте, уже после ее сохранения пользователем. Сделать это можно с помощью REST API. Если изменения затрагивают только классы, можно также использовать Google Pay Merchant Center. Обновление информации на карте – один из важных аспектов взаимодействия с клиентом.

Чтобы обновить данные на всех картах (например, заменить логотип), необходимо только изменить с помощью метода update или patch класс LoyaltyClass или использовать Google Pay Merchant Center. Google перенесет изменения во все объекты LoyaltyObject, связанные с обновленным классом LoyaltyClass. Это относится ко всем полям, определенным на уровне LoyaltyClass.

Чтобы обновить отдельную карту (например, указать другое количество бонусов на карте), нужно изменить с помощью метода update или patch только один объект LoyaltyObject. Это относится ко всем полям, определенным на уровне LoyaltyObject.

Кроме того, не всегда получается предугадать, когда произойдут изменения или когда придется отправить запрос update или patch. В этом случае стоит периодически выполнять запросы update или patch для каждого класса и объекта. Посмотреть все классы в аккаунте отдельного продавца можно с помощью метода LoyaltyClass для list. Чтобы посмотреть все объекты определенного класса, вызовите метод list для LoyaltyObject.

Сканирование в приложении Google Pay

Пользователи могут добавить карту постоянного клиента в приложение Google Pay, просканировав ее или введя данные вручную. Инструмент Google Pay API for Passes создаст объект LoyaltyObject, который не будет ссылаться на ранее определенный класс LoyaltyClass. Создавать новый объект или класс вручную не потребуется. Однако объект LoyaltyObject, созданный с помощью Google Pay API for Passes, обновить нельзя, поскольку он статический.

Связанные предложения

Связанные предложения отображаются при просмотре карты постоянного клиента. Таким образом пользователи быстрее находят контент, который может их заинтересовать. В linkedOfferIds для объекта LoyaltyObject указывается список идентификаторов специальных предложений, связанных с картой постоянного клиента.

Подготовка специальных предложений

Чтобы добавить связанное предложение, нужно заранее создать классы и объекты, связанные с картой постоянного клиента. Подробная информация о создании специальных предложений доступна в разделе Специальные предложения. Пользователям не нужно явным образом сохранять связанные предложения. Свойство id в объекте OfferObject указывает на объект LoyaltyObject.

Как добавлять специальные предложения к картам постоянного клиента

Существующие специальные предложения можно связать с картой постоянного клиента, используя вызовы REST API: insert, update, patch или modifyLinkedOfferObjects.

Если вы связываете предложения с создаваемой картой постоянного клиента, используя метод insert, или если вы связываете предложения или отменяете их связь с существующей картой постоянного клиента с помощью метода update, для записи данных в linkedOfferIds используйте оставшуюся часть объекта LoyaltyObject в следующем формате:

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

Если для установки или отмены связи предложений с существующей картой постоянного клиента используется метод patch, запрос должен содержать только linkedOfferIds:

{
  "linkedOfferIds": [
    "2945482443380251551.OfferObject1",
    "2945482443380251551.OfferObject2"
  ]
}

Чтобы избежать ошибок при работе с массивами, мы рекомендуем явно указывать, какие предложения нужно добавить, а какие удалить, с помощью метода modifyLinkedOfferObjects, как показано ниже.

{
  "linkedOfferObjectIds" {
    "addLinkedOfferObjectIds": [
      "2945482443380251551.OfferObject1",
      "2945482443380251551.OfferObject2"
    ],
    "removeLinkedOfferObjectIds": [
      "2945482443380251551.OfferObject3",
      "2945482443380251551.OfferObject4"
    ]
  }
}

Внешний вид карты постоянного клиента со связанными предложениями

Связанные предложения отображаются в представлении карты постоянного клиента и расположены между разделом с картой и разделом с подробными сведениями, как показано ниже. В карусели можно показывать не более пяти связанных предложений. Если с картой постоянного клиента связано больше предложений, пользователь может посмотреть их, нажав кнопку Ещё в конце карусели.

Если нажать на связанное предложение, оно будет показано с использованием упрощенного шаблона.

Настройка уведомлений с учетом местоположения

Сервисы Google могут активировать уведомления в зависимости от объектов, которые сохранил клиент, и расстояния до указанного вами адреса.

Информацию о местоположении можно добавить двумя способами.

1. При создании аккаунта Google Pay API for Passes Merchant Center используется информация о местоположении из Google Карт.
2. Координаты можно добавить в объект или класс, используя REST API.

Инструкции о добавлении координат в объекты или классы находятся в разделе Использование REST API для добавления информации о местоположении.

Концепция геозонирования

Используя алгоритмы и информацию о местоположении из Google Карт, инструменты Google могут определить, когда пользователь находится в магазине или рядом с ним. При этом обнаруживаются любые классы и объекты, созданные с использованием аккаунта Google Pay API for Passes Merchant Center.

Алгоритм учитывает данные GPS, Wi-Fi, Bluetooth, информацию о передвижении и времени остановок, а также другие факторы. Когда пользователь находится рядом с определенным адресом, активируется уведомление с учетом местоположения.

Если координаты были введены в Object вручную, уведомление с учетом местоположения активируется на расстоянии 150 метров от нужного места.

Частота уведомлений и учет предпочтений пользователя

Пользователь может получить не более четырех уведомлений в день.

Если в геозоне находится несколько сохраненных объектов, отображается одно уведомление с каруселью (на каждый аккаунт Google Pay API for Passes Merchant Center). Обнаруженные места можно просматривать по отдельности.

Чтобы получать уведомления с учетом местоположения, пользователь должен включить геолокацию на устройстве и Обновления о картах и билетах в настройках уведомлений приложения Google Pay.

Использование REST API для добавления информации о местоположении

Вы можете задать несколько местоположений (значений широты и долготы) в классах и объектах. Сервисы Google сверяют текущее местоположение устройства со списком мест, связанных с классом или объектом, и отправляют уведомление пользователю в тот момент, когда он находится в 150 метрах от нужного адреса. Ниже приведены примеры кода, в которых показано, как можно задать местоположения в классах и объектах.

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

Действия с картами, у которых истек срок действия

На вкладке "Карты" в приложении Google Pay есть раздел "Истек срок действия". В нем собраны билеты, карты и посадочные талоны, которые были помещены в архив или стали неактивны. Карты перемещаются в этот раздел, если верно хотя бы одно из следующих условий:

• Истек срок, указанный в object.validTimeInterval.end.date. Карта перемещается в раздел "Истек срок действия" в течение 24 часов после даты, указанной в object.validTimeInterval.end.date.
• Для object.state указано одно из следующих значений: Expired, Inactive или Completed.

Создание ссылки на сохраненную карту постоянного клиента

Чтобы создать ссылку на сохраненную карту постоянного клиента, нужно добавить в нее идентификатор objectId.

Используйте следующий шаблон:

https://pay.google.com/gp/v/object/{<issuerId>}.{<ObjectId>}

Карту постоянного клиента можно будет открыть в приложении Google Pay и в браузере.

Добавление к сохраненной карте ссылки на стороннее приложение или сайт

Вы можете добавить ссылку на свой сайт или приложение непосредственно на карту постоянного клиента. Ссылка будет отображаться в Google Pay под названием карты, к которой она относится. Эта функция доступна для всех типов карт и билетов Google Pay.

Как запросить доступ

Запросить доступ к функции можно через эту форму. При этом следует помнить следующее:

• В форме вам нужно указать ваш идентификатор эмитента.
• В поле Issue type (Тип проблемы) следует выбрать вариант Technical/API Integration (Технические проблемы/интеграция с API).
• Далее выберите Link your app or website below the Google Pay pass (Ссылка на сайт или приложение под картой в Google Pay).

Как добавить ссылку

URI приложения или сайта указывается в appLinkData для определенной карты Google Pay. URI можно добавлять в любом формате, но мы рекомендуем использовать динамическую ссылку.

Посмотрите пример кода ниже. В нем приводится формат и контекст для appLinkData.

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

Регистрация и аутентификация

При подключенной функции регистрации и аутентификации в программах лояльности пользователи могут находить и добавлять новые или уже существующие карты постоянного клиента в Google Pay. Более подробная информация приводится здесь.