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

Nhà phát triển ở Khu vực kinh tế Châu Âu (EEA)

Nếu địa chỉ thanh toán của bạn ở Khu vực kinh tế Châu Âu, thì kể từ ngày 8 tháng 7 năm 2025, Điều khoản dịch vụ của Nền tảng Google Maps ở EEA sẽ áp dụng cho việc bạn sử dụng Dịch vụ. Chức năng này thay đổi theo khu vực. Tìm hiểu thêm.

Dịch vụ tự động hoàn thành trong Places SDK cho Android trả về các cụm từ dự đoán 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 về địa điểm, chẳng hạn 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 theo những cách sau:

• Thêm một 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 nhất quán cho người dùng.
• Nhận 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ó 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ị một 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 mục, một thực thể Place sẽ được trả về. Sau đó, ứng dụng của bạn có thể dùng thực thể này để lấy 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:

• Cách 1: Nhúng AutocompleteSupportFragment.
• Cách 2: Dùng một ý định để chạy hoạt động tự động hoàn thành.

Cách 1: Nhúng một AutocompleteSupportFragment

Để thêm một 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 một trình nghe vào hoạt động hoặc mảnh của bạn.

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 này không có đường viền hoặc nền. Để mang lại giao diện 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 dùng mảnh Autocomplete và cần ghi đè onActivityResult, bạn phải gọi super.onActivityResult, nếu không mảnh này 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 biết cách tạo một tham chiếu đến mảnh và thêm một 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 một ý đị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ừ một biểu tượng thay vì một 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 một ý định.

Lưu ý: Bạn không cần thực hiện các bước này nếu đang nhúng một mảnh.

Thận trọng: KHÔNG khởi chạy AutcompleteActivity trực tiếp. Thay vào đó, hãy dùng một ý định để khởi chạy Autocomplete (PlaceAutocomplete trong thư viện tương thích).

Để 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. Dùng Autocomplete.IntentBuilder để tạo một ý định, truyền chế độ Autocomplete mong muốn.
2. Xác định một trình chạy kết quả hoạt động registerForActivityResult có thể dùng để chạy ý định và xử lý kết quả dự đoán địa điểm mà người dùng đã chọn.

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

Hình 1: Tiện ích tự động hoàn thành ở chế độ OVERLAY

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ẽ khởi 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 đề xuất, đề xuất đó sẽ được gử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 Place từ ý định đó.

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 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 được các 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 tên địa điểm và/hoặc địa chỉ được dự đoán từ Autocomplete API bằng cách gọi PlacesClient.findAutocompletePredictions(), truyền một đối tượng FindAutocompletePredictionsRequest có các tham số sau:

• Bắt buộc: Một chuỗi query chứa văn bản do người dùng nhập.
• Đề xuấ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 một cụm từ tìm kiếm và kết thúc khi họ chọn một địa điểm.
• Được đề xuất: Một đối tượng RectangularBounds, chỉ định ranh giới vĩ độ và kinh độ để giới hạn kết quả trong khu vực đượ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 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: TypeFilter, bạn có thể dùng để giới hạn kết quả cho loại địa điểm được chỉ định. Các loại địa điểm sau đây được hỗ trợ:

  • TypeFilter.GEOCODE – Chỉ trả về kết quả mã hoá địa lý, chứ không phải doanh nghiệp. Hãy 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 phù hợ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ề những kết quả khớp với LOCALITY hoặc ADMINISTRATIVE_AREA_LEVEL_3.

• Không bắt buộc: Một LatLng chỉ định vị trí của nguồn gốc 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) từ điểm xuất phát đã chỉ định cho từng kết quả dự đoán tự động 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ụ dưới đây minh hoạ một lệnh gọi hoàn chỉnh đế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 trả về FindAutocompletePredictionsResponse trong Task. FindAutocompletePredictionsResponse chứa danh sách các đối tượng AutocompletePrediction đại diện cho những địa điểm được dự đoán. Danh sách có thể trống nếu không có địa điểm nào đã 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 văn nội dung mô tả về 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 bằng 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. Đặt thành giá trị 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 Pitt Street".
• getSecondaryText(CharacterStyle) trả về văn bản phụ của nội dung mô tả về 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ừ dự đoán tự động hoàn thành. Ví dụ: "Avenue Anatole France, Paris, Pháp" 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ượng Place sau này. Để biết thêm thông tin về mã địa điểm trong Places SDK for 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 Tổng quan về mã địa điểm.
• getPlaceTypes() trả về danh sách các loại địa điểm được 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.

Lưu ý: Để biết thêm thông tin về cách khởi chạy PlacesClient, hãy xem phần Khởi chạy ứng dụng Places API.

Bạn có thể sử dụng CancellationToken để cố gắng huỷ yêu cầu đối với bất kỳ lớp yêu cầu nào (ví dụ: FetchPlaceRequest). Việc huỷ được thực hiện trên cơ sở nỗ lực tối đa. Sau khi yêu cầu huỷ được gửi, hệ thống sẽ không trả về phản hồi. Việc phát hành mã huỷ KHÔNG đảm bảo rằng một yêu cầu cụ thể sẽ bị huỷ và bạn vẫn có thể bị tính phí cho yêu cầu đó ngay cả khi không có phản hồi nào được trả về.

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 cụm 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 một 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, 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ệ; ứ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 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 một ý định, API sẽ tự động xử lý việc này).

Places SDK for Android 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 đế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.

Lưu ý: Nếu ứng dụng của bạn đang dùng tiện ích Tự động hoàn thành, bạn không cần triển khai các phiên vì tiện ích này sẽ tự động xử lý các phiên ở chế độ nề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à các API tự động hoàn thành có lập trình.

Để hạn chế 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ả từ bên ngoài khu vực đã xác định vẫn có thể được trả về).
• Để chỉ hiện 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ề những kết quả phù hợp với một loại địa điểm cụ thể, hãy gọi setTypesFilter() (ví dụ: khi chỉ định TypeFilter.ADDRESS, bạn sẽ chỉ nhận được 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(). Bạn phải truyền quốc gia dưới dạng mã quốc gia gồm 2 ký tự, tương thích với ISO 3166-1 Alpha-2.

Thiên vị kết quả cho một khu vực cụ thể

Để điều chỉnh kết quả tự động hoàn thành theo một khu vực địa lý cụ thể, hãy gọi setLocationBias(), truyền một RectangularBounds. Ví dụ về mã sau đây cho thấy cách gọi setLocationBias() trên một thực thể mảnh để điều chỉnh các đề xuất tự động hoàn thành cho 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. Ví dụ về mã sau đây cho thấy cách gọi setLocationRestriction() trên một thực thể mảnh để điều chỉnh các đề xuất tự động hoàn thành của thực thể đó theo 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 ý: 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 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 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ể hạn chế kết quả từ 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 một 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 bạn không chỉ định gì, thì 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.

Cách chỉ định bộ lọc loại hoặc bộ lọc tập hợp loại:

• Gọi setTypesFilter() và chỉ định tối đa 5 giá trị type trong Bảng 1 và Bảng 2 xuất hiện trên Các loại địa điểm. Các 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 type collection trong Bảng 3 xuất hiện trên Place Types (Các 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.

  Bạn chỉ được phép dùng 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.

Kotlin

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

      

Java

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

    autocompleteFragment.setTypesFilter(listOf(PlaceTypes.ADDRESS))

      

Java

    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 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 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 đến một mảnh hoặc ý định. Bạn phải truyền quốc gia dưới dạng mã quốc gia gồm 2 ký tự, tương thích với ISO 3166-1 Alpha-2.

Ví dụ về mã sau đây cho thấy cách 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.

Kotlin

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

      

Java

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

      

Hạn mức sử dụng

Mức sử dụng Places API, bao gồm cả Places SDK cho Android, sẽ 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 về tốc độ là 6.000 QPM (yêu cầu mỗi phút). Chỉ số 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ả các ứng dụng sử dụng thông tin đăng nhập của cùng một dự án.

Hiển thị thông tin ghi nhận quyền tác giả trong ứng dụng

• Nếu ứng dụng của bạn sử 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 hiển thị thông tin ghi công "Do Google cung cấp" hoặc xuất hiện trong một bản đồ có thương hiệu của 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ì khác (theo mặc định, thông tin ghi nhận quyền tác giả bắt buộc sẽ xuất hiện).
• Nếu truy xuất và hiển thị thông tin bổ sung về địa điểm sau khi nhận địa điểm theo mã nhận dạng, bạn cũng phải hiển thị thông tin ghi nhận quyền sở hữu 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 Place Autocomplete (Cũ)

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ụ Place Autocomplete (Cũ).

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 địa điểm (Cũ) của Maps JavaScript API, tiện ích Tự động hoàn thành địa điểm (Cũ) của Places SDK cho Android hoặc thành phần kiểm soát giao diện người dùng Tự động hoàn thành địa điểm (Cũ) của Places SDK 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 hoàn thành địa điểm (Phiên bản cũ).
• 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 giảm hiệu suất một cách thích hợp 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 địa điểm (Cũ), hãy sử dụng mặt nạ trường trong các tiện ích Chi tiết về địa điểm (Cũ) và Tự động hoàn thành địa điểm (Cũ) để chỉ trả về các trường dữ liệu về đị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 theo chương trình tính năng Tự động hoàn thành địa điểm (Cũ) để truy cập vào mức giá Theo yêu cầu và yêu cầu kết quả Geocoding API về địa điểm đã chọn thay vì Chi tiết về địa điểm (Cũ). 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 cả hai điều kiện sau đều được đáp ứng:

• 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ì Geocoding API sẽ cung cấp thông tin này cho ít hơn một lệnh gọi Place Details (Legacy).
• 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 gợi ý tự động hoàn thành địa điểm (phiên bản cũ) hoặc ít hơn, 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.

Để được trợ giúp chọn chế độ triển khai tính năng Tự động hoàn thành địa điểm (cũ) 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 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 Place Autocomplete dựa trên phiên (Cũ) cùng với tính năng Place Details (Cũ).
Vì ứng dụng của bạn yêu cầu có Thông tin về địa điểm (cũ) như tên địa điểm, trạng thái kinh doanh hoặc giờ hoạt động, nên việc triển khai tính năng Tự động hoàn thành địa điểm (cũ) phải sử dụng mã thông báo phiên (theo phương pháp có lập trình hoặc được tích hợp vào các tiện ích JavaScript, Android hoặc iOS). mỗi phiên cộng với SKU Dữ liệu về địa điểm hiện hành, tuỳ thuộc vào những trường dữ liệu về đị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. Điều này bao gồm cả yêu cầu Place Autocomplete (Cũ) và yêu cầu Place Details (Cũ) đố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 về địa điểm 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 Place Autocomplete (Cũ). Khi yêu cầu Thông tin chi tiết về địa điểm (Phiên bản cũ) về kết quả dự đoán đã chọn, hãy thêm các tham số sau:

1. Mã địa điểm trong phản hồi Place Autocomplete (Cũ)
2. Mã thông báo phiên được dùng trong yêu cầu Place Autocomplete (Cũ)
3. Tham số fields chỉ định các trường dữ liệu về địa điểm 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 (Legacy) cho ứng dụng của bạn, tuỳ thuộc vào hiệu suất của việc sử dụng Place Autocomplete (Legacy). Mức độ hiệu quả của tính năng Tự động hoàn thành địa điểm (Phiên bản cũ) của mỗi ứng dụng sẽ khác nhau, tuỳ thuộc vào nội dung mà người dùng nhập, vị trí sử dụng ứng dụng và việc bạn có triển khai các phương pháp hay nhất để tối ưu hoá hiệu suất 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à người dùng nhập trước khi chọn một kết quả dự đoán của tính năng Tự động hoàn thành địa điểm (Phiên bản cũ) trong ứng dụng của bạn.

Trung bình, người dùng của bạn có chọn một kết quả dự đoán của tính năng Tự động hoàn thành địa điểm (Phiên bản cũ) trong tối đa 4 yêu cầu không?

Có

Triển khai chương trình Place Autocomplete (Legacy) 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 địa điểm đã chọn.
Geocoding API cung cấp địa chỉ và toạ độ vĩ độ/kinh độ. Thực hiện 4 yêu cầu Place Autocomplete (Legacy) – Per Request (Tự động hoàn thành địa điểm (phiên bản cũ) – Theo yêu cầu) cộng với một lệnh gọi Geocoding API (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í Place Autocomplete (Legacy) (Tự động hoàn thành địa điểm (phiên bản cũ)) theo mỗi phiên.¹

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 thông tin dự đoán mà họ đang tìm kiếm chỉ trong vài ký tự.

Không

Sử dụng tính năng Place Autocomplete dựa trên phiên (Cũ) cùng với tính năng Place Details (Cũ).
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 kết quả dự đoán của tính năng Tự động hoàn thành địa điểm (Cũ) vượt quá chi phí của mức giá Theo phiên, nên việc triển khai tính năng Tự động hoàn thành địa điểm (Cũ) của bạn phải sử dụng mã thông báo phiên cho cả yêu cầu Tự động hoàn thành địa điểm (Cũ) và yêu cầu Chi tiết về địa điểm (Cũ) được liên kết cho mỗi phiê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. Điều này bao gồm cả yêu cầu Place Autocomplete (Cũ) và yêu cầu Place Details (Cũ) đố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 theo chương trình
Sử dụng mã thông báo phiên với các yêu cầu Place Autocomplete (Cũ). Khi yêu cầu Thông tin chi tiết về địa điểm (Phiên bản cũ) về kết quả dự đoán đã chọn, hãy thêm các tham số sau:

1. Mã địa điểm trong phản hồi Place Autocomplete (Cũ)
2. Mã thông báo phiên được dùng trong yêu cầu Place Autocomplete (Cũ)
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 trì hoãn các yêu cầu về tính năng Tự động hoàn thành địa điểm (phiên bản cũ)
Bạn có thể áp dụng các chiến lược như trì hoãn yêu cầu về tính năng Tự động hoàn thành địa điểm (phiên bản cũ) 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ụ: việc đưa ra yêu cầu cho tính năng Tự động hoàn thành địa điểm (Phiên bản cũ) 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 7 ký tự rồi chọn một cụm từ dự đoán mà bạn đưa ra một yêu cầu Geocoding API, thì tổng chi phí sẽ là 4 yêu cầu Tự động hoàn thành địa điểm (Phiên bản cũ) + Geocoding.¹

Nếu việc trì hoãn các yêu cầu có thể giúp yêu cầu trung bình theo chương trình của bạn dưới 4, thì bạn có thể làm theo hướng dẫn để triển khai tính năng Place Autocomplete (Cũ) hiệu quả bằng Geocoding API. Xin lưu ý rằng người dùng có thể coi việc trì hoãn các yêu cầu là độ trễ. Họ có thể mong đợi nhìn thấy các cụm từ dự đoán sau mỗi lần nhấn phím mới.

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.

---

1. Để biết chi phí, hãy xem danh sách giá của Nền tảng Google Maps.

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 địa điểm (Phiên bản cũ):

• Thêm các quy định hạn chế về quốc gia, độ lệch vị trí và (đối với các cách triển khai theo chương trình) lựa chọn ưu tiên về ngôn ngữ vào cách triển khai tính năng Tự động hoàn thành địa điểm (Phiên bản cũ). Không cần lựa chọn ưu tiên về ngôn ngữ đối với các tiện ích vì chúng 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 Place Autocomplete (Legacy) đi kèm với bản đồ, bạn có thể điều chỉnh vị trí theo khung hiển thị bản đồ.
• Trong trường hợp người dùng không chọn một trong các kết quả dự đoán của tính năng Tự động hoàn thành địa điểm (phiên bản cũ), thường là do không có kết quả dự đoán nào là địa chỉ mà họ 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 chỉ muốn người dùng 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 một 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 Tìm địa điểm (Phiên bản cũ). Nếu chỉ mong đợi kết quả ở một khu vực cụ thể, hãy sử dụ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 Geocoding API bao gồm:
  • 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 địa điểm (phiên bản cũ).
  • 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 loại lỗi, nhưng phần lớn các 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ụ: bạn đã sử dụng sai khoá API 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 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ế độ kiểm soát tính năng 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ả.