Dịch vụ tự động hoàn thành trong SDK địa điểm dành cho Android sẽ trả về những gợi ý về địa điểm để phản hồi các truy vấn tìm kiếm của người dùng. Khi người dùng nhập thông tin, dịch vụ tự động hoàn thành sẽ trả về nội dung đề xuất cho các địa điểm như doanh nghiệp, địa chỉ, mã cộng và địa điểm yêu thích.
Bạn có thể thêm tính năng tự động hoàn thành vào ứng dụng của mình theo các cách sau:
- Thêm tiện ích tự động hoàn thành để tiết kiệm thời gian phát triển và đảm bảo trải nghiệm người dùng nhất quán.
- Lấy 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 người dùng tuỳ chỉnh.
Thêm tiện ích tự động hoàn thành
Tiện ích tự động hoàn thành là một hộp thoại tìm kiếm có sẵn chức năng tự động hoàn thành. Khi người dùng nhập cụm từ tìm kiếm, tiện ích sẽ hiển thị danh sách các địa điểm được dự đoán để bạn chọn. Khi người dùng chọn, một bản sao Place sẽ được trả về. Ứng dụng của bạn sau đó có thể sử dụng để nhận thông tin chi tiết về địa điểm đã chọn.
Có hai cách để thêm tiện ích tự động hoàn thành vào ứng dụng:
- Cách 1: Nhúng
AutocompleteSupportFragment. - Tùy chọn 2: Sử dụng một ý định để khởi chạy hoạt động tự động hoàn thành.
Lựa chọn 1: Nhúng một Tự động điền tự động hoàn thành
Để thêm AutocompleteSupportFragment vào ứng dụng, hãy thực hiện các bước sau:
- Thêm một mảnh vào bố cục XML của hoạt động.
- Thêm trình nghe vào hoạt động hoặc mảnh.
Thêm RenderingSupportFragment vào một hoạt động
Để thêm AutocompleteSupportFragment vào một hoạt động, hãy thêm một mảnh mới vào
bố cục XML. Ví dụ:
<fragment android:id="@+id/autocomplete_fragment"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:name="com.google.android.libraries.places.widget.AutocompleteSupportFragment"
/>
- Theo mặc định, mảnh này không có đường viền hoặc nền. Để cung cấp giao diện hình ảnh nhất quán, hãy lồng mảnh trong một phần tử bố cục khác, chẳng hạn như CardView.
- Nếu đang sử dụng mảnh Tự động hoàn thành và cần ghi đè
onActivityResult, bạn phải gọisuper.onActivityResultnếu không, mảnh sẽ không hoạt động đúng cách.
Thêm PlaceSelectionListener vào một hoạt động
PlaceSelectionListener xử lý việc trả về một địa điểm để phản hồi lựa chọn của người dùng. Đoạn mã sau đây cho thấy việc tạo tệp tham chiếu đến mảnh và thêm trình nghe vào AutocompleteSupportFragment:
Java
// Initialize the AutocompleteSupportFragment.
AutocompleteSupportFragment autocompleteFragment = (AutocompleteSupportFragment)
getSupportFragmentManager().findFragmentById(R.id.autocomplete_fragment);
// Specify the types of place data to return.
autocompleteFragment.setPlaceFields(Arrays.asList(Place.Field.ID, Place.Field.NAME));
// Set up a PlaceSelectionListener to handle the response.
autocompleteFragment.setOnPlaceSelectedListener(new PlaceSelectionListener() {
@Override
public void onPlaceSelected(@NonNull Place place) {
// TODO: Get info about the selected place.
Log.i(TAG, "Place: " + place.getName() + ", " + place.getId());
}
@Override
public void onError(@NonNull Status status) {
// TODO: Handle the error.
Log.i(TAG, "An error occurred: " + status);
}
});
Kotlin
// Initialize the AutocompleteSupportFragment.
val autocompleteFragment =
supportFragmentManager.findFragmentById(R.id.autocomplete_fragment)
as AutocompleteSupportFragment
// Specify the types of place data to return.
autocompleteFragment.setPlaceFields(listOf(Place.Field.ID, Place.Field.NAME))
// Set up a PlaceSelectionListener to handle the response.
autocompleteFragment.setOnPlaceSelectedListener(object : PlaceSelectionListener {
override fun onPlaceSelected(place: Place) {
// TODO: Get info about the selected place.
Log.i(TAG, "Place: ${place.name}, ${place.id}")
}
override fun onError(status: Status) {
// TODO: Handle the error.
Log.i(TAG, "An error occurred: $status")
}
})
Cách 2: Sử dụng một ý định để khởi chạy hoạt động tự động hoàn thành
Nếu bạn muốn ứng dụng của mình sử dụng một luồng điều hướng khác (ví dụ: để kích hoạt trải nghiệm tự động hoàn thành từ một biểu tượng thay vì một trường tìm kiếm), ứng dụng của bạn có thể chạy tính năng tự động hoàn thành bằng cách sử dụng một ý định.
Để chạy tiện ích tự động hoàn thành bằng một ý định, hãy làm theo các bước sau:
- Sử dụng
Autocomplete.IntentBuilderđể tạo ý định, truyền chế độAutocompletemong muốn. Ý định phải gọistartActivityForResult, chuyển vào một mã yêu cầu xác định ý định. - Ghi đè lệnh gọi lại
onActivityResultđể nhận địa điểm đã chọn.
Tạo ý định tự động hoàn thành
Ví dụ bên dưới cho thấy việc sử dụng Autocomplete.IntentBuilder để tạo ý định chạy tiện ích tự động hoàn thành dưới dạng ý định:
Java
private static int AUTOCOMPLETE_REQUEST_CODE = 1;
// Set the fields to specify which types of place data to
// return after the user has made a selection.
List<Place.Field> fields = Arrays.asList(Place.Field.ID, Place.Field.NAME);
// Start the autocomplete intent.
Intent intent = new Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
.build(this);
startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE);
Kotlin
private val AUTOCOMPLETE_REQUEST_CODE = 1
// Set the fields to specify which types of place data to
// return after the user has made a selection.
val fields = listOf(Place.Field.ID, Place.Field.NAME)
// Start the autocomplete intent.
val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
.build(this)
startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE)
Khi sử dụng ý định chạy tiện ích tự động hoàn thành, bạn có thể chọn trong số các chế độ hiển thị lớp phủ hoặc toàn màn hình. Các ảnh chụp màn hình sau đây lần lượt hiển thị từng chế độ hiển thị:
Ghi đè lệnh gọi lại onActivityResult
Để nhận được thông báo khi người dùng đã chọn một địa điểm, ứng dụng của bạn nên
ghi đè onActivityResult() của hoạt động, kiểm tra mã yêu cầu mà bạn
đã truyền cho ý định của mình, như trong ví dụ sau.
Java
@Override
protected void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) {
if (requestCode == AUTOCOMPLETE_REQUEST_CODE) {
if (resultCode == RESULT_OK) {
Place place = Autocomplete.getPlaceFromIntent(data);
Log.i(TAG, "Place: " + place.getName() + ", " + place.getId());
} else if (resultCode == AutocompleteActivity.RESULT_ERROR) {
// TODO: Handle the error.
Status status = Autocomplete.getStatusFromIntent(data);
Log.i(TAG, status.getStatusMessage());
} else if (resultCode == RESULT_CANCELED) {
// The user canceled the operation.
}
return;
}
super.onActivityResult(requestCode, resultCode, data);
}
Kotlin
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
if (requestCode == AUTOCOMPLETE_REQUEST_CODE) {
when (resultCode) {
Activity.RESULT_OK -> {
data?.let {
val place = Autocomplete.getPlaceFromIntent(data)
Log.i(TAG, "Place: ${place.name}, ${place.id}")
}
}
AutocompleteActivity.RESULT_ERROR -> {
// TODO: Handle the error.
data?.let {
val status = Autocomplete.getStatusFromIntent(data)
Log.i(TAG, status.statusMessage ?: "")
}
}
Activity.RESULT_CANCELED -> {
// The user canceled the operation.
}
}
return
}
super.onActivityResult(requestCode, resultCode, data)
}
Lấy thông tin dự đoán địa điểm theo phương thức lập trình
Bạn có thể tạo một giao diện người dùng tìm kiếm tuỳ chỉnh để thay thế cho giao diện người dùng do tiện ích tự động hoàn thành cung cấp. Để làm điều này, ứng dụng của bạn phải nhận được thông tin dự đoán về địa điểm theo phương thức lập trình. Ứng dụng của bạn có thể nhận được danh sách các 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(), chuyển đối tượng FindAutocompletePredictionsRequest với các tham số sau:
- Bắt buộc: Chuỗi
querychứa văn bản do người dùng nhập. - Đề xuất: Một
AutocompleteSessionTokenđể nhóm các giai đoạn truy vấn và lựa chọn của một người dùng tìm kiếm thành một phiên riêng cho mục đích thanh toán. Phiên hoạt động bắt đầu khi người dùng bắt đầu nhập một truy vấn và kết thúc khi họ chọn một địa điểm. - Đề xuất: Đối tượng
RectangularBounds, chỉ định ranh giới vĩ độ và kinh độ để giới hạn kết quả với khu vực đã chỉ định. - Không bắt buộc: Một hoặc nhiều mã quốc gia gồm hai chữ cái (ISO 3166-1 Alpha-2), cho biết quốc gia hoặc các quốc gia cần giới hạn kết quả.
Không bắt buộc:
TypeFiltermà bạn có thể dùng để giới hạn kết quả theo loại địa điểm đã chỉ định. Các loại địa điểm sau được hỗ trợ:TypeFilter.GEOCODE– Chỉ trả về kết quả mã hóa địa lý thay vì doanh nghiệp. Sử dụng yêu cầu này để phân biệt kết quả mà vị trí đã chỉ định có thể không xác định.TypeFilter.ADDRESS– Chỉ trả về kết quả tự động hoàn thành bằng địa chỉ chính xác. Hãy sử dụng loại này khi bạn biết người dùng đang tìm kiếm một địa chỉ được chỉ định đầy đủ.TypeFilter.ESTABLISHMENT– Chỉ trả về những địa điểm là doanh nghiệp.TypeFilter.REGIONS– Chỉ trả về những địa điểm phù hợp với một trong các loại sau:LOCALITYSUBLOCALITYPOSTAL_CODECOUNTRYADMINISTRATIVE_AREA_LEVEL_1ADMINISTRATIVE_AREA_LEVEL_2
TypeFilter.CITIES– Chỉ trả về kết quả khớp vớiLOCALITYhoặcADMINISTRATIVE_AREA_LEVEL_3.
Không bắt buộc:
LatLngchỉ định vị trí gốc của yêu cầu. Khi bạn gọisetOrigin(), dịch vụ sẽ trả về khoảng cách tính bằng mét (distanceMeters) từ nguồn gốc đã chỉ định, cho mỗi cụm từ gợi ý tự động hoàn thành trong phản hồi.
Để biết thông tin về các loại địa điểm, hãy xem hướng dẫn về loại địa điểm.
Ví dụ dưới đây minh hoạ lệnh gọi đến PlacesClient.findAutocompletePredictions() hoàn chỉnh.
Java
// Create a new token for the autocomplete session. Pass this to FindAutocompletePredictionsRequest,
// and once again when the user makes a selection (for example when calling fetchPlace()).
AutocompleteSessionToken token = AutocompleteSessionToken.newInstance();
// Create a RectangularBounds object.
RectangularBounds bounds = RectangularBounds.newInstance(
new LatLng(-33.880490, 151.184363),
new LatLng(-33.858754, 151.229596));
// Use the builder to create a FindAutocompletePredictionsRequest.
FindAutocompletePredictionsRequest request = FindAutocompletePredictionsRequest.builder()
// Call either setLocationBias() OR setLocationRestriction().
.setLocationBias(bounds)
//.setLocationRestriction(bounds)
.setOrigin(new LatLng(-33.8749937,151.2041382))
.setCountries("AU", "NZ")
.setTypesFilter(Arrays.asList(TypeFilter.ADDRESS.toString()))
.setSessionToken(token)
.setQuery(query)
.build();
placesClient.findAutocompletePredictions(request).addOnSuccessListener((response) -> {
for (AutocompletePrediction prediction : response.getAutocompletePredictions()) {
Log.i(TAG, prediction.getPlaceId());
Log.i(TAG, prediction.getPrimaryText(null).toString());
}
}).addOnFailureListener((exception) -> {
if (exception instanceof ApiException) {
ApiException apiException = (ApiException) exception;
Log.e(TAG, "Place not found: " + apiException.getStatusCode());
}
});
Kotlin
// Create a new token for the autocomplete session. Pass this to FindAutocompletePredictionsRequest,
// and once again when the user makes a selection (for example when calling fetchPlace()).
val token = AutocompleteSessionToken.newInstance()
// Create a RectangularBounds object.
val bounds = RectangularBounds.newInstance(
LatLng(-33.880490, 151.184363),
LatLng(-33.858754, 151.229596)
)
// Use the builder to create a FindAutocompletePredictionsRequest.
val request =
FindAutocompletePredictionsRequest.builder()
// Call either setLocationBias() OR setLocationRestriction().
.setLocationBias(bounds)
//.setLocationRestriction(bounds)
.setOrigin(LatLng(-33.8749937, 151.2041382))
.setCountries("AU", "NZ")
.setTypesFilter(listOf(TypeFilter.ADDRESS.toString()))
.setSessionToken(token)
.setQuery(query)
.build()
placesClient.findAutocompletePredictions(request)
.addOnSuccessListener { response: FindAutocompletePredictionsResponse ->
for (prediction in response.autocompletePredictions) {
Log.i(TAG, prediction.placeId)
Log.i(TAG, prediction.getPrimaryText(null).toString())
}
}.addOnFailureListener { exception: Exception? ->
if (exception is ApiException) {
Log.e(TAG, "Place not found: " + exception.statusCode)
}
}
API trả về một FindAutocompletePredictionsResponse trong
Task. FindAutocompletePredictionsResponse chứa danh sách các đố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ó vị trí đã biết nào tương ứng với truy vấn 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ộ văn bản của 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ụ: "Eiffel Tower, Avenue Anatole France, Paris, France". Ngoài ra, phương thức này cho phép bạn làm nổi bật các phần mô tả khớp với nội dung tìm kiếm theo kiểu mà bạn chọn, sử dụngCharacterStyle. Thông sốCharacterStylelà không bắt buộc. Đặt thành rỗng nếu bạn không cần bất kỳ đánh dấu nào.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ụ: "Eiffel Tower" và "123 Đồi Street".getSecondaryText(CharacterStyle)trả về văn bản con của nội dung mô tả địa điểm. Ví dụ: trường này hữu ích khi là dòng thứ hai khi hiển thị cụm từ gợi ý của tính năng tự động hoàn thành. Ví dụ: "A hút 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à giá trị nhận dạng văn bản xác định duy nhất một địa điểm mà bạn có thể sử dụng để truy xuất lại đối tượngPlacesau này. Để biết thêm thông tin về mã địa điểm trong SDK Địa điểm dành cho Android, hãy xem nội dung Thông tin chi tiết về địa điểm. Để biết thông tin chung về mã địa điểm, hãy xem nội dung tổng quan về mã địa điểm.getPlaceTypes()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 đường thẳng tính bằng mét giữa địa điểm này và nguồn gốc đã chỉ định trong yêu cầu.
Mã thông báo phiên
Mã thông báo phiên hoạt động 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 người dùng thành một phiên hoạt động riêng biệt cho mục đích thanh toán. Phiên hoạt động bắt đầu khi người dùng bắt đầu nhập một truy vấn và kết thúc khi họ chọn một địa điểm. Mỗi phiên có thể có nhiều truy vấn, theo sau là một lựa chọn địa điểm. Sau khi một phiên hoạt động kết thúc, mã thông báo này sẽ không còn hợp lệ nữa; ứ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 hoạt động. 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 có lập 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 cách sử dụng một ý định, API sẽ tự động xử lý vấn đề này).
SDK Địa điểm dành cho Android sử dụng AutocompleteSessionToken
để xác định mỗi phiên. Ứng dụng của bạn phải chuyển mã thông báo phiên mới khi bắt đầu mỗi phiên mới, sau đó chuyển mã thông báo đó cùng với Mã địa điểm trong lệnh gọi fetchPlace() tiếp theo để 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ìm hiểu thêm về mã thông báo phiên.
Giới hạn kết quả tự động hoàn thành
Bạn có thể ràng buộc kết quả tự động hoàn thành vào một khu vực địa lý cụ thể và/hoặc lọc kết quả theo một hoặc nhiều loại địa điểm hoặc đến tối đa 5 quốc gia.
Bạn có thể áp dụng các quy tắc ràng buộc này cho hoạt động tự động hoàn thành,
AutocompleteSupportFragment và API tự động hoàn thành có lập trình.
Để ràng buộc kết quả, hãy làm như sau:
- Để ưu tiên kết quả trong khu vực đã xác định, hãy gọi
setLocationBias()(một số kết quả ở bên ngoài khu vực đã xác định có thể vẫn được trả về). - Để chỉ hiển thị kết quả trong khu vực đã xác định, hãy gọi
setLocationRestriction()(chỉ kết quả trong khu vực đã xác định sẽ được trả về). - Để chỉ trả về kết quả phù hợp với một loại địa điểm cụ thể, hãy gọi
setTypesFilter()(ví dụ: chỉ địnhTypeFilter.ADDRESSsẽ chỉ trả về kết quả có địa chỉ chính xác). - Để chỉ trả về kết quả trong tối đa năm quốc gia đã chỉ định, hãy gọi
setCountries(). Quốc gia phải được chuyển dưới dạng mã quốc gia tương thích với ISO 3166-1 Alpha-2 gồm hai ký tự.
Định kiến kết quả về một khu vực cụ thể
Để tạo kết quả tự động hoàn thành cho một khu vực địa lý cụ thể, hãy gọi
setLocationBias(), chuyển RectangularBounds.
Ví dụ về mã sau đây cho thấy việc gọi setLocationBias() trên một phiên bản mảnh để thiên về các đề xuất tự động hoàn thành tới một khu vực ở Sydney, Úc.
Java
autocompleteFragment.setLocationBias(RectangularBounds.newInstance(
new LatLng(-33.880490, 151.184363),
new LatLng(-33.858754, 151.229596)));
Kotlin
autocompleteFragment.setLocationBias(
RectangularBounds.newInstance(
LatLng(-33.880490, 151.184363),
LatLng(-33.858754, 151.229596)
)
)
Hạn chế kết quả ở một khu vực cụ thể
Để hạn chế việc tự động hoàn thành kết quả tại một khu vực địa lý cụ thể, hãy gọi
setLocationRestriction(), truyền một RectangularBounds.
Mã ví dụ sau đây cho thấy việc gọi setLocationRestriction() trên một thực thể mảnh để thiên về các đề xuất tự động hoàn thành tới một khu vực ở Sydney, Úc.
Java
autocompleteFragment.setLocationRestriction(RectangularBounds.newInstance(
new LatLng(-33.880490, 151.184363),
new LatLng(-33.858754, 151.229596)));
Kotlin
autocompleteFragment.setLocationRestriction(
RectangularBounds.newInstance(
LatLng(-33.880490, 151.184363),
LatLng(-33.858754, 151.229596)
)
)
Lưu ý: Quy định hạn chế này chỉ áp dụng cho toàn bộ tuyến đường, các kết quả tổng hợp nằm ngoài ranh giới hình chữ nhật có thể được trả về dựa trên tuyến đường chồng chéo với quy định hạn chế về vị trí.
Lọc kết quả theo loại địa điểm hoặc thu thập loại
Bạn có thể hạn chế kết quả của một yêu cầu tự động hoàn thành để chúng chỉ trả về một loại địa điểm nhất định. Chỉ định bộ lọc bằng cách sử dụng các loại địa điểm hoặc một bộ sưu tập loại được liệt kê trong Bảng 1, 2 và 3 trên Loại địa điểm. Nếu không có giá trị nào được chỉ định, tất cả các kiểu sẽ được trả về.
Để lọc kết quả tự động hoàn thành, hãy gọi setTypesFilter() để đặt bộ lọc.
Cách chỉ định một loại hoặc bộ lọc thu thập loại:
Gọi
setTypesFilter()và chỉ định tối đa 5 giá trị loại từ Bảng 1 và Bảng 2 hiển thị trên Loại địa điểm. Các giá trị kiểu được xác định bởi các hằng số trong PlaceTypes.Gọi
setTypesFilter()và chỉ định một bộ sưu tập loại trong Bảng 3 hiển thị trên Loại địa điểm. Các giá trị của bộ sưu tập được xác định bằng các hằng số trong PlaceTypes.Chỉ được phép có một loại trong Bảng 3 trong yêu cầu. Nếu chỉ định một giá trị trong Bảng 3, bạn không thể chỉ định một giá trị trong Bảng 1 hoặc Bảng 2. Nếu bạn làm như vậy, thì sẽ xảy ra lỗi.
Ví dụ về mã sau đây gọi setTypesFilter() trên
AutocompleteSupportFragment và chỉ định nhiều giá trị loại.
Java
autocompleteFragment.setTypesFilter(Arrays.asList("landmark", "restaurant", "store"));
Kotlin
autocompleteFragment.setTypesFilter(listOf("landmark", "restaurant", "store"))
Ví dụ về mã sau đây cho thấy việc gọi setTypesFilter() trên
AutocompleteSupportFragment để đặt một bộ lọc chỉ trả về kết quả có
địa chỉ chính xác bằng cách chỉ định một bộ sưu tập loại.
Java
autocompleteFragment.setTypesFilter(Arrays.asList(TypeFilter.ADDRESS.toString()));
Kotlin
autocompleteFragment.setTypesFilter(listOf(TypeFilter.ADDRESS.toString()))
Ví dụ về mã sau đây cho thấy việc gọi setTypesFilter() trên
IntentBuilder để đặt một bộ lọc chỉ trả về kết quả có địa chỉ chính xác bằng cách
chỉ định một bộ sưu tập loại.
Java
Intent intent = new Autocomplete.IntentBuilder(
AutocompleteActivityMode.FULLSCREEN, fields)
.setTypesFilter(Arrays.asList(TypeFilter.ADDRESS.toString()))
.build(this);
startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE);
Kotlin
val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
.setTypesFilter(listOf(TypeFilter.ADDRESS.toString()))
.build(this)
startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE)
Lọc kết quả theo quốc gia
Để lọc kết quả tự động hoàn thành cho tối đa 5 quốc gia, hãy gọi setCountries()để đặt mã quốc gia.
Sau đó, chuyển bộ lọc đến một mảnh hoặc ý định. Quốc gia phải được chuyển dưới dạng mã quốc gia tương thích với hai ký tự, ISO 3166-1 Alpha-2.
Ví dụ về mã sau đây cho thấy việc gọi setCountries() trên
AutocompleteSupportFragment để đặt một bộ lọc chỉ trả về kết quả trong các quốc gia được chỉ định.
Java
autocompleteFragment.setCountries("AU", "NZ");
Kotlin
autocompleteFragment.setCountries("AU", "NZ")
Hạn mức sử dụng
Việc bạn sử dụng API Địa điểm, bao gồm cả SDK địa điểm dành cho Android, không còn giới hạn ở số lượng yêu cầu tối đa mỗi ngày (QPD). Tuy nhiên, các hạn mức sử dụng sau vẫn được áp dụng:
- Giới hạn tốc độ là 100 yêu cầu mỗi giây (QPS). Nó được tính bằng tổng số yêu cầu phía máy khách và phía máy chủ cho tất cả ứng dụng sử dụng thông tin đăng nhập của cùng một dự án.
Hiển thị thuộc tính trong ứng dụng của bạn
- Nếu ứng dụng của bạn sử dụng dịch vụ tự động hoàn thành theo cách lập trình, thì giao diện người dùng của bạn phải thể hiện thuộc tính "Do Google cung cấp" hoặc xuất hiện trong bản đồ mang thương hiệu Google.
- Nếu ứng dụng của bạn sử dụng tiện ích tự động hoàn thành, thì bạn không cần làm gì thêm (nội dung phân bổ bắt buộc sẽ xuất hiện theo mặc định).
- Nếu bạn truy xuất và hiển thị thông tin bổ sung về địa điểm sau khi nhận một địa điểm theo mã nhận dạng, bạn cũng phải hiển thị các thuộc tính của bên thứ ba.
Để biết thêm thông tin, hãy xem tài liệu về thuộc tính.
Tối ưu hóa tự động hoàn thành địa điểm
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 địa điểm.
Dưới đâ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 đang hoạt động là sử dụng Tiện ích tự động hoàn thành API JavaScript, Maps SDK cho Android Tiện ích tự động hoàn thành hoặc SDK Địa điểm dành cho iOS Kiểm soát giao diện người dùng tự động hoàn thành
- Hiểu rõ các trường dữ liệu cần thiết của tính năng Tự động hoàn thành địa điểm ngay từ đầu.
- Trường xu hướng vị trí và hạn chế vị trí là trường không bắt buộc nhưng có thể có tác động đáng kể đến hiệu suất tự động hoàn thành.
- Sử dụng cách xử lý lỗi để đảm bảo ứng dụng của bạn xuống cấp nhẹ nhàng nếu API trả về một lỗi.
- Hãy đả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 hóa chi phí sử dụng dịch vụ Tự động hoàn thành địa điểm, hãy sử dụng mặt nạ trường trong thông tin chi tiết về Địa điểm và tiện ích Tự động hoàn thành địa điểm để chỉ trả về các trường dữ liệu địa đ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 địa điểm theo phương thức lập trình để truy cập vào Giá cho mỗi yêu cầu và yêu cầu kết quả API mã hóa địa lý về địa điểm đã chọn thay vì Thông tin chi tiết về địa điểm. Định giá theo mỗi yêu cầu ghép nối với API mã hóa địa lý tiết kiệm chi phí hơn so với đặt giá cho mỗi 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ĩ độ/kinh độ hoặc địa chỉ của địa điểm mà người dùng đã chọn, thì API mã hóa địa lý cung cấp thông tin này cho ít hơn một lệnh gọi Chi tiết địa điểm.
- 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 bốn yêu cầu cụm từ gợi ý của tính năng Tự động hoàn thành trở xuống, thì việc đặt giá theo Yêu cầu có thể tiết kiệm chi phí hơn so với quy tắc đặt giá cho mỗi 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 thông tin dự đoán đã chọn không?
Có, cần thêm chi tiết
Sử dụng tính năng Tự động hoàn thành địa điểm dựa trên phiên hoạt động với thông tin chi tiết về địa điểm.
Vì ứng dụng của bạn yêu cầu Thông tin chi tiết về địa điểm (chẳng hạn như tên địa điểm, trạng thái doanh nghiệp hoặc giờ mở cửa), nên việc triển khai tính năng Tự động hoàn thành địa điểm phải sử dụng mã thông báo phiên (theo chương trình hoặc tích hợp trong các tiện ích JavaScript, Android hoặc iOS) với tổng chi phí là 0,017 đô la mỗi phiên cộng với Địa điểm SKU dữ liệu phù hợp với yêu cầu của bạn.
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. Con số này bao gồm cả yêu cầu Tự động hoàn thành địa điểm và yêu cầu Thông tin chi tiết về địa điểm trên dự đoán đã chọn. Hãy nhớ chỉ định tham số fields để đảm bảo bạn chỉ yêu cầu các trường dữ liệu địa điểm bạn cần.
Triển khai có lập trình
Sử dụng mã thông báo phiên có các yêu cầu Tự động hoàn thành địa điểm. Khi yêu cầu Thông tin chi tiết về địa điểm về gợi ý đã chọn, hãy bao gồm các thông số sau:
- Mã địa điểm từ phản hồi Tự động hoàn thành địa điểm
- Mã thông báo phiên được sử dụng trong yêu cầu Tự động hoàn thành địa điểm
- Tham số
fieldschỉ định trường dữ liệu địa điểm bạn cần
Không, chỉ cần địa chỉ và vị trí
API mã hóa địa lý có thể là một tùy chọn hiệu quả về chi phí hơn so với Chi tiết địa điểm cho ứng dụng của bạn, tùy thuộc vào hiệu suất sử dụng Tự động hoàn thành địa điểm của bạn. Hiệu quả của tính năng Tự động hoàn thành của các ứng dụng sẽ khác nhau tuỳ thuộc vào nội dung mà người dùng đang nhập, vị trí ứng dụng đang được sử dụng và việc các phương pháp hay nhất để tối ưu hoá hiệu suất có được triển khai hay không.
Để trả lời câu hỏi sau, hãy phân tích số lượng ký tự trung bình một người dùng nhập vào trước khi chọn cụm từ gợi ý của tính năng Tự động hoàn thành địa điểm trong ứng dụng của bạn.
Người dùng có chọn trung bình 4 yêu cầu hoặc ít hơn trong một gợi ý của tính năng Tự động hoàn thành địa điểm không?
Có
Triển khai tính năng Tự động hoàn thành địa điểm theo phương thức lập trình mà không cần mã thông báo phiên hoạt động và gọi API mã hóa địa lý đối với những thông tin dự đoán về địa điểm đã chọn.
API mã hóa địa lý cung cấp địa chỉ và toạ độ vĩ độ/kinh độ với giá 0,005 đô la cho mỗi yêu cầu. Việc tạo 4 yêu cầu Tự động hoàn thành địa điểm – Mỗi yêu cầu có chi phí là 0,01132 đô la, do đó, tổng chi phí của 4 yêu cầu và lệnh gọi API mã hóa địa lý cho thông tin dự đoán địa điểm đã chọn sẽ là 0,01632 đô la, thấp hơn giá mỗi lần tự động hoàn thành mỗi phiên là 0,017 đô la.1
Hãy cân nhắc sử 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 bằng ít ký tự hơn.
Không
Sử dụng tính năng Tự động hoàn thành địa điểm dựa trên phiên hoạt động với thông tin chi tiết về địa điểm.
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 địa điểm vượt quá chi phí của mỗi mức giá trong mỗi Phiên hoạt động, nên việc triển khai tính năng Tự động hoàn thành địa điểm sẽ sử dụng mã thông báo phiên cho cả yêu cầu Tự động hoàn thành địa điểm và yêu cầu Thông tin chi tiết về địa điểm liên quan cho tổng chi phí là 0,017 đô la 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. Con số này bao gồm cả yêu cầu Tự động hoàn thành địa điểm và yêu cầu Thông tin chi tiết về địa điểm trên dự đoán đã chọn. Hãy nhớ chỉ định tham số fields để đảm bảo bạn chỉ yêu cầu các trường Dữ liệu cơ bản.
Triển khai có lập trình
Sử dụng mã thông báo phiên có các yêu cầu Tự động hoàn thành địa điểm. Khi yêu cầu Thông tin chi tiết về địa điểm về gợi ý đã chọn, hãy bao gồm các thông số sau:
- Mã địa điểm từ phản hồi Tự động hoàn thành địa điểm
- Mã thông báo phiên được sử dụng trong yêu cầu Tự động hoàn thành địa điểm
- Tham số
fieldschỉ định các trường Dữ liệu cơ bản, chẳng hạn như địa chỉ và hình học
Cân nhắc việc trì hoãn các yêu cầu Tự động hoàn thành địa điểm
Bạn có thể sử dụng các chiến lược như trì hoãn yêu cầu Tự động hoàn thành địa điểm cho đến khi người dùng nhập 3 hoặc 4 ký tự đầu tiên để ứng dụng có ít yêu cầu hơn. Ví dụ: tạo yêu cầu Tự động hoàn thành địa điểm cho mỗi ký tự sau khi người dùng nhập ký tự thứ ba có nghĩa là nếu người dùng nhập bảy ký tự thì hãy chọn một gợi ý mà bạn thực hiện một yêu cầu API mã hóa địa lý, tổng chi phí sẽ là $0,01632 (4 * $0,00283 Tự động hoàn thành cho mỗi yêu cầu + $0,005 Mã hóa địa lý).1
Nếu việc trì hoãn các yêu cầu có thể nhận được bốn yêu cầu có lập trình trung bình của bạn dưới bốn lần, bạn có thể làm theo hướng dẫn để triển khai Tự động hoàn thành địa điểm với API Mã hóa địa lý. Xin lưu ý rằng những yêu cầu trì hoãn có thể được coi là độ trễ bởi người dùng có thể muốn xem các gợi ý khi có mọi thao tác nhấn phím mới.
Hãy cân nhắc sử 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 với ít ký tự hơn.
-
Chi phí nêu tại đây được tính bằng USD. Vui lòng tham khảo trang Thanh toán trên Nền tảng Google Maps để biết thông tin đầy đủ về giá.
Các phương pháp hay nhất về hiệu suất
Nguyên tắc sau đây mô tả các cách để tối ưu hóa hiệu suất Tự động hoàn thành địa điểm:
- Thêm các quy định hạn chế theo quốc gia, khuynh hướng vị trí và (đối với các hoạt động triển khai có lập trình) vào việc triển khai tính năng Tự động hoàn thành địa điểm. Tùy chọn ngôn ngữ không cần thiết với các tiện ích vì chúng chọn các tùy chọn ngôn ngữ từ trình duyệt hoặc thiết bị di động của người dùng.
- Nếu tự động hoàn thành địa điểm đi kèm với một 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, thường là do không có cụm từ gợi ý nào trong số này là địa chỉ nhận được kết quả mong muốn, nê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 dữ liệu đầu vào do người dùng nhập ban đầu trong lệnh gọi đến API Mã hóa địa lý.
- Nếu bạn muốn người dùng nhập các 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 Tìm địa điểm. Nếu kết quả chỉ có thể xuất hiện ở một khu vực cụ thể, hãy sử dụng x thiên lệch vị trí.
- Người dùng nhập địa chỉ cơ sở ở các quốc gia chưa hoàn tất hỗ trợ tính năng Tự động hoàn thành địa chỉ đối với địa chỉ phụ, ví dụ: Séc, Estonia và Lithuania. Ví dụ: địa chỉ của Séc "Stroupežnického 3191/17, Praha" đưa ra dự đoán một phần trong tính năng Tự động hoàn thành địa điểm.
- Người dùng nhập địa chỉ có tiền tố phân đoạn đường bộ như "23-30 29th St, Queens" ở Thành phố New York hoặc "47-380 Kamehameha Hwy, Kaneohe" trên đảo Kauai ở Hawai'i.
Khắc phục sự cố
Có nhiều lỗi có thể xảy ra, nhưng phần lớn các lỗi ứng dụng của bạn có thể gặp phải là do lỗi cấu hình (ví dụ: sử dụng khoá API không chính xác hoặc khoá API được định cấu hình không chính xác) hoặc lỗi hạn mức (ứng dụng đã vượt quá hạn mức). Hãy xem bài viết về Giới hạn sử dụng để biết thêm thông tin về hạn mức.
Các lỗi xảy ra khi sử dụng chế độ điều khiển tự động hoàn thành sẽ được trả về trong lệnh gọi lại onActivityResult(). Gọi Autocomplete.getStatus() để nhận thông báo trạng thái cho kết quả.