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

Dịch vụ tự động hoàn thành trong SDK Địa điểm dành cho Android trả về các dự đoán về địa điểm để phản hồi 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 điền sẽ trả về các đề xuất cho địa điểm như doanh nghiệp, địa chỉ, mã cộng và đ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 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.
• Nhận thông tin dự đoán về địa điểm bằng cách lập trình để tạo ra trải nghiệm người dùng được 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ó chức năng tự động hoàn thành tích hợp. 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 để người dùng chọn. Khi người dùng chọn một địa điểm, một thực thể Place sẽ được trả về. Sau đó, ứng dụng của bạn có thể sử dụng thực thể này để lấy 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.
• Cách 2: Sử dụng ý định để chạy hoạt động tự động hoàn thành.

Cách 1: Nhúng AutocompleteSupportFragment

Để 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.

Thêm AutocompleteSupportFragment 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 không có đường viền hoặc nền. Để cung cấp giao diện nhất quán, hãy lồng mảnh này 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ẽ 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. Mã sau đây cho thấy cách tạo tham chiếu đến mảnh và thêm trình nghe vào AutocompleteSupportFragment:

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

      

    // 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 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ì trường tìm kiếm), ứng dụng 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:

1. Sử dụng Autocomplete.IntentBuilder để tạo một ý định, truyề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 ý định chạy tiện ích tự động hoàn thành dưới dạng ý định:

    // 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)

      

    // 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 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 cho thấy từng chế độ hiển thị tương ứng:

Đă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ẽ khởi chạy hoạt động và cũng xử lý kết quả như trong ví dụ sau. Nếu người dùng đã chọn một nội dung dự đoán, thì nội dung đó sẽ được phân phối trong ý định có trong đối tượng kết quả. Vì ý định được tạo bởi Autocomplete.IntentBuilder, nên phương thức Autocomplete.getPlaceFromIntent() có thể trích xuất đối tượng Địa điểm từ ý định đó.

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

      

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 thông tin dự đoán về địa điểm theo phương thức 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 cho giao diện người dùng do tiện ích tự động hoàn thành cung cấp. Để làm được việc này, ứng dụng của bạn phải nhận thông tin dự đoán về địa điểm bằng cách lập trình. Ứng dụng của bạn có thể nhận danh sách tên địa điểm và/hoặc địa chỉ đượ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 tham số sau:

• Bắt buộc: Chuỗi query chứ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 lượt 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 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 các giới hạn vĩ độ và kinh độ để giới hạn kết quả ở 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 mà kết quả sẽ bị hạn chế.

• Không bắt buộc: Một TypeFilter mà bạn có thể sử dụng để giới hạn kết quả ở loại địa điểm đã chỉ định. Sau đây là các loại địa điểm được hỗ trợ:

  • TypeFilter.GEOCODE – Chỉ trả về kết quả mã hoá địa lý, thay vì các doanh nghiệp. Sử dụng yêu cầu này để phân biệt kết quả khi 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. 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 khớp với một trong các loại 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í gốc của 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) từ điểm xuất phát được chỉ định, cho mỗi dự đoán 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 cho thấy một lệnh gọi hoàn chỉnh đến PlacesClient.findAutocompletePredictions().

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

      

    // 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 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 có thể trống nếu không có địa điểm nào được biết 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ụ: "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 mô tả khớp với nội dung tìm kiếm bằng một kiểu mà bạn chọn, sử dụng CharacterStyle. Bạn không bắt buộc phải sử dụng tham số CharacterStyle. Đặt giá trị này thành rỗng 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 hiển thị dòng thứ hai khi hiển thị nội dung dự đoán 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à giá trị nhận dạng văn bản giúp xác định duy nhất một địa điểm. Bạn có thể sử dụng mã này để 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 phần 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 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 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 kết thúc, mã thông báo 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. 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 phương thứ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 một ý đị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 cùng một 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.

Giới hạn kết quả tự động hoàn thành

Bạn có thể giới hạn kết quả tự động hoàn thành ở 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 theo 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 vẫn có thể đượ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ề những kết quả tuân thủ 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ề những kết quả có địa chỉ chính xác).
• Để chỉ trả về kết quả trong tối đa 5 quốc gia được chỉ định, hãy gọi setCountries(). Quốc gia phải được truyền dưới dạng mã quốc gia gồm hai ký tự, tương thích với ISO 3166-1 Alpha-2.

Kết quả thiên vị một khu vực cụ thể

Để thiên vị kết quả tự động hoàn thành cho một khu vực địa lý cụ thể, hãy gọi setLocationBias(), truyền RectangularBounds. Mã ví dụ sau đây cho thấy cách 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 cho một khu vực của Sydney, Úc.

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

      

    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 RectangularBounds. Mã ví dụ sau đây cho thấy cách 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 mảnh đó cho một khu vực của Sydney, Úc.

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

      

    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ộ tuyến đường, kết quả tổng hợp nằm ngoài giới hạn hình chữ nhật có thể được trả về dựa trên tuyến đường trùng lặp với quy định hạn chế 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ể giới hạn kết quả của một yêu cầu tự động hoàn thành để chỉ trả về một loại địa điểm nhất định. Chỉ định bộ lọc bằ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 trên trang Loại địa điểm. Nếu bạn không chỉ định loại nào, thì tất cả các loại đều đượ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 bộ lọc loại hoặc bộ lọc bộ sưu tập loại:

• Gọi setTypesFilter() và chỉ định tối đa 5 giá trị type (loại) trong Bảng 1 và Bảng 2 hiển thị trên Place Types (Loại địa điểm). Các giá trị loại được định nghĩa bằng 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.

  Yêu cầu chỉ được phép chứa một loại trong Bảng 3. 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, lỗi sẽ xảy ra.

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

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

      

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

      

Ví dụ về mã sau đây cho thấy cách gọi setTypesFilter() trên AutocompleteSupportFragment để đặ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.

    autocompleteFragment.setTypesFilter(listOf(PlaceTypes.ADDRESS))

      

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

      

Ví dụ về mã sau đây cho thấy cách gọi setTypesFilter() trên IntentBuilder để đặ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.

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

      

    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 thành tối đa 5 quốc gia, hãy gọi setCountries() để đặt mã quốc gia. Sau đó, truyền bộ lọc đến một mảnh hoặc ý định. Quốc gia phải được truyền dưới dạng mã quốc gia gồm hai chữ cái, tương thích với ISO 3166-1 Alpha-2.

Mã ví dụ sau đây cho thấy cách gọi setCountries() trên AutocompleteSupportFragment để đặt bộ lọc chỉ trả về kết quả trong các quốc gia được chỉ định.

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

      

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

      

Hạn mức sử dụng

Việc sử dụng API Địa điểm (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) nữa. Tuy nhiên, các giới hạn sử dụng sau đây vẫn được áp dụng:

• Giới hạn tốc độ là 6.000 QPM (yêu cầu mỗi phút). Giá trị 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ị thông tin phân bổ trong ứng dụng

• Nếu ứng dụng của bạn sử dụng dịch vụ tự động điền theo phương thức lập trình, thì giao diện người dùng của bạn phải hiển thị thông tin ghi công "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, bạn không cần làm gì thêm (mục phân bổ bắt buộc sẽ hiển thị theo mặc định).
• Nếu truy xuất và hiển thị thông tin bổ sung về địa điểm sau khi lấy một địa điểm theo mã nhận dạng, thì bạn cũng phải hiển thị thông tin phân bổ của bên thứ ba.

Để biết thêm thông tin, hãy xem tài liệu về phân bổ.

Tối ưu hoá tính năng Tự động hoàn thành của Place

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 giao diện người dùng hoạt động là sử dụng Tiện ích tự động hoàn thành API Maps JavaScript, Tiện ích tự động hoàn thành SDK Địa điểm dành cho Android hoặc Chế độ điều khiển giao diện người dùng tự động hoàn thành SDK Địa điểm dành cho iOS
• Ngay từ đầu, hãy tìm hiểu về các trường dữ liệu cần thiết của tính năng Tự động điền địa điểm.
• Bạn không bắt buộc phải sử dụng các trường thiên vị vị trí và hạn chế vị trí, nhưng các trường này có thể ảnh hưởng đáng kể đến hiệu suất của tính năng 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 giảm hiệu suất 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 một 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 điền địa điểm, hãy sử dụng mặt nạ trường trong tiện ích Chi tiết địa điểm và Tự động điền đị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 Giá theo yêu cầu và yêu cầu Kết quả của API Địa chỉ về địa điểm đã chọn thay vì Thông tin chi tiết về địa điểm. Giá theo yêu cầu kết hợp với API Địa chỉ được mã hoá địa lý sẽ tiết kiệm chi phí hơn so với giá theo phiên (dựa trên phiên) nếu đáp ứng cả hai điều kiện sau:

• Nếu bạn chỉ cần vĩ độ/kinh độ hoặc địa chỉ của địa điểm mà người dùng đã chọn, thì API Địa chỉ được mã hoá địa lý sẽ cung cấp thông tin này với chi phí thấp hơn một lệnh gọi Thông tin chi tiết về đị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 trung bình 4 yêu cầu cụm từ gợi ý tự động hoàn thành 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 thông tin dự đoán đã chọn không?

Các phương pháp hay nhất về hiệu suất

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

• Thêm các quy định hạn chế về quốc gia, tính năng thiên vị vị trí và lựa chọn ưu tiên về ngôn ngữ (đối với việc triển khai theo phương thức lập trình) vào quá trình triển khai tính năng Tự động hoàn thành địa điểm. Bạn không cần lựa chọn ưu tiên về ngôn ngữ cho tiện ích vì các tiện ích sẽ chọn lựa chọn ưu tiên về ngôn ngữ 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 địa điểm đ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, thường là vì 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 dữ liệu đầ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 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 bạn chỉ mong đợi kết quả ở một khu vực cụ thể, hãy sử dụng tính năng thiên vị vị trí.
  Các trường hợp khác mà bạn nên quay lại sử dụng API Địa chỉ được mã hoá địa lý bao gồm:
  • Người dùng nhập địa chỉ cơ sở phụ, chẳng hạn như địa chỉ của các căn hộ hoặc căn phòng cụ thể trong một toà nhà. Ví dụ: địa chỉ bằng tiếng Séc "Stroupežnického 3191/17, Praha" sẽ đưa ra một phần nội dung gợi ý 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ố đ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.

Khắc phục sự cố

Mặc dù có thể xảy ra nhiều lỗi, 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 sai khoá API hoặc định cấu hình sai khoá API) 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 Hạn mức sử dụng để biết thêm thông tin về hạn mức.

Các lỗi xảy ra trong quá trình 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(). Gọi Autocomplete.getStatus() để nhận thông báo trạng thái cho kết quả.