Transaksi yang Diperkaya

Ringkasan

Gunakan panduan ini untuk mempelajari cara mencocokkan lokasi dengan penjual tertentu dan menampilkan informasi penjual yang mendetail.

Saat Anda menerbitkan laporan transaksi yang disingkat seperti "ACMEHCORP", pelanggan Anda mungkin akan kesulitan memahaminya. Hal ini dapat menyebabkan tagihan yang disengketakan dan biaya dukungan tambahan untuk Anda. Sebagai gantinya, sebaiknya berikan nama penjual lengkap, seperti Acme Housewares.

Transaksi yang Diperkaya memudahkan Anda memberikan informasi transaksi yang intuitif, termasuk nama lengkap penjual, kategori bisnis, gambar muka bangunan, serta detail kontak dan lokasi. Hal ini meningkatkan transparansi, meningkatkan Skor Promotor Bersih (NPS), dan menghasilkan lebih banyak waktu yang dihabiskan di aplikasi Anda.

Contoh layar seluler yang membandingkan laporan transaksi mentah dengan detail penjual yang diperkaya
Layar contoh transaksi yang diperkaya (klik untuk memperbesar)

Mengaktifkan API

Untuk menerapkan Transaksi yang Diperkaya, Anda harus mengaktifkan API berikut di Konsol Google Cloud. Link berikut akan membuka Konsol Google Cloud sehingga Anda dapat mengaktifkan setiap API untuk project yang dipilih:

Untuk informasi selengkapnya tentang penyiapan, lihat artikel Memulai Google Maps Platform.

Bagian panduan penerapan

Penerapan dan penyesuaian berikut dibahas dalam panduan ini:

Mencocokkan penjual melalui Google Maps Platform Mengaitkan penjual dalam histori transaksi dengan tempat di Google Maps Platform.
Menampilkan detail penjual Tampilkan transaksi dengan data lengkap yang menunjukkan informasi berguna tentang penjual, sehingga pelanggan dapat mengenali transaksi dengan cepat.
Menambahkan peta lokasi penjual Tambahkan peta lokasi penjual dengan penanda lanjutan.

Mencocokkan penjual melalui Google Maps Platform

Contoh ini menggunakan: Places API (New) Juga tersedia: JavaScript

Diagram alir berikut menunjukkan cara aplikasi Anda mencocokkan transaksi penjual untuk menampilkan hasil menggunakan detail tempat dari database penjual yang ada atau melalui permintaan Text Search:

Diagram alir untuk mencocokkan data transaksi penjual dengan ID tempat dan detail tempat
Matriks alur pencocokan penjual (klik untuk memperbesar)

Mendapatkan ID tempat Google Maps Platform

Anda mungkin memiliki database penjual dengan informasi dasar seperti nama bisnis dan alamatnya. Untuk mendapatkan informasi yang dimiliki Google Maps Platform tentang tempat tersebut, termasuk detail kontak dan rating dari pelanggan, temukan ID tempat yang sesuai dengan setiap penjual di database Anda.

Agar dapat memperoleh ID tempat untuk bisnis, buat panggilan ke endpoint Text Search (New) di Places API (New) dan minta hanya kolom places.id di mask kolom, yang akan memicu SKU Text Search Essentials (IDs Only). Jika penjual memiliki beberapa lokasi, sertakan nama kota atau jalan bersama nama penjual dalam kueri Anda. Validasi hasil yang ditampilkan untuk mengonfirmasi bahwa hasil tersebut cocok dengan penjual.

Contoh berikut meminta ID tempat untuk kantor Google Taipei menggunakan nama penjual dan kota:

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'

Menyimpan ID tempat

Untuk menyimpan informasi dari Google Maps Platform tentang penjual untuk permintaan mendatang, Anda dapat menyimpan ID tempat tanpa batas waktu di database sebagai atribut data penjual. Anda hanya perlu menjalankan permintaan Text Search (New) sekali untuk setiap penjual, atau Anda dapat menelusuri ID tempat setiap kali pelanggan meminta detail transaksi.

Agar ID tempat yang Anda simpan tetap akurat, perbarui ID tempat setiap 12 bulan dengan membuat permintaan Place Details (New) yang hanya menentukan kolom id di mask kolom.

Jika Place Details yang Anda tampilkan tidak cocok dengan penjual tempat pelanggan menyelesaikan transaksi, Google merekomendasikan agar pelanggan mengirimkan masukan tentang kualitas kecocokan penjual.

Menampilkan detail penjual

Contoh ini menggunakan: Places API (New) Juga tersedia: Places SDK for Android | Places SDK for iOS | Places Library, Maps JavaScript API

