多元化交易

總覽

請參閱本指南，瞭解如何將地點與特定商家進行比對，以及如何顯示商家詳細資訊。

如果交易明細使用「ACMEHCORP」這類縮寫，客戶可能難以理解。這可能會導致爭議費用，並增加支援成本。建議您提供完整的商家名稱，例如 Acme Housewares。

「多元化交易」可讓您輕鬆提供直覺式的交易資訊，包括商家全名、業務類別、店面圖片，以及聯絡資訊和地點詳細資料。這不但能提升資訊透明度、提高淨推薦值 (NPS)，還能吸引使用者在應用程式內停留更長時間。

行動裝置畫面範例，比較原始交易對帳單和豐富的商家詳細資料
「多元化交易」範例畫面 (按一下即可放大)

啟用 API

如要導入「多元化交易」，請在 Google Cloud 控制台中啟用下列 API。請透過以下連結前往 Google Cloud 控制台，選取所需專案以逐一啟用各個 API：

如要進一步瞭解設定，請參閱「開始使用 Google 地圖平台」一文。

導入指南章節

本指南涵蓋下列導入和自訂項目：

將商家與 Google 地圖平台進行比對 將交易記錄中的商家與 Google 地圖平台中的地點建立關聯。
顯示商家詳細資料 顯示多元化資料的交易，內含與商家相關的實用資訊，方便顧客快速辨識交易。
新增商家地點的地圖 新增商家地點的地圖，並加上進階標記。

將商家與 Google 地圖平台進行比對

此範例使用： Places API (新版) 同時支援： JavaScript

下圖說明應用程式如何使用現有商家資料庫的 Place Details 或透過 Text Search 要求，比對商家交易並傳回結果：

比對商家交易記錄與地點 ID 和地點詳細資料的流程圖
商家比對流程矩陣 (按一下可放大)

取得 Google Maps Platform 地點 ID

您可能已建有商家資料庫，內有商家名稱及地址等基本資訊。如要取得 Google 地圖平台內的地點資訊 (包括聯絡資料和顧客提供的評分)，請找出資料庫中各商家對應的地點 ID。

如要取得商家的地點 ID，請在 Places API (新版) 中呼叫 Text Search (新版) 端點，並在欄位遮罩中只要求 places.id 欄位，這樣就會觸發 Text Search Essentials (僅限 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 當成商家記錄屬性，無限期儲存於資料庫中。您只需要為每個商家執行一次 Text Search (New) 要求，也可以在顧客要求交易明細時搜尋地點 ID。

為確保儲存的地點 ID 準確無誤，請每 12 個月重新整理地點 ID，方法是提出 Place Details (新版) 要求，且只指定欄位遮罩中的 id 欄位。

如果顯示的 Place Details 與顧客完成交易的商家不符，Google 建議您允許顧客就商家比對的品質提出意見。

顯示商家詳細資料

此範例使用： Places API (新版) 同時支援： Places SDK for Android | Places SDK for iOS | Maps JavaScript API 的 Places Library

您可以在顧客造訪商家地點後，向他們提供必要的 Place Details。呼叫 Places API (新版) 的 Place Details (新版) 端點後，您可以在資訊視窗、網頁側欄或行動裝置詳細資料檢視畫面中，篩選及算繪回應，但須遵守《Google 地圖平台服務條款》的限制。

行動裝置交易明細檢視畫面，顯示商家名稱、地址、地圖和聯絡資料
商家詳細資料畫面範例 (按一下即可放大)

如要向 Place Details 端點發出要求，您需要每個地點的地點 ID。請參閱「取得 Google 地圖平台地點 ID」一文，瞭解如何擷取商家地點的地點 ID。

以下 Place Details (新版) 要求會以 JSON 格式，傳回 Google 臺北 101 地點 ID 的顯示名稱、格式化地址、座標、網站、電話號碼、圖示、營業時間和評分：

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",
  ],
});

新增商家地點的地圖

此範例使用： Maps JavaScript API | Geocoding API | Maps Static API 同時支援： Android | iOS

判斷商家地點

您可以使用地點詳細資料中的地理座標，在地圖上放置標記。如果商家資料庫有街道地址，但沒有地理座標，且您不要求提供 Place Details，則可使用 Geocoding API，在伺服器端將街道地址轉換為經緯度座標，再將這些座標儲存於資料庫，並至少每 30 天更新一次。

以下範例使用 Geocoding API 取得 Google 臺北辦公室地點 ID 的經緯度：

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

在網頁地圖中新增進階標記

顧客查看地圖是為了確認交易，而不是要瀏覽或導航，因此請設定互動性有限的地圖，並在商家位置放置進階標記。進階標記需要地圖 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，便可依地點詳細資料中的座標放置進階標記。

顧客查看地圖是為了確認交易，而不是要瀏覽或導航，因此請設定互動性有限的地圖：