Tự động hoàn thành địa điểm

Chọn nền tảng: Android iOS JavaScript Dịch vụ web

Dịch vụ tự động hoàn thành trong Places SDK dành cho Android sẽ trả về gợi ý về địa điểm để phản hồi các cụm từ tìm kiếm của người dùng. Khi người dùng nhập, dịch vụ tự động hoàn thành sẽ trả về các đề 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ện ích tự động hoàn thành là một hộp thoại tìm kiếm có tích hợp 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 này sẽ hiển thị danh sách các địa điểm dự đoán để lựa chọn. Khi người dùng lựa chọn, hệ thống sẽ trả về một thực thể Place. Sau đó, ứng dụng của bạn có thể dùng thực thể này để xem thông tin chi tiết về địa điểm đã chọn.

Có hai lựa chọn để thêm tiện ích tự động hoàn thành vào ứng dụng của bạn:

Lựa chọn 1: Nhúng AutofillSupportFragment

Để thêm AutocompleteSupportFragment vào ứng dụng, hãy làm theo các bước sau:

  1. Thêm một mảnh vào bố cục XML của hoạt động.
  2. Thêm trình nghe vào hoạt động hoặc mảnh của bạn.

Thêm AutofillSupportFragment 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. Để mang lại 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ọi super.onActivityResult, nếu không mảnh sẽ hoạt động khô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. Mã sau đây cho biết cách tạo tham chiếu đến mảnh và thêm trình nghe vào AutocompleteSupportFragment:

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

      

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

      

Cách 2: Sử dụng ý định để 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 quy trình điều hướng khác (ví dụ: để kích hoạt trải nghiệm tự động hoàn thành từ biểu tượng thay vì trường tìm kiếm), thì ứ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 ý định.

Để chạy tiện ích tự động hoàn thành bằng ý định, hãy làm theo các bước sau:

  1. Sử dụng Autocomplete.IntentBuilder để tạo ý định, chuyển chế độ Autocomplete mong muốn.
  2. Xác định trình chạy kết quả hoạt động registerForActivityResult có thể dùng để chạy ý định và xử lý thông tin dự đoán về địa điểm đã chọn của người dùng trong kết quả.

Tạo ý định tự động hoàn thành

Ví dụ bên dưới sử dụng Autocomplete.IntentBuilder để tạo một ý định nhằm khởi chạy tiện ích tự động hoàn thành dưới dạng một ý định:

Kotlin




    // 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)
    startAutocomplete.launch(intent)

      

Java



    // 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);
    startAutocomplete.launch(intent);

      

Khi sử dụng ý định để chạy tiện ích tự động hoàn thành, bạn có thể chọn chế độ lớp phủ hoặc chế độ hiển thị toàn màn hình. Các ảnh chụp màn hình sau đây lần lượt cho thấy từng chế độ hiển thị:

Khi hiển thị ở chế độ lớp phủ, tiện ích tự động hoàn thành sẽ xuất hiện ở chồng lên giao diện người dùng gọi.
Hình 1: Tiện ích Tự động hoàn thành ở chế độ OVERLAY
Khi được hiển thị ở chế độ toàn màn hình, tiện ích tự động hoàn thành sẽ lấp đầy toàn bộ màn hình.
Hình 2: Tiện ích Tự động hoàn thành ở chế độ TOÀN MÀN HÌNH

Đăng ký lệnh gọi lại cho kết quả ý định

Để nhận thông báo khi người dùng đã chọn một địa điểm, hãy xác định trình chạy registerForActivityResult(). Trình chạy này sẽ chạy hoạt động và xử lý kết quả như trong ví dụ sau. Nếu người dùng chọn một cụm từ gợi ý, thì cụm từ gợi ý đó sẽ được gửi trong ý định có trong đối tượng kết quả. Vì ý định do Autocomplete.IntentBuilder xây dựng, nên phương thức Autocomplete.getPlaceFromIntent() có thể trích xuất đối tượng Địa điểm từ đó.

Kotlin



private val startAutocomplete =
    registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult ->
        if (result.resultCode == Activity.RESULT_OK) {
            val intent = result.data
            if (intent != null) {
                val place = Autocomplete.getPlaceFromIntent(intent)
                Log.i(
                    TAG, "Place: ${place.name}, ${place.id}"
                )
            }
        } else if (result.resultCode == Activity.RESULT_CANCELED) {
            // The user canceled the operation.
            Log.i(TAG, "User canceled autocomplete")
        }
    }

      

Java


private final ActivityResultLauncher<Intent> startAutocomplete = registerForActivityResult(
        new ActivityResultContracts.StartActivityForResult(),
        result -> {
            if (result.getResultCode() == Activity.RESULT_OK) {
                Intent intent = result.getData();
                if (intent != null) {
                    Place place = Autocomplete.getPlaceFromIntent(intent);
                    Log.i(TAG, "Place: ${place.getName()}, ${place.getId()}");
                }
            } else if (result.getResultCode() == Activity.RESULT_CANCELED) {
                // The user canceled the operation.
                Log.i(TAG, "User canceled autocomplete");
            }
        });

      

Nhận các gợi ý địa điểm bằng cách lập trình

Bạn có thể tạo 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 tất cung cấp. Để làm việc này, ứng dụng của bạn phải nhận thông tin dự đoán đị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 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 đối tượng FindAutocompletePredictionsRequest với các thông số sau:

  • Bắt buộc: Chuỗi query chứa văn bản do người dùng nhập.
  • Nên dùng: AutocompleteSessionToken, nhóm các giai đoạn truy vấn và lựa chọn trong hoạt động tìm kiếm 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 hoạt động bắt đầu khi người dùng bắt đầu nhập 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 giới hạn vĩ độ và kinh độ để ràng buộc 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 2 chữ cái (ISO 3166-1 Alpha-2), cho biết (các) quốc gia cần phải đưa ra kết quả.
  • Không bắt buộc: TypeFilter mà bạn có thể sử dụng để giới hạn kết quả cho 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ã hoá địa lý thay vì doanh nghiệp. Hãy sử dụng yêu cầu này để phân biệt các kết quả mà vị trí được chỉ định có thể không xác định.
    • TypeFilter.ADDRESS – Chỉ trả về kết quả tự động hoàn thành có đị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ề các địa điểm là doanh nghiệp.
    • TypeFilter.REGIONS – Chỉ trả về các địa điểm khớp với một trong các kiểu sau:

    • LOCALITY

    • SUBLOCALITY

    • POSTAL_CODE

    • COUNTRY

    • ADMINISTRATIVE_AREA_LEVEL_1

    • ADMINISTRATIVE_AREA_LEVEL_2

    • TypeFilter.CITIES – Chỉ trả về kết quả khớp với LOCALITY hoặc ADMINISTRATIVE_AREA_LEVEL_3.

  • Không bắt buộc: LatLng chỉ định vị trí xuất phát cho yêu cầu. Khi bạn gọi setOrigin(), dịch vụ sẽ trả về khoảng cách tính bằng mét (distanceMeters) so với điểm gốc đượ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ề các loại địa điểm.

Ví dụ bên dưới minh hoạ một lệnh gọi đầy đủ đến PlacesClient.findAutocompletePredictions().

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(PlaceTypes.ADDRESS))
            .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}")
            }
        }

      

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(PlaceTypes.ADDRESS))
            .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());
        }
    });

      

API này sẽ trả về một FindAutocompletePredictionsResponse trong Task. FindAutocompletePredictionsResponse chứa danh sách các đối tượng AutocompletePrediction đại diện cho địa điểm được dự đoán. Danh sách này có thể trống nếu không có địa điểm không xác định nào 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ộ 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ụ: "Tháp Eiffel, Đại lộ Anatole France, Paris, Pháp". Ngoài ra, phương thức này còn 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 mà bạn chọn, bằng cách sử dụng CharacterStyle. Tham số CharacterStyle là không bắt buộc. Hãy đặt giá trị này thành rỗng nếu bạn không cần đánh dấu.
  • 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 đường Pitt".
  • getSecondaryText(CharacterStyle) trả về văn bản phụ của nội dung mô tả địa điểm. Hàm này hữu ích, chẳng hạn như dưới dạng dòng thứ hai khi hiển thị các cụm từ gợi ý tự động hoàn thành. Ví dụ: "APLACE 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 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ượng Place sau 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 phần Thông tin chi tiết về địa điểm. Để biết thông tin chung về mã địa điểm, hãy xem bài viết 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 theo đường thẳng tính bằng mét giữa địa điểm này và điểm gốc được chỉ định trong yêu cầu.

Mã thông báo phiên

Mã thông báo phiên sẽ nhóm các giai đoạn truy vấn và lựa chọn của hoạt động 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 hoạt động 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 truy vấn, theo sau là một lựa chọn địa điểm. Sau khi phiên kết thúc, mã thông báo này không còn hợp lệ nữa; ứng dụng 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ã phiên cho mọi phiên tự động hoàn thành có lập trình (khi bạn nhúng một mảnh hoặc chạy tính năng tự động hoàn thành bằng ý định, API sẽ tự động xử lý việc này).

SDK Địa điểm dành cho Android sử dụng AutocompleteSessionToken để xác định từng phiên. Ứng dụng của bạn phải truyền 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ã địa điểm trong lệnh gọi tiếp theo đến fetchPlace() để 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.

Ràng buộc 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ới 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 cho 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à các 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 các kết quả trong khu vực đã xác định, hãy gọi setLocationBias() (một số kết quả từ 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 mới được trả về).
  • Để chỉ trả về các kết quả phù hợp với một loại địa điểm cụ thể, hãy gọi setTypesFilter() (ví dụ: việc chỉ định TypeFilter.ADDRESS sẽ chỉ trả về các kết quả có địa chỉ chính xác).
  • Để chỉ trả về kết quả trong tối đa 5 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 2 ký tự.

Chênh lệch kết quả đối với một khu vực cụ thể

Để thiên về kết quả tự động hoàn thành tới một khu vực địa lý cụ thể, hãy gọi setLocationBias(), truyền một RectangularBounds. Mã ví dụ sau đây cho thấy việc gọi setLocationBias() trên một thực thể mảnh để thiên vị các đề xuất tự động hoàn thành của nó tới một khu vực ở Sydney, Úc.

Kotlin



    autocompleteFragment.setLocationBias(
        RectangularBounds.newInstance(
            LatLng(-33.880490, 151.184363),
            LatLng(-33.858754, 151.229596)
        )
    )

      

Java


    autocompleteFragment.setLocationBias(RectangularBounds.newInstance(
            new LatLng(-33.880490, 151.184363),
            new LatLng(-33.858754, 151.229596)));

      

Hạn chế kết quả ở một khu vực cụ thể

Để hạn chế kết quả tự động hoàn thành ở 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 của ứng dụng đó tới một khu vực ở Sydney, Úc.

Kotlin



    autocompleteFragment.setLocationRestriction(
        RectangularBounds.newInstance(
            LatLng(-33.880490, 151.184363),
            LatLng(-33.858754, 151.229596)
        )
    )

      

Java


    autocompleteFragment.setLocationRestriction(RectangularBounds.newInstance(
            new LatLng(-33.880490, 151.184363),
            new LatLng(-33.858754, 151.229596)));

      

Lưu ý: Quy định hạn chế này chỉ áp dụng cho toàn bộ các tuyến đường. Kết quả tổng hợp nằm bên ngoài ranh giới hình chữ nhật có thể được trả về dựa trên một tuyến đường trùng lặp với giới hạn về vị trí.

Lọc kết quả theo loại địa điểm hoặc bộ sưu tập loại

Bạn có thể hạn chế kết quả từ yêu cầu tự động hoàn thành để các kết quả đó chỉ trả về một loại địa điểm nhất định. Hãy chỉ định một bộ lọc bằng cách sử dụng các loại địa điểm hoặc tập hợp loại được liệt kê trong Bảng 1, 2 và 3 cho Loại địa điểm. Nếu không có gì được chỉ định, tất cả các loại sẽ được trả về.

Để lọc kết quả tự động hoàn thành, hãy gọi setTypesFilter() để đặt bộ lọc.

Để chỉ định một kiểu hoặc bộ lọc tập hợp kiểu:

  • Gọi setTypesFilter() và chỉ định tối đa 5 giá trị loại từ Bảng 1 và Bảng 2 như trên Loại địa điểm. Giá trị loại được xác định bằng các hằng số trong PlaceTypes.

  • Gọi setTypesFilter() và chỉ định một tập hợp loại từ Bảng 3 được hiển thị trên Loại địa điểm. Giá trị bộ sưu tập được xác định bằng các hằng số trong PlaceTypes.

    Chỉ được dùng một loại duy nhất trong Bảng 3 trong yêu cầu. Nếu chỉ định giá trị từ Bảng 3, thì bạn không thể chỉ định giá trị từ Bảng 1 hoặc Bảng 2. Nếu bạn làm như vậy, thì sẽ có lỗi xảy ra.

Mã ví dụ sau đây gọi setTypesFilter() trên AutocompleteSupportFragment và chỉ định nhiều giá trị loại.

Kotlin



    autocompleteFragment.setTypesFilter(listOf("landmark", "restaurant", "store"))

      

Java


    autocompleteFragment.setTypesFilter(Arrays.asList("landmark", "restaurant", "store"));

      

Ví dụ về mã sau đây cho thấy việc gọi setTypesFilter() trên AutocompleteSupportFragment để thiết lập bộ lọc chỉ trả về kết quả có địa chỉ chính xác bằng cách chỉ định một tập hợp kiểu.

Kotlin



    autocompleteFragment.setTypesFilter(listOf(PlaceTypes.ADDRESS))

      

Java


    autocompleteFragment.setTypesFilter(Arrays.asList(PlaceTypes.ADDRESS, PlaceTypes.ESTABLISHMENT));

      

Ví dụ về mã sau đây cho thấy việc gọi setTypesFilter() trên IntentBuilder để thiết lập 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 tập hợp loại.

Kotlin



    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .setTypesFilter(listOf(PlaceTypes.ADDRESS))
        .build(this)

      

Java


    Intent intent = new Autocomplete.IntentBuilder(
            AutocompleteActivityMode.FULLSCREEN, fields)
            .setTypesFilter(Arrays.asList(PlaceTypes.ADDRESS))
            .build(this);

      

Lọc kết quả theo quốc gia

Để lọc kết quả tự động hoàn thành theo tối đa 5 quốc gia, hãy gọi setCountries() để đặt mã quốc gia. Sau đó, hãy truyền bộ lọc vào 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 ISO 3166-1 Alpha-2 gồm 2 ký tự.

Mã ví dụ sau đây cho thấy việc gọi setCountries() trên AutocompleteSupportFragment, để thiết lập một bộ lọc chỉ trả về kết quả ở các quốc gia đã chỉ định.

Kotlin



    autocompleteFragment.setCountries("AU", "NZ")

      

Java


    autocompleteFragment.setCountries("AU", "NZ");

      

Hạn mức sử dụng

Việc bạn sử dụng Places API, bao gồm cả SDK Địa điểm dành cho Android, không còn bị 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 đây vẫn được áp dụng:

  • Giới hạn số lượng yêu cầu là 6.000 QPM (yêu cầu mỗi phút). Số liệu này đượ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 xác thực 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 dùng dịch vụ tự động hoàn thành theo phương thức lập trình, thì giao diện người dùng của bạn phải cho thấy thuộc tính "Do Google cung cấp" hoặc xuất hiện trong một bản đồ có 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 (thuộc tính bắt buộc sẽ hiển thị theo mặc định).
  • Nếu truy xuất và hiển thị thêm thông tin về địa điểm sau khi nhận địa điểm theo mã nhận dạng, thì bạn cũng phải hiển thị thông tin thuộc tính của bên thứ ba.

Để biết thêm thông tin chi tiết, vui lòng xem tài liệu về mô hình phân bổ.