Anda dapat membagikan detail tempat yang dibutuhkan pelanggan setelah mereka mengunjungi lokasi penjual. Setelah memanggil endpoint Place Details (New) di Places API (New), Anda dapat memfilter dan merender respons di jendela info, sidebar web, atau tampilan detail seluler dalam batas Persyaratan Layanan Google Maps Platform.

Tampilan detail transaksi seluler yang menampilkan nama, alamat, peta, dan detail kontak penjual
Layar contoh detail penjual (klik untuk memperbesar)

Untuk mengirim permintaan ke endpoint Place Details, Anda memerlukan ID tempat untuk setiap lokasi. Lihat Mendapatkan ID tempat Google Maps Platform untuk mengambil ID tempat lokasi penjual.

Permintaan Place Details (New) berikut menampilkan nama tampilan, alamat yang diformat, koordinat, situs, nomor telepon, ikon, jam buka, dan rating dalam format JSON untuk ID tempat Google Taipei 101:

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'

Jika Anda membangun aplikasi web dengan Maps JavaScript API, Anda juga dapat menggunakan class Place untuk mengambil kolom yang sama di klien:

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

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

Menambahkan peta lokasi penjual

Contoh ini menggunakan: Maps JavaScript API | Geocoding API | Maps Static API Juga tersedia: Android | iOS

Menentukan lokasi penjual

Anda dapat menempatkan penanda di peta menggunakan koordinat geografis dari detail tempat. Jika database penjual Anda memiliki alamat tanpa koordinat geografis dan Anda tidak meminta detail tempat, Anda dapat menggunakan Geocoding API untuk mengonversi alamat menjadi koordinat lintang dan bujur di sisi server, menyimpan koordinat tersebut di database, dan memperbaruinya setidaknya sekali setiap 30 hari.

Contoh berikut menggunakan Geocoding API untuk mendapatkan lintang dan bujur ID tempat kantor Google Taipei:

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

Menambahkan penanda lanjutan di peta web

Karena pelanggan melihat peta untuk mengonfirmasi transaksi, bukan melihat-lihat atau bernavigasi, konfigurasikan peta Anda dengan interaktivitas terbatas dan tempatkan penanda lanjutan di lokasi penjual. Penanda lanjutan memerlukan ID peta dan library marker (libraries=marker).

Pertama, muat Maps JavaScript API dengan libraries=marker dan tambahkan penampung div untuk peta:

<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>

Selanjutnya, lakukan inisialisasi peta dengan gestureHandling: "none" dan zoomControl: false untuk membatasi interaktivitas, berikan mapId, dan buat google.maps.marker.AdvancedMarkerElement di koordinat penjual:

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

Anda juga dapat menyesuaikan penanda lanjutan dengan mengubah warna pin, batas, atau glyph, atau dengan memberikan gambar grafis kustom untuk kategori penjual.

Menambahkan gambar peta statis

Jika Anda lebih memilih gambar peta non-interaktif untuk desktop atau web seluler, buat URL Maps Static API dengan satu penanda pada koordinat lintang dan bujur atau alamat penjual. Maps Static API menampilkan peta versi foto menggunakan parameter yang Anda tentukan.

Permintaan berikut menampilkan peta jalan dengan ukuran 640x480 piksel, yang berpusat pada penanda merah di kantor Google Taipei dengan gaya visual peta berbasis cloud:

```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
```

Tabel berikut menjelaskan setiap bagian permintaan:

URL API https://maps.googleapis.com/maps/api/staticmap?
Ukuran gambar size=640x480
Penanda lokasi penjual (menggunakan encoding URL) markers=color:red%7C25.033976%2C121.5645389
Gaya peta berbasis Cloud map_id=b224095f76859890
Kunci API key=YOUR_API_KEY
Tanda tangan digital (pelajari cara menandatangani permintaan Anda secara digital) signature=BASE64_SIGNATURE

Permintaan ini menghasilkan gambar peta statis berikut:

Peta yang berpusat di kantor Google Taipei dengan penanda lokasi berwarna merah

Anda juga dapat meneruskan alamat sebagai lokasi penanda:

```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
```

Untuk opsi parameter tambahan, lihat dokumentasi Maps Static API.

Menambahkan peta di aplikasi seluler

Jika menggunakan Maps SDK for Android atau Maps SDK for iOS, Anda dapat menempatkan penanda lanjutan menggunakan koordinat dari Place Details.

Karena pelanggan melihat peta untuk mengonfirmasi transaksi, bukan melihat-lihat atau bernavigasi, konfigurasikan peta dengan interaktivitas terbatas: