Tính năng Tự động hoàn thành (Mới) trả về cụm từ gợi ý về địa điểm để phản hồi một yêu cầu bao gồm chuỗi tìm kiếm văn bản và ranh giới địa lý kiểm soát khu vực tìm kiếm. Tính năng tự động hoàn thành có thể so khớp trên các từ đầy đủ và chuỗi con của dữ liệu đầu vào, phân giải tên địa điểm, địa chỉ và Plus Codes. Ứng dụng của bạn có thể gửi các truy vấn khi người dùng nhập, để cung cấp thông tin dự đoán về địa điểm và truy vấn ngay lập tức.
Ví dụ: bạn gọi tính năng Tự động hoàn thành bằng cách sử dụng dữ liệu đầu vào là một chuỗi chứa một phần thông tin do người dùng nhập, "Sicilian piz", với khu vực tìm kiếm được giới hạn ở San Francisco, CA. Sau đó, phản hồi sẽ chứa danh sách các cụm từ gợi ý về địa điểm khớp với chuỗi tìm kiếm và khu vực tìm kiếm, chẳng hạn như nhà hàng có tên "Sicilian Pizza Kitchen". Các kết quả dự đoán địa điểm được trả về được thiết kế để trình bày cho người dùng nhằm hỗ trợ họ chọn địa điểm mong muốn. Bạn có thể gửi yêu cầu Chi tiết địa điểm (Mới) để biết thêm thông tin về bất kỳ cụm từ gợi ý địa điểm nào được trả về.
Bạn có thể tích hợp chức năng Tự động hoàn thành (Mới) vào ứng dụng theo 2 cách chính:
- Thêm tiện ích Place Autocomplete: Cung cấp trải nghiệm tự động hoàn thành tìm kiếm sẵn sàng sử dụng thông qua lớp
PlaceAutocomplete. Lớp này sẽ hiển thị các cụm từ gợi ý khi người dùng nhập. - Lấy thông tin dự đoán về địa điểm theo phương thức lập trình: Gọi trực tiếp API để truy xuất thông tin dự đoán và hiển thị thông tin đó trong giao diện người dùng tuỳ chỉnh.
Thêm tiện ích Place Autocomplete
Để dễ dàng cung cấp trải nghiệm Place Autocomplete nhất quán, bạn có thể thêm tiện ích Place Autocomplete vào ứng dụng của mình. Tiện ích này cung cấp một giao diện chuyên dụng, toàn màn hình, xử lý hoạt động đầu vào của người dùng và hiển thị thông tin dự đoán về địa điểm cho người dùng, đồng thời trả về các đối tượng AutocompletePrediction cho ứng dụng. Sau đó, bạn có thể gửi yêu cầu Place Details (Mới) để nhận thêm thông tin về bất kỳ thông tin dự đoán nào về địa điểm.
Giống như khi lấy cụm từ gợi ý về địa điểm theo phương thức lập trình, tiện ích Place Autocomplete cho phép bạn sử dụng mã phiên để nhóm các yêu cầu tự động hoàn thành vào phiên cho mục đích thanh toán. Bạn có thể truyền mã phiên khi tạo ý định cho tiện ích bằng cách gọi setAutocompleteSessionToken(). Nếu bạn không cung cấp mã thông báo phiên, tiện ích sẽ tạo một mã thông báo cho bạn. Bạn có thể truy cập vào mã thông báo này bằng cách gọi getSessionTokenFromIntent(). Để biết thêm thông tin về cách sử dụng mã thông báo phiên, hãy xem bài viết Giới thiệu về mã thông báo phiên.
Cách thêm tiện ích Place Autocomplete vào ứng dụng:
(Không bắt buộc) Xác định mã thông báo phiên. Nếu bạn không cung cấp mã thông báo phiên, tiện ích sẽ tạo một mã thông báo cho bạn.
Xác định
autocompleteIntentbằng các tham số mong muốn và mã phiên của bạn.Xác định
ActivityResultLauncherchoStartActivityForResult. Trình khởi chạy này sẽ xử lý kết quả do hoạt động tự động hoàn thành trả về.Xử lý kết quả trong lệnh gọi lại của
ActivityResultLauncher. Việc này bao gồm trích xuấtAutocompletePredictionvàAutocompleteSessionToken(nếu bạn chưa cung cấp), xử lý lỗi và tuỳ ý đưa ra yêu cầufetchPlace()để biết thêm thông tin chi tiết về một địa điểm.Khởi chạy ý định bằng cách dùng
placeAutocompleteActivityResultLauncher
Các mẫu sau đây minh hoạ cách thêm tiện ích Place Autocomplete bằng cả Kotlin và Java:
Kotlin
// Provide the API key that has enabled "Places API (New)" in the Google Cloud Console. Places.initializeWithNewPlacesApiEnabled(/* Context= */ context, /* API Key= */ key) // Optional, create a session token for Autocomplete request and the followup FetchPlace request. val sessionToken: AutocompleteSessionToken = AutocompleteSessionToken.newInstance() val autocompleteIntent: Intent = PlaceAutocomplete.createIntent(this) { // ... provide input params for origin, countries, types filter ... setAutocompleteSessionToken(sessionToken) } val placeAutocompleteActivityResultLauncher: ActivityResultLauncher<Intent> = registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult -> val intent = result.data if (intent != null && result.resultCode == PlaceAutocompleteActivity.RESULT_OK) { // get prediction object val prediction: AutocompletePrediction? = PlaceAutocomplete.getPredictionFromIntent(intent!!) // get session token val sessionToken: AutocompleteSessionToken? = PlaceAutocomplete.getSessionTokenFromIntent(intent!!) // create PlacesClient to make FetchPlace request (optional) val placesClient: PlacesClient = Places.createClient(this) val response = placesClient.awaitFetchPlace(prediction.placeId, Field.DISPLAY_NAME) { sessionToken = sessionToken // optional } } } // Launch Activity placeAutocompleteActivityResultLauncher.launch(autocompleteIntent)
Java
// Provide the API key that has enabled "Places API (New)" in the Google Cloud Console. Places.initializeWithNewPlacesApiEnabled(/* Context= */ context, /* API Key= */ key); // Optional, create a session token for Autocomplete request and the followup FetchPlace request AutocompleteSessionToken sessionToken = AutocompleteSessionToken.newInstance(); Intent autocompleteIntent = new PlaceAutocomplete.IntentBuilder() // ... set input params for origin, countries, types filter ... .setSessionToken(sessionToken) // optional .build(this); ActivityResultLauncher<Intent> placeAutocompleteActivityResultLauncher = registerForActivityResult( new ActivityResultContracts.StartActivityForResult(), new ActivityResultCallback<ActivityResult>() { @Override public void onActivityResult(ActivityResult result) { Intent intent = result.getData(); if (result.getResultCode() == PlaceAutocompleteActivity.RESULT_OK) { // get prediction object AutocompletePrediction prediction = PlaceAutocomplete.getPredictionFromIntent( Preconditions.checkNotNull(intent)); // get session token AutocompleteSessionToken sessionToken = PlaceAutocomplete.getSessionTokenFromIntent( Preconditions.checkNotNull(intent)); // create PlacesClient to make FetchPlace request (optional) PlacesClient placesClient = Places.createClient(this); FetchPlaceRequest request = FetchPlaceRequest.builder(prediction.getPlaceId(), Arrays.asList(Field.DISPLAY_NAME)) .setSessionToken(sessionToken).build(); Task<FetchPlaceResponse> task = placesClient.fetchPlace(request); } } } ); // Launch Activity placeAutocompleteActivityResultLauncher.launch(autocompleteIntent);
Tuỳ chỉnh giao diện
Khi tạo một thực thể cho trải nghiệm Tự động hoàn thành, bạn có thể chỉ định một giao diện ghi đè bất kỳ thuộc tính kiểu mặc định nào. Bạn có thể tuỳ chỉnh màu sắc, kiểu chữ, khoảng cách, đường viền và góc của thành phần Tự động hoàn thành địa điểm. Giá trị mặc định là PlacesMaterialTheme. Mọi thuộc tính giao diện không bị ghi đè sẽ sử dụng các kiểu mặc định.
Bạn có thể xác định các chế độ ghi đè giao diện trong …/res/values/themes.xml. Ví dụ:
<?xml version="1.0" encoding="utf-8"?> <resources> <style name="BrandedTheme" parent="PlacesMaterialTheme"> <!-- Color tokens. --> <item name="placesColorOnNeutralContainer">#5300e8</item> <item name="placesColorOnNeutralContainerVariant">#ee6002</item> ... <!-- Typography tokens. --> <item name="placesTextAppearanceTitleLarge">@style/PlacesTextAppearance</item> <item name="placesTextAppearanceBodyMedium">@style/PlacesTextAppearance</item> ... <!-- Spacing tokens. --> <item name="placesSpacingSmall">6dp</item> <item name="placesSpacingMedium">12dp</item> ... <!-- Attribution tokens. --> <item name="placesColorAttributionLightTheme">white</item> <item name="placesColorAttributionDarkTheme">black</item> </style> </resources>
Sau đó, bạn có thể tham chiếu các kiểu ghi đè bằng cách gọi setAutocompleteUiCustomization:
ActivityResultLauncher<Intent> placeAutocompleteActivityResultLauncher = registerForActivityResult( new ActivityResultContracts.StartActivityForResult(), new ActivityResultCallback<ActivityResult>() { @Override public void onActivityResult(ActivityResult result) { Intent intent = result.getData(); if (intent != null) { AutocompletePrediction prediction = PlaceAutocomplete.getPredictionFromIntent(intent); AutocompleteSessionToken sessionToken = PlaceAutocomplete.getSessionTokenFromIntent(intent); Status status = PlaceAutocomplete.getResultStatusFromIntent(intent); ... } } } ); Intent placeAutocompleteIntent = new PlaceAutocomplete.IntentBuilder() .setInitialQuery("INSERT_QUERY_TEXT") .setOrigin(new LatLng(10.0, 10.0)) ... .setAutocompleteUiCustomization( AutocompleteUiCustomization.builder() .listItemIcon(AutocompleteUiIcon.noIcon()) .listDensity(AutocompleteListDensity.MULTI_LINE) .theme(R.style.BrandedTheme) .build()) .build(this); placeAutocompleteActivityResultLauncher.launch(placeAutocompleteIntent);
Nhận thông tin dự đoán về địa điểm theo cách có lập trình
Ứng dụng của bạn có thể lấy danh sách tên và/hoặc địa chỉ địa điểm được dự đoán từ API tự động hoàn thành bằng cách gọi PlacesClient.findAutocompletePredictions(), truyền một đối tượng FindAutocompletePredictionsRequest. Ví dụ dưới đây minh hoạ một lệnh gọi hoàn chỉnh đến PlacesClient.findAutocompletePredictions().
Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();
LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);
final FindAutocompletePredictionsRequest autocompletePlacesRequest =
FindAutocompletePredictionsRequest.builder()
.setQuery("Sicilian piz")
.setRegionCode("ES")
.setLocationRestriction(circle)
.build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
.addOnSuccessListener(
(response) -> {
List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
}
).addOnFailureListener(
exception -> {
Log.e(TAG, "some exception happened" + exception.getMessage());
})
);Câu trả lời của tính năng Tự động hoàn thành (Mới)
API này trả về một
FindAutocompletePredictionsResponse
trong
Task.
FindAutocompletePredictionsResponse
chứa danh sách tối đa 5 đối tượng
AutocompletePrediction
đại diện cho các địa điểm được dự đoán. Danh sách này có thể trống nếu không có địa điểm nào đã biết tương ứng với cụm từ tìm kiếm và tiêu chí lọc.
Đối với mỗi địa điểm được dự đoán, bạn có thể gọi các phương thức sau để truy xuất thông tin chi tiết về địa điểm:
getFullText(CharacterStyle)trả về toàn bộ nội dung mô tả địa điểm. Đây là sự kết hợp giữa văn bản chính và văn bản phụ. Ví dụ: "Tháp Eiffel, Đại lộ Anatole France, Paris, Pháp". Ngoài ra, phương thức này cho phép bạn làm nổi bật các phần của nội dung mô tả khớp với nội dung tìm kiếm theo kiểu bạn chọn, bằng cách sử dụngCharacterStyle. Tham sốCharacterStylelà không bắt buộc. Đặt giá trị này thành null nếu bạn không cần làm nổi bật.getPrimaryText(CharacterStyle)trả về văn bản chính mô tả một địa điểm. Đây thường là tên của địa điểm. Ví dụ: "Tháp Eiffel" và "123 Pitt Street".getSecondaryText(CharacterStyle)trả về văn bản phụ của nội dung mô tả địa điểm. Ví dụ: điều này hữu ích khi bạn dùng làm dòng thứ hai khi hiển thị các cụm từ gợi ý của tính năng tự động hoàn thành. Ví dụ: "Avenue Anatole France, Paris, France" và "Sydney, New South Wales".getPlaceId()trả về Mã địa điểm của địa điểm được dự đoán. Mã địa điểm là một giá trị nhận dạng bằng văn bản xác định duy nhất một địa điểm. Bạn có thể dùng mã này để truy xuất lại đối tượngPlacesau này. Để biết thêm thông tin về mã địa điểm trong tính năng Tự động hoàn thành, hãy xem phần Thông tin chi tiết về địa điểm (Mới). Để biết thông tin chung về mã địa điểm, hãy xem phần Tổng quan về mã địa điểm.getTypes()trả về danh sách các loại địa điểm liên kết với địa điểm này.getDistanceMeters()trả về khoảng cách theo đường thẳng (tính bằng mét) giữa địa điểm này và điểm xuất phát được chỉ định trong yêu cầu.
Tham số bắt buộc
-
Truy vấn
Chuỗi văn bản cần tìm kiếm. Chỉ định từ đầy đủ và chuỗi con, tên địa điểm, địa chỉ và Plus Codes. Dịch vụ Tự động hoàn thành (Mới) trả về các kết quả phù hợp dựa trên chuỗi này và sắp xếp kết quả dựa trên mức độ liên quan mà dịch vụ nhận thấy.
Để đặt tham số truy vấn, hãy gọi phương thức
setQuery()khi tạo đối tượngFindAutocompletePredictionsRequest.
Thông số tùy chọn
-
Loại chính
Một danh sách gồm tối đa 5 giá trị loại từ các loại Bảng A hoặc Bảng B dùng để lọc những địa điểm được trả về trong phản hồi. Một địa điểm phải khớp với một trong các giá trị loại chính được chỉ định để có thể xuất hiện trong phản hồi.
Một địa điểm chỉ có thể có một loại chính trong số các loại được liên kết trong Bảng A hoặc Bảng B. Ví dụ: loại chính có thể là
"mexican_restaurant"hoặc"steak_house".Yêu cầu sẽ bị từ chối kèm theo lỗi
INVALID_REQUESTnếu:- Bạn chỉ định nhiều hơn 5 loại.
- Mọi loại không nhận dạng được đều được chỉ định.
Để đặt tham số loại chính, hãy gọi phương thức
setTypesFilter()khi tạo đối tượngFindAutocompletePredictionsRequest. -
Quốc gia
Chỉ bao gồm kết quả từ danh sách các quốc gia được chỉ định, được chỉ định dưới dạng danh sách tối đa 15 giá trị gồm hai ký tự ccTLD ("miền cấp cao nhất"). Nếu bạn bỏ qua, thì sẽ không có quy định hạn chế nào được áp dụng cho phản hồi. Ví dụ: để giới hạn khu vực ở Đức và Pháp:
Nếu bạn chỉ định cả
locationRestrictionvàincludedRegionCodes, thì kết quả sẽ nằm trong khu vực giao nhau của hai chế độ cài đặt này.Để đặt tham số quốc gia, hãy gọi phương thức
setCountries()khi tạo đối tượngFindAutocompletePredictionsRequest. -
Độ lệch đầu vào
Vị trí ký tự Unicode dựa trên số 0 cho biết vị trí con trỏ trong cụm từ tìm kiếm. Vị trí con trỏ có thể ảnh hưởng đến những dự đoán được trả về. Nếu để trống, giá trị này sẽ mặc định là độ dài của cụm từ tìm kiếm.
Để đặt tham số độ lệch đầu vào, hãy gọi phương thức
setInputOffset()khi tạo đối tượngFindAutocompletePredictionsRequest. Thiên vị vị trí hoặc hạn chế vị trí
Bạn có thể chỉ định độ lệch vị trí hoặc quy định hạn chế về vị trí (nhưng không được chỉ định cả hai) để xác định khu vực tìm kiếm. Hãy coi việc hạn chế vị trí là chỉ định khu vực mà kết quả phải nằm trong đó, còn thiên vị vị trí là chỉ định khu vực mà kết quả phải ở gần. Điểm khác biệt chính là với độ lệch vị trí, kết quả bên ngoài khu vực được chỉ định vẫn có thể được trả về.
Thiên kiến về vị trí
Chỉ định một khu vực để tìm kiếm. Vị trí này đóng vai trò là một yếu tố thiên vị, chứ không phải là một hạn chế, vì vậy, kết quả bên ngoài khu vực được chỉ định vẫn có thể được trả về.
Để đặt tham số thiên vị vị trí, hãy gọi phương thức
setLocationBias()khi tạo đối tượngFindAutocompletePredictionsRequest.Hạn chế về vị trí
Chỉ định một khu vực để tìm kiếm. Kết quả bên ngoài khu vực được chỉ định sẽ không được trả về.
Để đặt tham số hạn chế vị trí, hãy gọi phương thức
setLocationRestriction()khi tạo đối tượngFindAutocompletePredictionsRequest.
Chỉ định khu vực thiên vị vị trí hoặc khu vực hạn chế vị trí dưới dạng Khung nhìn hình chữ nhật hoặc hình tròn.
Hình tròn được xác định bằng tâm và bán kính tính bằng mét. Bán kính phải nằm trong khoảng từ 0,0 đến 50000,0, tính cả hai giá trị này. Giá trị mặc định là 0.0. Đối với quy định hạn chế về vị trí, bạn phải đặt bán kính thành một giá trị lớn hơn 0. Nếu không, yêu cầu sẽ không trả về kết quả nào.
Hình chữ nhật là một khung nhìn vĩ độ-kinh độ, được biểu thị dưới dạng hai điểm
lowvàhighđối diện nhau theo đường chéo. Khung nhìn được coi là một vùng khép kín, nghĩa là nó bao gồm cả ranh giới của nó. Giới hạn vĩ độ phải nằm trong khoảng từ -90 đến 90 độ và giới hạn kinh độ phải nằm trong khoảng từ -180 đến 180 độ:- Nếu
low=high, thì khung nhìn sẽ bao gồm điểm duy nhất đó. - Nếu
low.longitude>high.longitude, thì phạm vi kinh độ sẽ bị đảo ngược (khung nhìn vượt qua đường kinh độ 180 độ). - Nếu
low.longitude= -180 độ vàhigh.longitude= 180 độ, thì khung nhìn sẽ bao gồm tất cả các kinh độ. - Nếu
low.longitude= 180 độ vàhigh.longitude= -180 độ, thì phạm vi kinh độ sẽ trống.
Bạn phải điền cả
lowvàhigh, đồng thời hộp được biểu thị không được để trống. Khung hiển thị trống sẽ dẫn đến lỗi.- Nếu
-
Điểm gốc
Điểm xuất phát để tính khoảng cách theo đường thẳng đến điểm đến (truy cập bằng
getDistanceMeters()). Nếu bạn bỏ qua giá trị này, khoảng cách theo đường thẳng sẽ không được trả về. Phải được chỉ định dưới dạng toạ độ vĩ độ và kinh độ:Để đặt tham số nguồn gốc, hãy gọi phương thức
setOrigin()khi tạo đối tượngFindAutocompletePredictionsRequest. -
Mã vùng
Mã vùng dùng để định dạng phản hồi, bao gồm cả định dạng địa chỉ, được chỉ định dưới dạng giá trị gồm hai ký tự ccTLD ("miền cấp cao nhất"). Hầu hết các mã ccTLD đều giống với mã ISO 3166-1, ngoại trừ một số trường hợp ngoại lệ đáng chú ý. Ví dụ: ccTLD của Vương quốc Anh là "uk" (.co.uk) trong khi mã ISO 3166-1 của quốc gia này là "gb" (về mặt kỹ thuật là cho thực thể "Vương quốc Anh và Bắc Ireland").
Nếu bạn chỉ định mã vùng không hợp lệ, API sẽ trả về lỗi
INVALID_ARGUMENT. Tham số này có thể ảnh hưởng đến kết quả dựa trên luật hiện hành.Để đặt tham số mã khu vực, hãy gọi phương thức
setRegionCode()khi tạo đối tượngFindAutocompletePredictionsRequest. -
Mã thông báo phiên
Mã thông báo phiên là chuỗi do người dùng tạo để theo dõi các lệnh gọi Tự động hoàn thành (Mới) – cả lệnh gọi được thực hiện thông qua tiện ích và lệnh gọi theo chương trình – dưới dạng "phiên". Tính năng Tự động hoàn thành sử dụng 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 cụm từ tìm kiếm và kết thúc khi họ chọn một địa điểm. Mỗi phiên có thể có nhiều cụm từ tìm kiếm, sau đó là một lựa chọn về địa điểm. Sau khi một phiên kết thúc, mã thông báo sẽ không còn hợp lệ; ứng dụng của bạn phải tạo một mã thông báo mới cho mỗi phiên. Bạn nên sử dụng mã thông báo phiên cho tất cả các phiên tự động hoàn thành theo chương trình (khi bạn nhúng một mảnh hoặc khởi chạy tính năng tự động hoàn thành bằng một ý định, API sẽ tự động xử lý việc này).
Tính năng Tự động hoàn thành sử dụng
AutocompleteSessionTokenđể xác định từng phiên. Ứng dụng của bạn phải truyền một mã thông báo phiên mới khi bắt đầu mỗi phiên mới, sau đó truyền mã thông báo đó cùng với một Mã địa điểm trong lệnh gọi tiếp theo đếnfetchPlace()để truy xuất Thông tin chi tiết về địa điểm cho địa điểm mà người dùng đã chọn.Để đặt tham số mã thông báo phiên, hãy gọi phương thức
setSessionToken()khi tạo đối tượngFindAutocompletePredictionsRequest.Để biết thêm thông tin, hãy xem phần Mã thông báo phiên.
Ví dụ về tính năng Tự động hoàn thành (Mới)
Sử dụng hạn chế về vị trí và thiên kiến về vị trí
Tính năng Tự động hoàn thành (Mới) sử dụng độ lệch IP theo mặc định để kiểm soát khu vực tìm kiếm. Với tính năng thiên vị theo IP, API sẽ sử dụng địa chỉ IP của thiết bị để thiên vị kết quả. Bạn có thể sử dụng hạn chế vị trí hoặc thiên vị vị trí (nhưng không được dùng cả hai) để chỉ định một khu vực cần tìm kiếm.
Hạn chế về vị trí chỉ định khu vực cần tìm kiếm. Kết quả bên ngoài khu vực được chỉ định sẽ không được trả về. Ví dụ sau đây sử dụng quy định hạn chế về vị trí để giới hạn yêu cầu trong một quy định hạn chế về vị trí hình tròn có bán kính 5.000 m, lấy San Francisco làm tâm:
Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();
LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);
final FindAutocompletePredictionsRequest autocompletePlacesRequest =
FindAutocompletePredictionsRequest.builder()
.setQuery("Amoeba")
.setLocationRestriction(circle)
.build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
.addOnSuccessListener(
(response) -> {
List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
}
).addOnFailureListener(
exception -> {
Log.e(TAG, "some exception happened" + exception.getMessage());
})
);Với thiên kiến về vị trí, vị trí đóng vai trò là một thiên kiến, tức là kết quả xung quanh vị trí đã chỉ định có thể được trả về, bao gồm cả kết quả bên ngoài khu vực đã chỉ định. Ví dụ tiếp theo thay đổi yêu cầu trước đó để sử dụng độ lệch vị trí:
Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();
LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);
final FindAutocompletePredictionsRequest autocompletePlacesRequest =
FindAutocompletePredictionsRequest.builder()
.setQuery("Amoeba")
.setLocationBias(circle)
.build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
.addOnSuccessListener(
(response) -> {
List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
}
).addOnFailureListener(
exception -> {
Log.e(TAG, "some exception happened" + exception.getMessage());
})
);Sử dụng các loại chính
Sử dụng tham số primary types để hạn chế kết quả của một yêu cầu thuộc một loại nhất định như được liệt kê trong Bảng A và Bảng B. Bạn có thể chỉ định một mảng có tối đa 5 giá trị. Nếu bạn bỏ qua, tất cả các loại sẽ được trả về.
Ví dụ sau đây chỉ định một chuỗi truy vấn là "Bóng đá" và sử dụng tham số primarytypes để giới hạn kết quả ở những cơ sở thuộc loại "sporting_goods_store":
Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();
final List<Place.Field> primaryTypes = Arrays.asList("sporting_goods_store");
LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);
final FindAutocompletePredictionsRequest autocompletePlacesRequest =
FindAutocompletePredictionsRequest.builder()
.setQuery("Soccer")
.setIncludedPrimaryTypes(primaryTypes)
.setLocationBias(circle)
.build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
.addOnSuccessListener(
(response) -> {
List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
}
).addOnFailureListener(
exception -> {
Log.e(TAG, "some exception happened" + exception.getMessage());
})
);Nếu bạn bỏ qua tham số loại chính, kết quả có thể bao gồm những cơ sở thuộc loại mà bạn không muốn, chẳng hạn như "athletic_field".
Sử dụng nguồn gốc
Khi bạn đưa tham số origin vào yêu cầu, được chỉ định dưới dạng toạ độ vĩ độ và kinh độ, API sẽ đưa khoảng cách đường thẳng từ điểm xuất phát đến điểm đến vào phản hồi (được truy cập bằng getDistanceMeters()). Ví dụ này đặt điểm xuất phát là trung tâm của San Francisco:
Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();
LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);
final FindAutocompletePredictionsRequest autocompletePlacesRequest =
FindAutocompletePredictionsRequest.builder()
.setQuery("Amoeba")
.setOrigin(center)
.setLocationRestriction(circle)
.build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
.addOnSuccessListener(
(response) -> {
List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
}
).addOnFailureListener(
exception -> {
Log.e(TAG, "some exception happened" + exception.getMessage());
})
);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ý khi 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ức 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ức giá theo phiên (dựa trên phiên) nếu bạn đá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 cho ít hơn một 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 dựa trên phiên (Mới) với tính năng Chi tiết về địa điểm (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 theo chương trình
Sử dụng mã thông báo 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 trong 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 dữ liệu 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 ý Tự động hoàn thành (Mới) trong tối đa 4 yêu cầu 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 kết quả dự đoán được chọn về địa điểm.
Geocoding API cung cấp địa chỉ và toạ độ vĩ độ/kinh độ.
Thực hiện 4 yêu cầu Tự động hoàn thành cộng với một lệnh gọi Geocoding API về cụm từ gợi ý địa điểm đã chọn sẽ ít tốn kém hơn so với chi phí cho mỗi phiên của tính năng Tự động hoàn thành (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 dựa trên phiên (Mới) với tính năng Chi tiết về địa điểm (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) phải sử dụng mã phiên cho cả yêu cầu Tự động hoàn thành (Mới) và yêu cầu Place Details (Mới) được liên kết cho mỗi phiên.
1
Triển khai tiện ích
Tính năng quản lý phiên được tự động tích hợp 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 trong 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 thông tin dự đoán mà họ đang tìm kiếm chỉ bằng í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ả những 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 đơn vị cụ thể trong một toà nhà. Ví dụ: địa chỉ "Stroupežnického 3191/17, Praha" của Cộng hoà Séc sẽ cho ra 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ề vị trí
Điều chỉnh 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ả và chỉ cho thấy 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 do location và tham số radius xác định 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 đó.