增强型交易

概览

通过本指南，您可以了解如何将营业地点与特定商家进行匹配，以及如何显示商家的详细信息。

如果您发出“ACMEHCORP”等缩写的交易语句，客户可能会觉得难以理解。这可能会导致扣款争议，并增加您的支持成本。最好提供完整的商家名称，例如 Acme Housewares。

借助增强型交易，您可以更轻松地提供直观的交易信息，包括商家的全称、业务类别、店面图片以及联系信息和位置信息。这不仅可以提高透明度，提升净推荐值 (NPS)，还能让用户在您的应用中停留更长时间。

对比原始交易对账单与增强型商家详情的移动设备屏幕示例
增强型交易示例屏幕（点击可放大）

启用 API

若要实现增强型交易，您必须在 Google Cloud 控制台中启用以下 API。您可以通过以下链接打开 Google Cloud 控制台，为您选择的项目启用各个 API：

如需详细了解设置方法，请参阅 Google Maps Platform 使用入门。

实现指南的各个部分

本指南涵盖以下实现方法和自定义设置：

使用 Google Maps Platform 匹配商家 将交易记录中的商家与 Google Maps Platform 中的地点相关联。
显示商家详情 显示包含丰富数据的交易，其中会提供商家的相关实用信息，以便客户快速识别交易。
添加商家营业地点地图 添加带有高级标记的商家营业地点地图。

使用 Google Maps Platform 匹配商家

此示例使用：Places API（新版） 同样适用于：JavaScript

以下流程图展示了您的应用如何使用现有商家数据库中的地点详情或通过文本搜索请求对商家交易进行匹配，从而返回相关结果：

将商家交易记录与地点 ID 和地点详情进行匹配的流程图
商家匹配流程矩阵（点击可放大）

获取 Google Maps Platform 地点 ID

您可能会有一个包含商家名称和商家地址等基本信息的商家数据库。若要从 Google Maps Platform 中获取此地点的相关信息（包括详细联系信息和客户贡献的评分），请在您的数据库中查找每个商家对应的地点 ID。

若要获取商家所对应的地点 ID，请在 Places API（新版）中调用文本搜索（新版）端点，并仅在字段掩码中请求 places.id 字段，这会触发文本搜索基础版（仅 ID）SKU。如果商家有多个营业地点，请在查询中同时包含城市或街道名称以及商家名称。验证返回的结果，确认其与商家匹配。

以下示例使用商家名称和城市请求 Google 台北办事处的地点 ID：

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'

存储地点 ID

若要存储 Google Maps Platform 中的商家相关信息以用于将来的请求，您可以在数据库中无限期存储地点 ID，将其作为商家记录的一种属性。您只需为每个商家运行一次文本搜索（新版）请求，也可以在客户请求交易详情时搜索地点 ID。

为确保您存储的地点 ID 准确无误，请每 12 个月刷新一次地点 ID，方法是发出地点详情（新版）请求，并在字段掩码中仅指定 id 字段。

如果您显示的地点详情与客户完成交易的商家不匹配，Google 建议您允许客户就商家匹配质量提交反馈。

显示商家详情

此示例使用：Places API（新版） 同样适用于：Places SDK for Android | Places SDK for iOS | Maps JavaScript API 地点库

在客户前往商家营业地点之后，您可以分享客户需要的地点详情。在 Places API（新版）中调用地点详情（新版）端点后，您可以在 Google Maps Platform 服务条款的限制范围内，通过信息窗口、网页边栏或移动端详情视图过滤并呈现响应结果。

移动端交易详情视图，其中显示了商家名称、地址、地图和详细联系信息
商家详情示例屏幕（点击可放大）

如需向地点详情端点发出请求，您需要每个营业地点的地点 ID。请参阅获取 Google Maps Platform 地点 ID，检索商家营业地点的地点 ID。

以下“地点详情（新版）”请求会针对 Google 台北 101 地点 ID 以 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 构建 Web 应用，还可以使用 Place 类在客户端提取相同的字段：

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

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

添加商家营业地点地图

此示例使用的是：Maps JavaScript API | Geocoding API | Maps Static API 同样适用于：Android | iOS

确定商家营业地点

您可以使用地点详情中的地理坐标在地图上放置标记。如果您的商家数据库包含街道地址但没有地理坐标，并且您不请求地点详情，则可以使用 Geocoding API 在服务器端将街道地址转换为经纬度坐标，将这些坐标存储在数据库中，并至少每 30 天刷新一次。

以下示例使用 Geocoding API 获取 Google 台北办事处地点 ID 的经纬度：

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

在 Web 地图上添加高级标记

由于客户会查看地图来确认交易，而不是浏览或导航，因此请将地图配置为具有一定可交互性，并在商家的位置放置高级标记。高级标记需要地图 ID 和 marker 库 (libraries=marker)。

首先，使用 libraries=marker 加载 Maps JavaScript API，并为地图添加容器 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",
  });
}

您还可以自定义高级标记，方法是更改图钉背景、边框或字形颜色，或者为商家的类别提供自定义图形图片。

添加静态地图图片

如果您希望在桌面版网站或移动网站上显示非互动式地图图片，请创建 Maps Static API 网址并将一个标记放置在商家的纬度和经度坐标或地址处。Maps Static API 会根据您指定的参数返回地图的图片版本。

以下请求会返回一个尺寸为 640x480 像素的路线图，该图以放置在 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
```

下表介绍了请求的各个部分：

API 网址 https://maps.googleapis.com/maps/api/staticmap?
图片尺寸 size=640x480
商家营业地点标记（使用网址编码） markers=color:red%7C25.033976%2C121.5645389
云端地图样式 map_id=b224095f76859890
API 密钥 key=YOUR_API_KEY
数字签名（了解如何对请求进行数字签名） signature=BASE64_SIGNATURE

该请求会生成以下静态地图图片：

以 Google 台北办事处为中心且带有红色位置标记的地图

您也可以传递地址作为标记位置：

```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 for Android 或 Maps SDK for iOS，则可以根据地点详情中的坐标来放置高级标记。

由于客户会查看地图来确认交易，而不是浏览或导航，因此请配置具有一定互动性的地图。