Tối ưu hoá tính năng 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 của đị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 hoạt động hiệu quả là sử dụng tiện ích Tự động hoàn thành của API JavaScript Maps, Tiện ích Tự động hoàn thành của SDK Địa điểm dành cho Android hoặc SDK Địa điểm dành cho Kiểm soát giao diện người dùng Tự động hoàn thành dành cho iOS
  • Nâng cao sự hiểu biết về các trường dữ liệu thiết yếu của tính năng Tự động hoàn thành địa điểm ngay từ đầu.
  • Các trường xu hướng vị trí và giới hạn vị trí là không bắt buộc nhưng có thể có tác động đáng kể đến hiệu suất của tính năng tự động hoàn thành.
  • Xử lý lỗi để đảm bảo ứng dụng của bạn sẽ xuống cấp nhẹ nếu API trả về lỗi.
  • Hãy đảm bảo ứng dụng của bạn xử lý khi không có lựa chọn 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 địa điểm, hãy sử dụng mặt nạ trường trong tiện ích 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 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 tính năng Mức giá theo 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. Đặt giá theo mỗi yêu cầu được kết hợp với API mã hóa địa lý sẽ tiết kiệm chi phí hơn so với đặt giá Theo 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 người dùng đã chọn, API mã hoá địa lý sẽ cung cấp thông tin này cho ít hơn một cuộc gọi Chi tiết địa điểm.
  • Nếu người dùng chọn một cụm từ gợi ý tự động hoàn thành trong khoảng trung bình 4 yêu cầu cụm từ gợi ý Tự động hoàn thành trở xuống, thì tính năng đặt giá theo Mỗi yêu cầu có thể tiết kiệm chi phí hơn so với đặt giá theo mỗi phiên.
Để được hỗ trợ lựa chọn cách triển khai tính năng Tự động hoàn thành theo địa điểm phù hợp với nhu cầu của bạn, hãy chọn thẻ tương ứng với câu trả lời của bạn cho câu hỏi sau.

Ứ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 thông tin

