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.

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:

• Places API (Baru)
• Geocoding API
• Maps JavaScript API, Maps Static API, Maps SDK for Android, atau Maps SDK for iOS

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

Bagian panduan penerapan

Penerapan dan penyesuaian berikut dibahas dalam panduan ini:

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:

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.

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.

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

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:

Permintaan ini menghasilkan gambar peta statis berikut:

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:

• Untuk aplikasi Android, lihat Penanda lanjutan untuk Android dan Menambahkan peta dengan penanda, serta aktifkan Mode Ringan untuk memberikan interaktivitas terbatas.
• Untuk aplikasi iOS, lihat Penanda lanjutan untuk iOS dan Menambahkan peta dengan penanda, serta menonaktifkan kontrol dan gestur dengan class GMSUISettings.