API dữ liệu của Place Autocomplete cho phép bạn tìm nạp thông tin dự đoán về địa điểm theo phương thức lập trình, để tạo trải nghiệm tự động hoàn thành tuỳ chỉnh với mức độ kiểm soát cao hơn so với tiện ích tự động hoàn thành. Trong hướng dẫn này, bạn sẽ tìm hiểu cách sử dụng API dữ liệu của tính năng Place Autocomplete để đưa ra yêu cầu tự động hoàn thành dựa trên cụm từ tìm kiếm của người dùng.
Ví dụ sau đây cho thấy một quy trình tích hợp tính năng tự động hoàn thành đơn giản. Nhập cụm từ tìm kiếm, chẳng hạn như "pizza" hoặc "poke", sau đó nhấp để chọn kết quả bạn muốn.
Yêu cầu tự động hoàn thành
Yêu cầu tự động hoàn thành sẽ lấy một chuỗi đầu vào của cụm từ tìm kiếm và trả về danh sách các cụm từ gợi ý về địa điểm. Để
gửi yêu cầu tự động hoàn thành, hãy gọi fetchAutocompleteSuggestions()
và truyền một yêu cầu có các thuộc tính cần thiết. Thuộc tính input chứa chuỗi cần tìm kiếm; trong một ứng dụng thông thường, giá trị này sẽ được cập nhật khi người dùng nhập cụm từ tìm kiếm. Yêu cầu phải bao gồm sessionToken, được dùng cho mục đích thanh toán.
Đoạn mã sau đây cho thấy cách tạo nội dung yêu cầu và thêm mã thông báo phiên, sau đó gọi fetchAutocompleteSuggestions() để lấy danh sách PlacePrediction.
// Add an initial request body. const request = { input: 'Tadi', locationRestriction: { west: -122.44, north: 37.8, east: -122.39, south: 37.78, }, origin: { lat: 37.7893, lng: -122.4039 }, includedPrimaryTypes: ['restaurant'], language: 'en-US', region: 'us', }; // Create a session token. const token = new AutocompleteSessionToken(); // Add the token to the request. request.sessionToken = token;
Hạn chế cụm từ gợi ý của tính năng tự động hoàn thành
Theo mặc định, Place Autocomplete sẽ hiển thị tất cả các loại địa điểm, ưu tiên các cụm từ gợi ý gần vị trí của người dùng và tìm nạp tất cả các trường dữ liệu có sẵn cho địa điểm mà người dùng đã chọn. Đặt các tuỳ chọn của tính năng Tự động hoàn thành địa điểm để đưa ra cụm từ gợi ý phù hợp hơn bằng cách hạn chế hoặc ưu tiên kết quả.
Việc hạn chế kết quả sẽ khiến tiện ích Tự động hoàn thành bỏ qua mọi kết quả nằm ngoài khu vực hạn chế. Một phương pháp phổ biến là giới hạn kết quả trong ranh giới bản đồ. Việc thiên vị kết quả sẽ khiến tiện ích Tự động hoàn thành hiển thị kết quả trong khu vực được chỉ định, nhưng một số kết quả trùng khớp có thể nằm ngoài khu vực đó.
Sử dụng thuộc tính origin để chỉ định điểm xuất phát để tính khoảng cách trắc địa đến điểm đến. Nếu bạn bỏ qua giá trị này, khoảng cách sẽ không được trả về.
Sử dụng thuộc tính includedPrimaryTypes để chỉ định tối đa 5 loại địa điểm.
Nếu bạn không chỉ định loại nào, thì hệ thống sẽ trả về địa điểm thuộc mọi loại.
Lấy thông tin chi tiết về địa điểm
Để trả về một đối tượng Place từ kết quả dự đoán địa điểm, trước tiên, hãy gọi toPlace(), sau đó gọi fetchFields() trên đối tượng Place thu được (mã phiên từ kết quả dự đoán địa điểm sẽ tự động được đưa vào). Việc gọi fetchFields() sẽ kết thúc phiên tự động hoàn thành.
const place = suggestions[0].placePrediction.toPlace(); // Get first predicted place. await place.fetchFields({ fields: ['displayName', 'formattedAddress'], }); const placeInfo = document.getElementById('prediction'); placeInfo.textContent = `First predicted place: ${place.displayName}: ${place.formattedAddress}`;
Mã thông báo phiên
Mã thông báo phiên nhóm các giai đoạn truy vấn và lựa chọn của một lượt tìm kiếm tự động hoàn thành của người dùng thành một phiên riêng biệt cho mục đích thanh toán. Phiên bắt đầu khi người dùng bắt đầu nhập. Phiên kết thúc khi người dùng chọn một địa điểm và lệnh gọi đến Place Details được thực hiện.
Để tạo mã thông báo phiên mới và thêm mã đó vào yêu cầu, hãy tạo một thực thể của AutocompleteSessionToken, sau đó đặt thuộc tính sessionToken của yêu cầu để sử dụng mã thông báo như trong đoạn mã sau:
// Create a session token. const token = new AutocompleteSessionToken(); // Add the token to the request. request.sessionToken = token;
Một phiên sẽ kết thúc khi fetchFields() được gọi. Sau khi tạo thực thể Place, bạn không cần truyền mã phiên đến fetchFields() vì việc này được xử lý tự động.
await place.fetchFields({ fields: ['displayName', 'formattedAddress'], });
Tạo mã thông báo phiên cho phiên tiếp theo bằng cách tạo một thực thể mới của AutocompleteSessionToken.
Đề xuất về mã thông báo phiên:
- Sử dụng mã thông báo phiên cho tất cả lệnh gọi Place Autocomplete.
- Tạo mã thông báo mới cho mỗi phiên.
- Truyền một mã thông báo phiên riêng biệt cho mỗi phiên mới. Nếu bạn sử dụng cùng một mã thông báo cho nhiều phiên, thì mỗi yêu cầu sẽ được tính phí riêng.
Bạn có thể tuỳ ý bỏ qua mã phiên tự động hoàn thành trong một yêu cầu. Nếu mã phiên bị bỏ qua, thì mỗi yêu cầu sẽ được tính phí riêng, kích hoạt SKU Tự động hoàn thành – Theo yêu cầu. Nếu bạn sử dụng lại mã thông báo phiên, thì phiên đó sẽ được coi là không hợp lệ và các yêu cầu sẽ bị tính phí như thể không có mã thông báo phiên nào được cung cấp.
Ví dụ
Khi người dùng nhập một cụm từ tìm kiếm, yêu cầu tự động hoàn thành sẽ được gọi sau mỗi vài lần nhấn phím (không phải theo từng ký tự) và danh sách các kết quả có thể có sẽ được trả về. Khi người dùng lựa chọn trong danh sách kết quả, lựa chọn đó được tính là một yêu cầu và tất cả các yêu cầu được thực hiện trong quá trình tìm kiếm sẽ được gộp lại và tính là một yêu cầu duy nhất. Nếu người dùng chọn một địa điểm, thì cụm từ tìm kiếm sẽ được cung cấp không tính phí và chỉ yêu cầu về Dữ liệu địa điểm mới bị tính phí. Nếu người dùng không đưa ra lựa chọn trong vòng vài phút kể từ khi bắt đầu phiên, thì chỉ cụm từ tìm kiếm mới bị tính phí.
Từ góc độ của một ứng dụng, luồng sự kiện sẽ diễn ra như sau:
- Người dùng bắt đầu nhập cụm từ tìm kiếm để tìm "Paris, Pháp".
- Khi phát hiện hoạt động đầu vào của người dùng, ứng dụng sẽ tạo một mã phiên mới, "Mã thông báo A".
- Khi người dùng nhập, API sẽ đưa ra yêu cầu tự động hoàn thành sau mỗi vài ký tự, hiển thị danh sách kết quả tiềm năng mới cho mỗi ký tự:
"P"
"Par"
"Paris,"
"Paris, Fr"
- Khi người dùng đưa ra lựa chọn:
- Tất cả yêu cầu từ cụm từ tìm kiếm đều được nhóm lại và thêm vào phiên được biểu thị bằng "Mã thông báo A" dưới dạng một yêu cầu duy nhất.
- Lựa chọn của người dùng được tính là một yêu cầu Place Details và được thêm vào phiên hoạt động do "Mã thông báo A" đại diện.
- Phiên kết thúc và ứng dụng sẽ loại bỏ "Mã thông báo A".
Mã ví dụ hoàn chỉnh
Phần này có các ví dụ hoàn chỉnh cho thấy cách sử dụng Place Autocomplete Data API .Cụm từ gợi ý của tính năng tự động hoàn thành địa điểm
Ví dụ sau đây minh hoạ cách gọi fetchAutocompleteSuggestions() cho dữ liệu đầu vào "Tadi", sau đó gọi toPlace() trên kết quả dự đoán đầu tiên, rồi gọi fetchFields() để lấy thông tin chi tiết về địa điểm.
TypeScript
async function init() { const { AutocompleteSessionToken, AutocompleteSuggestion } = await google.maps.importLibrary('places'); // Add an initial request body. const request: google.maps.places.AutocompleteRequest = { input: 'Tadi', locationRestriction: { west: -122.44, north: 37.8, east: -122.39, south: 37.78, }, origin: { lat: 37.7893, lng: -122.4039 }, includedPrimaryTypes: ['restaurant'], language: 'en-US', region: 'us', }; // Create a session token. const token = new AutocompleteSessionToken(); // Add the token to the request. request.sessionToken = token; // Fetch autocomplete suggestions. const { suggestions } = await AutocompleteSuggestion.fetchAutocompleteSuggestions(request); const title = document.getElementById('title')!; title.appendChild( document.createTextNode( 'Query predictions for "' + request.input + '":' ) ); const resultsElement = document.getElementById('results')!; for (const suggestion of suggestions) { const placePrediction = suggestion.placePrediction; // Create a new list element. const listItem = document.createElement('li'); listItem.appendChild( document.createTextNode(placePrediction!.text.toString()) ); resultsElement.appendChild(listItem); } const place = suggestions[0].placePrediction!.toPlace(); // Get first predicted place. await place.fetchFields({ fields: ['displayName', 'formattedAddress'], }); const placeInfo = document.getElementById('prediction')!; placeInfo.textContent = `First predicted place: ${place.displayName}: ${place.formattedAddress}`; } void init();
JavaScript
async function init() { const { AutocompleteSessionToken, AutocompleteSuggestion } = await google.maps.importLibrary('places'); // Add an initial request body. const request = { input: 'Tadi', locationRestriction: { west: -122.44, north: 37.8, east: -122.39, south: 37.78, }, origin: { lat: 37.7893, lng: -122.4039 }, includedPrimaryTypes: ['restaurant'], language: 'en-US', region: 'us', }; // Create a session token. const token = new AutocompleteSessionToken(); // Add the token to the request. request.sessionToken = token; // Fetch autocomplete suggestions. const { suggestions } = await AutocompleteSuggestion.fetchAutocompleteSuggestions(request); const title = document.getElementById('title'); title.appendChild( document.createTextNode( 'Query predictions for "' + request.input + '":' ) ); const resultsElement = document.getElementById('results'); for (const suggestion of suggestions) { const placePrediction = suggestion.placePrediction; // Create a new list element. const listItem = document.createElement('li'); listItem.appendChild( document.createTextNode(placePrediction.text.toString()) ); resultsElement.appendChild(listItem); } const place = suggestions[0].placePrediction.toPlace(); // Get first predicted place. await place.fetchFields({ fields: ['displayName', 'formattedAddress'], }); const placeInfo = document.getElementById('prediction'); placeInfo.textContent = `First predicted place: ${place.displayName}: ${place.formattedAddress}`; } void init();
CSS
/* * Always set the map height explicitly to define the size of the div element * that contains the map. */ #map { height: 100%; } /* * Optional: Makes the sample page fill the window. */ html, body { height: 100%; margin: 0; padding: 0; }
HTML
<html>
<head>
<title>Place Autocomplete Data API Predictions</title>
<link rel="stylesheet" type="text/css" href="./style.css" />
<script type="module" src="./index.js"></script>
<script>
// prettier-ignore
(g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
key: "GOOGLE_MAPS_API_KEY"
});
</script>
</head>
<body>
<div id="title"></div>
<ul id="results"></ul>
<p><span id="prediction"></span></p>
<img
class="powered-by-google"
src="./powered_by_google_on_white.png"
alt="Powered by Google" />
</body>
</html>Place Autocomplete trước khi nhập bằng phiên
Ví dụ này minh hoạ các khái niệm sau:
- Gọi
fetchAutocompleteSuggestions()dựa trên cụm từ tìm kiếm của người dùng và hiển thị danh sách các địa điểm được dự đoán để phản hồi. - Sử dụng mã phiên để nhóm một cụm từ tìm kiếm của người dùng với yêu cầu Place Details cuối cùng.
- Truy xuất thông tin chi tiết về địa điểm cho địa điểm đã chọn và hiển thị điểm đánh dấu.
- Sử dụng tính năng lồng ghép thành phần điều khiển để lồng các phần tử trên giao diện người dùng vào phần tử
gmp-map.
TypeScript
const mapElement = document.querySelector('gmp-map')!; let innerMap: google.maps.Map; let marker: google.maps.marker.AdvancedMarkerElement; const titleElement = document.querySelector<HTMLElement>('.title')!; const resultsContainerElement = document.querySelector('.results')!; const inputElement = document.querySelector('input')!; const tokenStatusElement = document.querySelector('.token-status')!; let newestRequestId = 0; let tokenCount = 0; // Create an initial request body. const request: google.maps.places.AutocompleteRequest = { input: '', includedPrimaryTypes: [ 'restaurant', 'cafe', 'museum', 'park', 'botanical_garden', ], }; async function init() { await google.maps.importLibrary('maps'); innerMap = mapElement.innerMap; innerMap.setOptions({ mapTypeControl: false, }); // Update request center and bounds when the map bounds change. innerMap.addListener('bounds_changed', () => { request.locationRestriction = innerMap.getBounds(); request.origin = innerMap.getCenter(); }); inputElement.addEventListener('input', makeAutocompleteRequest); } async function makeAutocompleteRequest(inputEvent: Event) { // To avoid race conditions, store the request ID and compare after the request. const requestId = ++newestRequestId; const { AutocompleteSuggestion } = await google.maps.importLibrary('places'); if (!(inputEvent.target as HTMLInputElement)?.value) { titleElement.textContent = ''; resultsContainerElement.replaceChildren(); return; } // Add the latest char sequence to the request. request.input = (inputEvent.target as HTMLInputElement).value; // Fetch autocomplete suggestions and show them in a list. const { suggestions } = await AutocompleteSuggestion.fetchAutocompleteSuggestions(request); // If the request has been superseded by a newer request, do not render the output. if (requestId !== newestRequestId) return; titleElement.innerText = `Place predictions for "${request.input}"`; // Clear the list first. resultsContainerElement.replaceChildren(); for (const suggestion of suggestions) { const placePrediction = suggestion.placePrediction; if (!placePrediction) { continue; } // Create a link for the place, add an event handler to fetch the place. // We are using a button element to take advantage of its a11y capabilities. const placeButton = document.createElement('button'); placeButton.addEventListener('click', () => { void onPlaceSelected(placePrediction.toPlace()); }); placeButton.textContent = placePrediction.text.toString(); placeButton.classList.add('place-button'); // Create a new list item element. const li = document.createElement('li'); li.appendChild(placeButton); resultsContainerElement.appendChild(li); } } // Event handler for clicking on a suggested place. async function onPlaceSelected(place: google.maps.places.Place) { const { AdvancedMarkerElement } = await google.maps.importLibrary('marker'); await place.fetchFields({ fields: ['displayName', 'formattedAddress', 'location'], }); resultsContainerElement.textContent = `${place.displayName}: ${place.formattedAddress}`; titleElement.textContent = 'Selected Place:'; inputElement.value = ''; await refreshToken(); // Remove the previous marker, if it exists. if (marker) { marker.remove(); } // Create a new marker. marker = new AdvancedMarkerElement({ map: innerMap, position: place.location, title: place.displayName, }); // Center the map on the selected place. if (place.location) { innerMap.setCenter(place.location); innerMap.setZoom(15); } } // Helper function to refresh the session token. async function refreshToken() { const { AutocompleteSessionToken } = await google.maps.importLibrary('places'); // Increment the token counter. tokenCount++; // Create a new session token and add it to the request. request.sessionToken = new AutocompleteSessionToken(); tokenStatusElement.textContent = `Session token count: ${tokenCount}`; } void init();
JavaScript
const mapElement = document.querySelector('gmp-map'); let innerMap; let marker; const titleElement = document.querySelector('.title'); const resultsContainerElement = document.querySelector('.results'); const inputElement = document.querySelector('input'); const tokenStatusElement = document.querySelector('.token-status'); let newestRequestId = 0; let tokenCount = 0; // Create an initial request body. const request = { input: '', includedPrimaryTypes: [ 'restaurant', 'cafe', 'museum', 'park', 'botanical_garden', ], }; async function init() { await google.maps.importLibrary('maps'); innerMap = mapElement.innerMap; innerMap.setOptions({ mapTypeControl: false, }); // Update request center and bounds when the map bounds change. innerMap.addListener('bounds_changed', () => { request.locationRestriction = innerMap.getBounds(); request.origin = innerMap.getCenter(); }); inputElement.addEventListener('input', makeAutocompleteRequest); } async function makeAutocompleteRequest(inputEvent) { // To avoid race conditions, store the request ID and compare after the request. const requestId = ++newestRequestId; const { AutocompleteSuggestion } = await google.maps.importLibrary('places'); if (!inputEvent.target?.value) { titleElement.textContent = ''; resultsContainerElement.replaceChildren(); return; } // Add the latest char sequence to the request. request.input = inputEvent.target.value; // Fetch autocomplete suggestions and show them in a list. const { suggestions } = await AutocompleteSuggestion.fetchAutocompleteSuggestions(request); // If the request has been superseded by a newer request, do not render the output. if (requestId !== newestRequestId) return; titleElement.innerText = `Place predictions for "${request.input}"`; // Clear the list first. resultsContainerElement.replaceChildren(); for (const suggestion of suggestions) { const placePrediction = suggestion.placePrediction; if (!placePrediction) { continue; } // Create a link for the place, add an event handler to fetch the place. // We are using a button element to take advantage of its a11y capabilities. const placeButton = document.createElement('button'); placeButton.addEventListener('click', () => { void onPlaceSelected(placePrediction.toPlace()); }); placeButton.textContent = placePrediction.text.toString(); placeButton.classList.add('place-button'); // Create a new list item element. const li = document.createElement('li'); li.appendChild(placeButton); resultsContainerElement.appendChild(li); } } // Event handler for clicking on a suggested place. async function onPlaceSelected(place) { const { AdvancedMarkerElement } = await google.maps.importLibrary('marker'); await place.fetchFields({ fields: ['displayName', 'formattedAddress', 'location'], }); resultsContainerElement.textContent = `${place.displayName}: ${place.formattedAddress}`; titleElement.textContent = 'Selected Place:'; inputElement.value = ''; await refreshToken(); // Remove the previous marker, if it exists. if (marker) { marker.remove(); } // Create a new marker. marker = new AdvancedMarkerElement({ map: innerMap, position: place.location, title: place.displayName, }); // Center the map on the selected place. if (place.location) { innerMap.setCenter(place.location); innerMap.setZoom(15); } } // Helper function to refresh the session token. async function refreshToken() { const { AutocompleteSessionToken } = await google.maps.importLibrary('places'); // Increment the token counter. tokenCount++; // Create a new session token and add it to the request. request.sessionToken = new AutocompleteSessionToken(); tokenStatusElement.textContent = `Session token count: ${tokenCount}`; } void init();
CSS
/* * Always set the map height explicitly to define the size of the div element * that contains the map. */ gmp-map { height: 100%; } /* * Optional: Makes the sample page fill the window. */ html, body { height: 100%; margin: 0; padding: 0; } .place-button { height: 3rem; width: 100%; background-color: transparent; text-align: left; border: none; cursor: pointer; } .place-button:focus-visible { outline: 2px solid #0056b3; border-radius: 2px; } .input { width: 300px; font-size: small; margin-bottom: 1rem; } /* Styles for the floating panel */ .controls { background-color: #fff; border-radius: 8px; box-shadow: 0 2px 6px rgba(0, 0, 0, 0.3); font-family: sans-serif; font-size: small; margin: 12px; padding: 1rem; } .title { font-weight: bold; margin-top: 1rem; margin-bottom: 0.5rem; } .results { list-style-type: none; margin: 0; padding: 0; } .results li:not(:last-child) { border-bottom: 1px solid #ddd; } .results li:hover { background-color: #eee; }
HTML
<html>
<head>
<title>Place Autocomplete Data API Session</title>
<link rel="stylesheet" type="text/css" href="./style.css" />
<script type="module" src="./index.js"></script>
<script>
// prettier-ignore
(g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
key: "GOOGLE_MAPS_API_KEY"
});
</script>
</head>
<body>
<gmp-map center="37.7893, -122.4039" zoom="12" map-id="DEMO_MAP_ID">
<div class="controls" slot="control-inline-start-block-start">
<input
type="text"
class="input"
placeholder="Search for a place..."
autocomplete="off" /><!-- Turn off the input's own autocomplete (not supported by all browsers).-->
<div class="token-status"></div>
<div class="title"></div>
<ol class="results"></ol>
</div>
</gmp-map>
</body>
</html>Tối ưu hoá tính năng Tự động hoàn thành (Mới)
Phần này mô tả các phương pháp hay nhất giúp bạn khai thác tối đa dịch vụ Tự động hoàn thành (Mới).
Sau đây là một số nguyên tắc chung:
- Cách nhanh nhất để phát triển một giao diện người dùng hoạt động hiệu quả là sử dụng tiện ích Tự động hoàn thành (Mới) của API JavaScript Maps, tiện ích Tự động hoàn thành (Mới) của SDK Địa điểm cho Android, hoặc tiện ích Tự động hoàn thành (Mới) của SDK Địa điểm cho iOS.
- Hiểu rõ các trường dữ liệu thiết yếu của tính năng Tự động hoàn thành (Mới) ngay từ đầu.
- Các trường thiên vị vị trí và hạn chế vị trí là không bắt buộc nhưng có thể ảnh hưởng đáng kể đến hiệu suất tự động hoàn thành.
- Sử dụng tính năng xử lý lỗi để đảm bảo ứng dụng của bạn xuống cấp một cách linh hoạt nếu API trả về lỗi.
- Đảm bảo ứng dụng của bạn xử lý trường hợp không có lựa chọn nào và cung cấp cho người dùng cách tiếp tục.
Các phương pháp hay nhất để tối ưu hoá chi phí
Tối ưu hoá chi phí cơ bản
Để tối ưu hoá chi phí sử dụng dịch vụ Tự động hoàn thành (Mới), hãy sử dụng mặt nạ trường trong các tiện ích Place Details (Mới) và Tự động hoàn thành (Mới) để chỉ trả về trường dữ liệu Tự động hoàn thành (Mới) mà bạn cần.
Tối ưu hoá chi phí nâng cao
Hãy cân nhắc việc triển khai tính năng Tự động hoàn thành (Mới) theo phương thức lập trình để sử dụng SKU: Giá của yêu cầu Tự động hoàn thành và yêu cầu kết quả của Geocoding API về địa điểm đã chọn thay vì Place Details (Mới). Mô hình định giá theo yêu cầu kết hợp với Geocoding API sẽ tiết kiệm chi phí hơn so với mô hình định giá theo phiên (dựa trên phiên) nếu đáp ứng cả hai điều kiện sau:
- Nếu bạn chỉ cần vĩ độ và kinh độ hoặc địa chỉ của địa điểm mà người dùng đã chọn, thì Geocoding API sẽ cung cấp thông tin này với chi phí thấp hơn so với lệnh gọi Place Details (Mới).
- Nếu người dùng chọn một cụm từ gợi ý của tính năng tự động hoàn thành trong trung bình 4 yêu cầu cụm từ gợi ý của tính năng Tự động hoàn thành (Mới) trở xuống, thì mức giá theo yêu cầu có thể tiết kiệm chi phí hơn so với mức giá theo phiên.
Ứng dụng của bạn có yêu cầu thông tin nào khác ngoài địa chỉ và vĩ độ/kinh độ của kết quả dự đoán đã chọn không?
Có, cần thêm thông tin chi tiết
Sử dụng tính năng Tự động hoàn thành (Mới) dựa trên phiên với Place Details (Mới).
Vì ứng dụng của bạn yêu cầu Chi tiết địa điểm (Mới), chẳng hạn như tên địa điểm, trạng thái kinh doanh
hoặc giờ mở cửa, nên việc triển khai tính năng Tự động hoàn thành (Mới) phải sử dụng mã thông báo phiên
(theo phương thức lập trình hoặc được tích hợp vào các tiện ích
JavaScript,
Android
hoặc iOS)
cho mỗi phiên cộng với các SKU Địa điểm hiện hành,
tuỳ thuộc vào trường dữ liệu địa điểm mà bạn yêu cầu.1
Triển khai tiện ích
Tính năng quản lý phiên được tích hợp tự động vào các tiện ích
JavaScript,
Android,
hoặc iOS. Trong đó bao gồm cả yêu cầu của tính năng Tự động hoàn thành (Mới) và yêu cầu của tính năng Place Details (Mới)
về cụm từ gợi ý đã chọn. Hãy nhớ chỉ định tham số fields để đảm bảo bạn chỉ yêu cầu trường dữ liệu của tính năng Tự động hoàn thành (Mới) mà bạn cần.
Triển khai có lập trình
Sử dụng
mã phiên
với các yêu cầu Tự động hoàn thành (Mới). Khi yêu cầu Place Details (Mới) về cụm từ gợi ý đã chọn, hãy thêm các tham số sau:
- Mã địa điểm từ phản hồi của tính năng Tự động hoàn thành (Mới)
- Mã thông báo phiên được dùng trong yêu cầu Tự động hoàn thành (Mới)
- Tham số
fieldschỉ định trường dữ liệu của tính năng Tự động hoàn thành (Mới) mà bạn cần
Không, chỉ cần địa chỉ và vị trí
Geocoding API có thể là một lựa chọn tiết kiệm chi phí hơn so với Place Details (Mới) cho ứng dụng của bạn, tuỳ thuộc vào hiệu suất sử dụng tính năng Tự động hoàn thành (Mới). Hiệu suất của tính năng Tự động hoàn thành (Mới) trong mỗi ứng dụng sẽ khác nhau tuỳ thuộc vào nội dung người dùng nhập, nơi ứng dụng được sử dụng và liệu các phương pháp hay nhất để tối ưu hoá hiệu suất đã được triển khai hay chưa.
Để trả lời câu hỏi sau, hãy phân tích số ký tự trung bình mà người dùng nhập trước khi chọn một cụm từ gợi ý của tính năng Tự động hoàn thành (Mới) trong ứng dụng của bạn.
Trung bình, người dùng của bạn có chọn một cụm từ gợi ý của tính năng Tự động hoàn thành (Mới) trong 4 yêu cầu trở xuống không?
Có
Triển khai tính năng Tự động hoàn thành (Mới) theo phương thức lập trình mà không cần mã thông báo phiên và gọi Geocoding API trên cụm từ gợi ý địa điểm đã chọn.
Geocoding API cung cấp địa chỉ và toạ độ vĩ độ/kinh độ.
Việc thực hiện 4 yêu cầu Autocomplete Requests cộng với một lệnh gọi Geocoding API về cụm từ gợi ý địa điểm đã chọn sẽ có chi phí thấp hơn chi phí cho mỗi phiên của Autocomplete (Mới).1
Hãy cân nhắc áp dụng các phương pháp hay nhất về hiệu suất để giúp người dùng nhận được cụm từ gợi ý mà họ đang tìm kiếm chỉ với ít ký tự hơn.
Không
Sử dụng tính năng Tự động hoàn thành (Mới) dựa trên phiên với Place Details (Mới).
Vì số lượng yêu cầu trung bình mà bạn dự kiến thực hiện trước khi người dùng chọn một cụm từ gợi ý của tính năng Tự động hoàn thành (Mới) vượt quá chi phí của mô hình định giá theo phiên, nên việc triển khai tính năng Tự động hoàn thành (Mới) của bạn phải sử dụng mã thông báo phiên cho cả yêu cầu Tự động hoàn thành (Mới) và yêu cầu Chi tiết địa điểm (Mới) liên quan
theo phiên.
1
Triển khai tiện ích
Tính năng quản lý phiên được tích hợp tự động vào các tiện ích
JavaScript,
Android
hoặc iOS. Yêu cầu này bao gồm cả yêu cầu Tự động hoàn thành (Mới) và yêu cầu Place Details (Mới)
về cụm từ gợi ý đã chọn. Hãy nhớ chỉ định tham số fields để đảm bảo bạn chỉ yêu cầu các trường cần thiết.
Triển khai có lập trình
Sử dụng
mã phiên
với các yêu cầu Tự động hoàn thành (Mới).
Khi yêu cầu Place Details (Mới) về cụm từ gợi ý đã chọn, hãy thêm các tham số sau:
- Mã địa điểm từ phản hồi của tính năng Tự động hoàn thành (Mới)
- Mã thông báo phiên được dùng trong yêu cầu Tự động hoàn thành (Mới)
- Tham số
fieldschỉ định các trường chẳng hạn như địa chỉ và hình học
Cân nhắc việc trì hoãn yêu cầu Tự động hoàn thành (Mới)
Bạn có thể áp dụng các chiến lược như trì hoãn yêu cầu Tự động hoàn thành (Mới) cho đến khi người dùng nhập 3 hoặc 4 ký tự đầu tiên để ứng dụng của bạn đưa ra ít yêu cầu hơn. Ví dụ: nếu bạn đưa ra Yêu cầu API về tính năng Tự động hoàn thành (Mới) cho mỗi ký tự sau khi người dùng nhập ký tự thứ ba, thì tức là nếu người dùng nhập 7 ký tự rồi chọn một cụm từ gợi ý mà bạn đưa ra một Yêu cầu API về Geocoding API, thì tổng chi phí sẽ là 4 Yêu cầu API về tính năng Tự động hoàn thành (Mới) + Geocoding.1
Nếu việc trì hoãn yêu cầu có thể giúp bạn giảm số yêu cầu có lập trình trung bình xuống dưới 4, thì bạn có thể làm theo hướng dẫn triển khai Tính năng tự động hoàn thành (Mới) hiệu suất cao bằng Geocoding API. Xin lưu ý rằng việc trì hoãn yêu cầu có thể khiến người dùng cảm thấy có độ trễ khi họ muốn xem thông tin dự đoán sau mỗi lần nhấn phím.
Hãy cân nhắc việc áp dụng các phương pháp hay nhất về hiệu suất để giúp người dùng nhận được cụm từ gợi ý mà họ đang tìm kiếm với ít ký tự hơn.
-
Để biết chi phí, hãy xem bảng giá của Google Maps Platform.
Các phương pháp hay nhất về hiệu suất
Các nguyên tắc sau đây mô tả cách tối ưu hoá hiệu suất của tính năng Tự động hoàn thành (Mới):
- Thêm các quy định hạn chế theo quốc gia, độ lệch vị trí và (đối với việc triển khai có lập trình) ngôn ngữ ưu tiên cho việc triển khai Tính năng tự động hoàn thành (Mới). Bạn không cần đặt ngôn ngữ ưu tiên cho tiện ích vì tiện ích sẽ chọn ngôn ngữ ưu tiên từ trình duyệt hoặc thiết bị di động của người dùng.
- Nếu tính năng Tự động hoàn thành (Mới) đi kèm với bản đồ, bạn có thể thiên vị vị trí theo khung nhìn bản đồ.
- Trong trường hợp người dùng không chọn một trong các cụm từ gợi ý của tính năng Tự động hoàn thành (Mới), thường là do không có cụm từ gợi ý nào là địa chỉ kết quả mong muốn, bạn có thể sử dụng lại thông tin đầu vào ban đầu của người dùng để cố gắng nhận được kết quả phù hợp hơn:
- Nếu bạn muốn người dùng chỉ nhập thông tin địa chỉ, hãy sử dụng lại hoạt động đầu vào ban đầu của người dùng trong lệnh gọi đến Geocoding API.
- Nếu bạn muốn người dùng nhập cụm từ tìm kiếm cho một địa điểm cụ thể theo tên hoặc địa chỉ, hãy sử dụng yêu cầu Chi tiết địa điểm (Mới). Nếu bạn chỉ muốn nhận kết quả ở một khu vực cụ thể, hãy sử dụng tính năng thiên vị vị trí.
- Người dùng nhập địa chỉ của cơ sở phụ, chẳng hạn như địa chỉ của các căn hộ hoặc căn hộ cụ thể trong một toà nhà. Ví dụ: địa chỉ "Stroupežnického 3191/17, Praha" ở Séc trả về một cụm từ gợi ý một phần trong tính năng Tự động hoàn thành (Mới).
- Người dùng nhập địa chỉ có tiền tố đoạn đường như "23-30 29th St, Queens" ở Thành phố New York hoặc "47-380 Kamehameha Hwy, Kaneohe" trên đảo Kauai ở Hawaii.
Thiên vị vị trí
Ưu tiên kết quả cho một khu vực cụ thể bằng cách truyền tham số location và tham số radius. Thao tác này hướng dẫn tính năng Tự động hoàn thành (Mới) ưu tiên hiển thị kết quả trong khu vực đã xác định. Kết quả bên ngoài khu vực đã xác định vẫn có thể xuất hiện. Bạn có thể sử dụng tham số includedRegionCodes để lọc kết quả nhằm chỉ hiển thị những địa điểm trong một quốc gia cụ thể.
Hạn chế về vị trí
Hạn chế kết quả trong một khu vực cụ thể bằng cách truyền tham số locationRestriction.
Bạn cũng có thể giới hạn kết quả ở khu vực được xác định bằng location và tham số radius bằng cách thêm tham số locationRestriction. Thao tác này hướng dẫn tính năng Tự động hoàn thành (Mới) chỉ trả về kết quả trong khu vực đó.