Дополненные транзакции

Обзор

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

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

Дополненные транзакции позволяют показывать полное название компании-продавца, вид ее деятельности, фотографию магазина, контактную информацию и адрес. Это повышает прозрачность, улучшает индекс потребительской лояльности (NPS) и увеличивает время, которое пользователи проводят в вашем приложении.

Как включить API

Чтобы реализовать дополненные транзакции, необходимо включить в консоли Google Cloud указанные ниже API. Следующие ссылки позволяют перейти на страницы консоли Google Cloud, где можно включить эти API для выбранного проекта:

• Places API (New)
• Geocoding API
• Maps JavaScript API, Maps Static API, Maps SDK для Android или Maps SDK для iOS

Подробная информация приведена в статье Начало работы с платформой Google Карт.

Разделы руководства по внедрению

В этом руководстве рассматриваются следующие варианты реализации и настройки:

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

Как получить идентификаторы мест для платформы Google Карт

Возможно, у вас есть база данных с основными сведениями о продавцах, такими как название и адрес. Платформа Google Карт также содержит определенную информацию о местах, в том числе контактные данные и добавленные пользователями оценки. Чтобы получить эту информацию, необходимо указать идентификатор места на платформе Google Карт, присвоенный продавцу из вашей базы данных.

Чтобы получить идентификатор места, соответствующий компании, отправьте запрос в конечную точку Places API (New) Text Search (New). В маске полей запросите только поле places.id, чтобы вызов был бесплатным. Если у продавца несколько филиалов, то помимо названия продавца укажите город или улицу. Проверьте, соответствуют ли результаты продавцу.

Например, так запрашивается идентификатор места для офиса Google в Тайбэе по названию продавца и городу:

curl -X POST -d '{
  "textQuery" : "Google Taipei"
}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: places.id' \
'https://places.googleapis.com/v1/places:searchText'

Сохранение идентификаторов мест

Вы можете сохранить идентификатор места из платформы Google Карт в своей базе данных в качестве атрибута записи о продавце. Вам нужно выполнить запрос текстового поиска (New) только один раз для каждого продавца. Также вы можете искать идентификатор места каждый раз, когда пользователь запрашивает сведения о транзакции.

Чтобы поддерживать актуальность информации в своей базе данных, обновляйте идентификаторы мест каждые 12 месяцев с помощью запроса информации о месте (нового), в маске полей которого указано только поле id.

Если информация о местах, которую вы показываете, не соответствует продавцу, у которого клиент совершил транзакцию, Google рекомендует разрешить клиентам отправлять отзывы о качестве соответствия продавца.

Вы можете предоставлять пользователям информацию о местах, которая им нужна после посещения офиса или магазина продавца. Вызвав конечную точку информации о местах (New) в Places API (New), вы можете отфильтровать ответ и показать результат в информационном окне, на боковой панели или другим способом в соответствии с Условиями использования платформы Google Карт.

Чтобы отправить запрос к конечной точке Place Details, вам потребуется идентификатор каждого места. Подробнее о том, как получить идентификаторы мест для платформы Google Карт…

Следующий запрос Place Details (New) возвращает отображаемое название, отформатированный адрес, координаты, URL сайта, номер телефона, значок, часы работы и оценку тайбэйского офиса Google в формате JSON:

curl -X GET -H 'Content-Type: application/json' \
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: displayName,formattedAddress,location,websiteUri,nationalPhoneNumber,iconMaskBaseUri,regularOpeningHours,rating' \
'https://places.googleapis.com/v1/places/ChIJraeA2rarQjQRyAqIxkx2vN8'

Если вы создаете веб-приложение с помощью Maps JavaScript API, то можете использовать класс Place, чтобы получать те же поля на стороне клиента:

const place = new google.maps.places.Place({
  id: "ChIJraeA2rarQjQRyAqIxkx2vN8",
});

await place.fetchFields({
  fields: [
    "displayName",
    "formattedAddress",
    "location",
    "websiteURI",
    "nationalPhoneNumber",
    "regularOpeningHours",
    "rating",
  ],
});

Определение местоположения продавца

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

В этом примере мы с помощью Geocoding API получаем широту и долготу по идентификатору места для офиса Google в Тайбэе:

```html
https://maps.googleapis.com/maps/api/geocode/json?place_id=ChIJraeA2rarQjQRyAqIxkx2vN8&key=YOUR_API_KEY
```

Как добавить расширенный маркер на веб-карту

Поскольку пользователи просматривают карту для подтверждения транзакций, а не для поиска или навигации, настройте карту с ограниченной интерактивностью и разместите расширенный маркер в месте нахождения продавца. Для работы с расширенными маркерами требуется идентификатор карты и библиотека marker (libraries=marker).

Сначала загрузите Maps JavaScript API с помощью libraries=marker и добавьте контейнер div для карты:

<script defer src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=marker&callback=initMap"></script>
<div id="map" style="height: 300px; width: 100%;"></div>

Затем инициализируйте карту с помощью gestureHandling: "none" и zoomControl: false, чтобы ограничить интерактивность, укажите mapId и создайте google.maps.marker.AdvancedMarkerElement с координатами продавца:

function initMap() {
  const merchantLocation = { lat: 25.033976, lng: 121.5645389 };
  const map = new google.maps.Map(document.getElementById("map"), {
    center: merchantLocation,
    zoom: 16,
    mapId: "DEMO_MAP_ID",
    gestureHandling: "none",
    zoomControl: false,
  });

  new google.maps.marker.AdvancedMarkerElement({
    map,
    position: merchantLocation,
    title: "Google Taipei",
  });
}

Вы также можете настроить расширенные маркеры, изменив цвет фона, контура или глифа маркера или добавив собственное графическое изображение для категории продавца.

Как добавить статическое изображение карты

Если вы предпочитаете неинтерактивное изображение карты для компьютеров или мобильных устройств, создайте URL Maps Static API с одним маркером по адресу или координатам продавца. Maps Static API возвращает изображение карты с указанными параметрами.

Следующий запрос возвращает дорожную карту размером 640 x 480 пикселей, центрированную по красному маркеру тайбэйского офиса Google, с облачным стилем карты:

```html
https://maps.googleapis.com/maps/api/staticmap?size=640x480&markers=color:red%7C25.033976%2C121.5645389&map_id=b224095f76859890&key=YOUR_API_KEY&signature=BASE64_SIGNATURE
```

В таблице ниже описаны все разделы запроса.

В результате запроса создается следующее изображение статической карты:

Позицию маркера также можно задать с помощью адреса:

```html
https://maps.googleapis.com/maps/api/staticmap?size=640x480&markers=color:green%7CTaipei%20101%20Tower%2CNo.%207信義路五段信義區台北市%20Taiwan%20110&map_id=b224095f76859890&key=YOUR_API_KEY&signature=BASE64_SIGNATURE
```

Полный список параметров доступен в документации Maps Static API.

Добавление карты в мобильное приложение

Если вы используете Maps SDK для Android или Maps SDK для iOS, вы можете поставить расширенный маркер по координатам, полученным с помощью запроса информации о месте.

Поскольку пользователи не будут ничего искать на карте (она нужна только для того, чтобы увидеть место транзакции), выберите карту с ограниченными интерактивными функциями.

• Для приложений для Android см. Расширенные маркеры для Android и Добавление карты с маркером, а также включите упрощенный режим, чтобы обеспечить ограниченную интерактивность.
• Для iOS: следуйте инструкциям по добавлению расширенных маркеров и добавлению карты с маркером, а также отключите элементы управления и жесты с помощью класса GMSUISettings.