Sử dụng tính năng Tự động hoàn thành địa điểm dựa trên phiên 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 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 về địa điểm phải sử dụng mã phiên (theo chương trình hoặc tích hợp trong 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 SKU dữ liệu địa điểm áp dụng tuỳ thuộc vào trường dữ liệu địa điểm mà bạn yêu cầu

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. Dữ liệu này bao gồm cả yêu cầu Tự động hoàn thành về địa điểm và yêu cầu Chi tiết địa điểm đối với cụm từ gợi ý đã chọn. Nhớ chỉ định tham số fields để đảm bảo rằng bạn chỉ yêu cầu các trường dữ liệu vị trí mà bạn cần.

Triển khai có lập trình
Sử dụng mã thông báo của phiên với các yêu cầu Tự động hoàn thành địa điểm của bạn. Khi yêu cầu Thông tin chi tiết về địa điểm cho cụm từ gợi ý đã chọn, hãy cung cấp các thông số sau:

  1. Mã địa điểm từ phản hồi Tự động hoàn thành địa điểm
  2. Mã thông báo phiên được dùng trong yêu cầu Tự động hoàn thành địa điểm
  3. Tham số fields chỉ định các trường dữ liệu địa điểm mà bạn cần

Không, chỉ cần địa chỉ và vị trí

API mã hoá địa lý có thể là một lựa chọn tiết kiệm chi phí hơn so với Thông tin chi tiết về địa điểm 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 địa điểm của bạn. Hiệu quả của tính năng Tự động hoàn thành của mỗi ứng dụng sẽ khác nhau tuỳ thuộc vào nội dung mà người dùng đang nhập, nơi ứng dụng đang được sử dụng và việc liệu các phương pháp hay nhất về 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ố lượng ký tự mà người dùng nhập trung bình trước khi chọn một dự đoán Tự động hoàn thành địa điểm 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 địa điểm trong tối đa 4 yêu cầu không?

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ã phiên và gọi API Mã hoá địa lý trên thông tin dự đoán địa điểm đã chọn.
API mã hoá địa lý cung cấp địa chỉ và vĩ độ/kinh độ với giá 0,005 USD cho mỗi yêu cầu. Việc thực hiện bốn 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 Mỹ, do đó, tổng chi phí của 4 yêu cầu cộng với lệnh gọi API mã hoá địa lý về thông tin dự đoán địa điểm đã chọn sẽ là 0,01632 đô la, thấp hơn giá của tính năng Tự động hoàn thành cho mỗi phiên là 0,017 đô la Mỹ/phiên.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ọ muốn chỉ bằng ít ký tự hơn nữa.

Không

Sử dụng tính năng Tự động hoàn thành địa điểm dựa trên phiên 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 muốn thực hiện trước khi người dùng chọn dự đoán Tự động hoàn thành địa điểm vượt quá chi phí định giá mỗi phiên, nên việc triển khai tính năng Tự động hoàn thành địa điểm của bạn phải sử dụng mã phiên cho cả yêu cầu Tự động hoàn thành địa điểm và yêu cầu Chi tiết địa điểm được liên kết với tổng chi phí là 0,017 USD 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. Dữ liệu này bao gồm cả yêu cầu Tự động hoàn thành về địa điểm và yêu cầu Chi tiết địa điểm đối với 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 Dữ liệu cơ bản.

Triển khai có lập trình
Sử dụng mã thông báo của phiên với các yêu cầu Tự động hoàn thành địa điểm của bạn. Khi yêu cầu Thông tin chi tiết về địa điểm cho cụm từ gợi ý đã chọn, hãy cung cấp các thông số sau:

  1. Mã địa điểm từ phản hồi Tự động hoàn thành địa điểm
  2. Mã thông báo phiên được dùng trong yêu cầu Tự động hoàn thành địa điểm
  3. Tham số fields chỉ đị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 của đị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 của địa điểm cho đến khi người dùng nhập ba hoặc bốn ký tự đầu tiên để ứng dụng của bạn đưa ra ít yêu cầu hơn. Ví dụ: việc thực hiện yêu cầu Tự động hoàn thành địa điểm cho từng 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 7 ký tự rồi chọn một dự đoán mà bạn thực hiện một yêu cầu API mã hóa địa lý, thì tổng chi phí sẽ là 0,01632 đô la (4 * 0,00283 đô la Mỹ cho mỗi yêu cầu + 0,005 đô la Mã hóa địa lý).1

Nếu việc trì hoãn các yêu cầu có thể khiến yêu cầu có lập trình trung bình của bạn dưới 4, bạn có thể làm theo hướng dẫn triển khai Tự động hoàn thành địa điểm thực hiện bằng API mã hóa địa lý. Xin lưu ý rằng người dùng có thể xem các yêu cầu trì hoãn là độ trễ, vì người dùng này có thể sẽ thấy các cụm từ gợi ý mỗi khi nhấn phím mới.

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 trong ít ký tự hơn.


  1. Chi phí liệt kê tại đây được tính theo 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ác phương pháp hay nhất về hiệu suất

Các nguyên tắc sau đây mô tả các cách tối ưu hóa hiệu suất của tính năng Tự động hoàn thành theo địa điểm:

  • Thêm các hạn chế theo quốc gia, xu hướng vị trí và lựa chọn ưu tiên về ngôn ngữ (đối với các phương thức triển khai có lập trình) vào phương thức triển khai tính năng Tự động hoàn thành theo địa điểm. Không cần thiết lập lựa chọn ưu tiên về ngôn ngữ cho các tiện ích vì chúng chọn lựa chọn ưu tiên về ngôn ngữ trên 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 đị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 ý Tự động hoàn thành, thường là do không có cụm từ gợi ý nào trong số đó là địa chỉ kết quả mong muốn, thì bạn có thể sử dụng lại thông tin mà người dùng nhập ban đầu để tìm cách 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 thông tin đầu vào ban đầu của người dùng trong lệnh gọi đến API mã hoá địa lý.
    • 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 Tìm địa điểm. Nếu kết quả chỉ được mong đợi ở một khu vực cụ thể, hãy sử dụng tính năng thiên về vị trí.
    Có một số trường hợp khác mà bạn nên quay lại sử dụng API Mã hoá địa lý:
    • Người dùng nhập địa chỉ cơ sở phụ ở những quốc gia chưa hỗ trợ tính năng Tự động hoàn thành cho địa điểm, ví dụ: Cộng hoà Séc, Estonia và Lithuania. Ví dụ: địa chỉ bằng tiếng Séc "StroupeAccessnického 3191/17, Praha" sẽ đưa ra thông tin 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ố

Mặc dù có nhiều loại lỗi có thể xảy ra, nhưng phần lớn lỗi mà ứng dụng của bạn có thể gặp phải thường 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 đúng cách) hoặc lỗi hạn mức (ứng dụng của bạn đã vượt quá hạn mức). Hãy xem phần 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 các chế độ điều khiển tự động hoàn thành sẽ được trả về trong lệnh gọi lại onActivityResult(). Hãy gọi Autocomplete.getStatus() để nhận thông báo trạng thái của kết quả.