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 SDK địa điểm dành cho Android trả về vị trí để phản hồi các truy vấn tìm kiếm của người dùng. Khi người dùng nhập, dịch vụ tự động hoàn thành sẽ trả về đề 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 để lưu 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 theo phương thức lập trình để tạo 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ó tích hợp sẵn tính năng tự động hoàn thành của Google. 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 địa điểm được dự đoán để chọn. Khi người dùng lựa chọn, Place thực thể được trả về mà sau đó ứng dụng có thể dùng để 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ách 1: Nhúng một AutocompleteSupportFragment.
• Cách 2: Sử dụng một ý định để chạy hoạt động tự động hoàn thành.

Cách 1: Nhúng một 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 AutomaticSupportFragment 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 một hoạt động Bố cục XML. Ví dụ:

<fragment android:id="@+id/autocomplete_fragment"
  android:layout_width="match_parent"
  android:layout_height="wrap_content"
  android:name="com.google.android.libraries.places.widget.AutocompleteSupportFragment"
  />

• Theo mặc định, mảnh này không có đường viền hoặc nền. Để cung cấp một giao diện trực quan nhất quán, lồng mảnh trong một bố cục khác như một phần tử CardView.
• Nếu bạn đ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 hàm thì mảnh này sẽ không hoạt động chính xác.

Thêm PlaceSelectionListener vào một hoạt động

PlaceSelectionListener xử lý việc trả về một địa điểm theo yêu cầu của người dùng lựa chọn. Đoạn mã sau đây cho thấy việc tạo 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 luồng điều hướng khác (ví dụ: để kích hoạt trải nghiệm tự động hoàn thành từ một biểu tượng thay vì một trường tìm kiếm), ứng dụng của bạn có thể khởi chạy tính năng tự động hoàn thành bằng cách sử dụng một ý định.

Lưu ý: Những bước này không cần thiết nếu bạn đang nhúng .

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

Để 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 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 để khởi chạy ý định và xử lý địa điểm mà người dùng đã chọn dự đoán 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 khởi chạy tiện ích tự động hoàn thành dưới dạng ý đị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 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 hiển thị từng chế độ hiển thị tương ứng:

Hình 1: Tiện ích Tự động hoàn thành ở chế độ TRÙNG LẶP

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() 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 cụm từ gợi ý, điều đó sẽ được phân phối trong ý định chứa trong đối tượng kết quả. Vì ý định được tạo bởi Autocomplete.IntentBuilder, 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 gợi ý đị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 thế cho giao diện người dùng do tính năng tiện ích tự động hoàn thành. Để làm được điều này, ứng dụng của bạn phải nhận được 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ể tải danh sách tên địa điểm được dự đoán và/hoặc địa chỉ từ API tự động hoàn thành bằng cách gọi PlacesClient.findAutocompletePredictions()! truyền một FindAutocompletePredictionsRequest bằng 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.
• Nên dùng: Đáp AutocompleteSessionToken! Nhóm này nhóm các giai đoạn truy vấn và lựa chọn trong tìm kiếm của người dùng thành các nhóm cho mục đích thanh toán. Phiên bắt đầu khi người dùng bắt đầu nhập và kết thúc khi họ chọn một địa điểm.
• Nên dùng: RectangularBounds Đối tượng này chỉ định giới hạn vĩ độ và kinh độ để giới hạn kết quả ở khu vực được chỉ định.
• Không bắt buộc: Một hoặc nhiều quốc gia gồm hai chữ cái (ISO 3166-1) Alpha-2), cho biết (các) quốc gia cần nhận kết quả bị hạn chế.

• Không bắt buộc: A TypeFilter! mà bạn có thể sử dụng để hạn chế kết quả cho loại địa điểm được chỉ định. Chiến lược phát hành đĩa đơn 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ì của chúng tôi. Sử dụng yêu cầu này để phân biệt kết quả trong đó giá trị được chỉ định vị trí có thể là chưa xác định.
  • TypeFilter.ADDRESS – Chỉ trả về kết quả tự động hoàn thành có địa chỉ chính xác của bạn. Sử dụng loại này khi bạn biết người dùng đang tìm kiếm địa chỉ được chỉ định đầy đủ.
  • TypeFilter.ESTABLISHMENT – Chỉ trả về các địa điểm của chúng tôi.

  • TypeFilter.REGIONS – Chỉ trả về các đị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í điểm 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ừ giá trị được chỉ định nguồn gốc của 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ề đị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().

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 trả về một FindAutocompletePredictionsResponse trong Task. FindAutocompletePredictionsResponse chứa danh sách AutocompletePrediction các đối tượng đại diện cho địa điểm dự đoán. Danh sách này có thể trống, nếu không có địa điểm đã 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 địa điểm chi tiết:

• getFullText(CharacterStyle) sẽ 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à phụ. Ví dụ: "Tháp Eiffel, Đại lộ Anatole France, Paris, Pháp". Ngoài ra, phương pháp này cho phép bạn đánh dấu các phần của mô tả khớp với nội dung tìm kiếm theo kiểu mà bạn chọn, 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 thực hiện 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) sẽ trả về văn bản thành phần con của một nội dung mô tả địa điểm. Điều này rất hữu ích, đối với chẳng hạn như dòng thứ hai khi hiện các cụm từ gợi ý của tính năng tự động hoàn thành. Ví dụ: "Alocations Anatole France, Paris, France" và "Sydney, New South Wales".
• getPlaceId() sẽ trả về mã địa điểm của địa điểm được dự đoán. Mã địa điểm là dạng văn bản giá trị nhận dạng xác định duy nhất một địa điểm mà bạn có thể sử dụng để truy xuất thời gian Place đối tượng một lần nữa sau đó. Để 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 Địa điểm Thông tin chi tiết. Dành cho tất cả mọi người thông tin về mã địa điểm, hãy xem Mã địa điểm tổng quan.
• 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 gốc được chỉ định trong yêu cầu.

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

Bạn có thể sử dụng CancellationToken để cố huỷ một yêu cầu tới bất kỳ lớp yêu cầu nào (ví dụ: FetchPlaceRequest). Quá trình huỷ được thực hiện nỗ lực hết sức có thể. Sau khi đưa ra yêu cầu huỷ, sẽ không có phản hồi nào được trả về. Việc cấp mã thông báo 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 phản hồi được trả về.

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 trong quá trình tự động hoàn thành của người dùng tìm kiếm vào 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. Mỗi phiên có thể có nhiều truy vấn, theo sau là một lựa chọn địa điểm. Khi một phiên hoạt động có kết thúc, mã thông báo 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 từng phiên hoạt động. Bạn nên sử dụng mã thông báo phiên cho tất cả quảng cáo có lập trình phiên tự động hoàn thà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 ý định thì 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 sẽ truyền mã thông báo phiên mới khi bắt đầu mỗi phiên mới, sau đó chuyển cùng mã thông báo đó cùng với ID địa điểm vào 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 đã được người dùng chọn.

Lưu ý: Nếu ứng dụng của bạn đang dùng tính năng Tự động hoàn thành tiện ích, bạn không cần triển khai phiên, vì tiện ích này xử lý các phiên tự động chạy trong nền.

Tìm hiểu thêm về phiên mã thông báo.

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

Bạn có thể ràng buộc kết quả tự động hoàn thành trong 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 tối đa năm quốc gia. Bạn có thể áp dụng các điều kiện 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() (có thể một số kết quả từ bên ngoài vùng đã xác định 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ỉ những kết quả trong khu vực xác định mới được bị trả lại).
• Để chỉ trả về kết quả phù hợp với một loại địa điểm cụ thể, gọi setTypesFilter() (ví dụ: chỉ định TypeFilter.ADDRESS sẽ trả về chỉ những kết quả có địa chỉ chính xác).
• Để chỉ trả lại kết quả trong tối đa năm quốc gia được chỉ định, gọi setCountries(). Quốc gia phải được thông qua dưới dạng hai ký tự, ISO 3166-1 Quốc gia tương thích với Alpha-2 .

Kết quả sai lệch đến một khu vực cụ thể

Để dịch chuyển kết quả tự động hoàn thành sang 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 mảnh để thiên vị các đề xuất tự động hoàn thành sang một vùng 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)));

      

Giới hạn 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 thực thể mảnh để thiên lệch các đề xuất tự động hoàn thành cho một vùng 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ộ 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 giới hạn vị trí.

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

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

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

Để chỉ định một loại hoặc bộ lọc bộ sưu tập kiểu:

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

• Gọi setTypesFilter() và chỉ định một bộ sưu tập kiểu trong Bảng 3 như trình bày dưới đây trên Loại địa điểm. Giá trị của tập hợp được xác định bởi hằng số trong PlaceTypes (Loại địa điểm).

  Chỉ cho phép một loại duy nhất từ Bảng 3 trong yêu cầu. Nếu bạn chỉ định một 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ẽ có lỗi xảy ra.

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

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 một 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 một 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 kiểu.

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 đó, chuyển bộ lọc vào một mảnh hoặc ý định. Quốc gia phải được thông qua dưới dạng hai ký tự, tương thích với quốc gia theo ISO 3166-1 Alpha-2 .

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

Kotlin

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

      

Java

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

      

Hạn mức sử dụng

Bạn sử dụng Places API, bao gồm cả Places SDK 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 vẫn áp dụng:

• Giới hạn số lần yêu cầu là 6.000 QPM (yêu cầu mỗi phút). Đó là được tính bằng tổng của các yêu cầu phía máy khách và phía máy chủ cho tất cả các yêu cầu bằng cách sử dụng thông tin đăng nhập của cùng một dự án.

Hiển thị thuộc tính trong ứng dụng của bạn

• Nếu ứng dụng của bạn sử dụng dịch vụ tự động hoàn thành theo phương thức lập trình, thì giao diện người dùng phải hoặc hiển thị biểu tượ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 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 bạn truy xuất và hiển thị thông tin địa điểm bổ sung sau khi nhận được địa điểm theo , bạn cũng phải hiển thị thông tin ghi nhận sự đóng góp 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 địa điểm

Phần này mô tả các phương pháp hay nhất để giúp bạn khai thác tối đa Dịch vụ Tự động hoàn thành địa điểm.

Dưới đây là một số nguyên tắc chung:

• Cách nhanh nhất để phát triển một giao diện người dùng hoạt động tốt là sử dụng Tiện ích Tự động hoàn thành của API Maps JavaScript, 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 iOS Kiểm soát giao diện người dùng tự động hoàn thành
• Hiểu rõ về tính năng Tự động hoàn thành địa điểm thiết yếu trường dữ liệu 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 tự động hoàn thành.
• Sử dụng tính năng xử lý lỗi để đảm bảo ứng dụng của bạn xuống cấp nhẹ 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í khi sử dụng tính năng Tự động hoàn thành về địa điểm hãy sử dụng mặt nạ trường trong các tiện ích Chi tiết địa điểm và Tự động hoàn thành về địa điểm để chỉ trả về trường dữ liệu địa điểm mà bạn cần.

Tối ưu hoá chi phí nâng cao

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 chế độ Giá theo mỗi yêu cầu và yêu cầu kết quả bằng API mã hoá địa lý về địa điểm đã chọn thay vì Thông tin chi tiết về địa điểm. Đặt giá Mỗi yêu cầu được kết hợp với API mã hoá địa lý sẽ tiết kiệm chi phí hơn so với đặt giá Mỗi phiên (dựa trên phiên) nếu đáp ứng cả hai điều kiện sau:

• Nếu bạn chỉ cần vĩ độ/kinh độ hoặc địa chỉ của địa điểm mà người dùng đã chọn, thì API mã hoá địa lý sẽ cung cấp thông tin này trong ít hơn một lệnh gọi Chi tiết địa điểm.
• Nếu người dùng chọn một cụm từ gợi ý tự động hoàn thành trong số trung bình 4 yêu cầu dự đoán Tự động hoàn thành trở xuống, thì phương thức đặt giá Theo yêu cầu có thể tiết kiệm chi phí hơn so với phương thức đặt giá Theo phiên.

Để được trợ giúp trong việc chọn cách triển khai tính năng Tự động hoàn thành đị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 cụm từ gợi ý đã 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 cùng với Thông tin chi tiết về địa điểm.
Vì ứng dụng của bạn yêu cầu Thông tin chi tiết về địa điểm, chẳng hạn như tên địa điểm, trạng thái doanh nghiệp hoặc giờ mở cửa, nên việc triển khai tính năng Tự động hoàn thành địa điểm sẽ sử dụng mã thông báo phiên (theo phương thức lập trình hoặc tích hợp vào tiện ích JavaScript, Android hoặc iOS) với tổng chi phí là 0, 017 USD cho mỗi phiên cộng với SKU dữ liệu địa điểm có thể áp dụng tuỳ thuộc vào các trường dữ liệu địa điểm mà bạn yêu cầu.^{/15

Triển khai tiện ích
Tính năng quản lý phiên được tự động tích hợp vào 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à thông tin chi tiết về địa điểm trên cụm từ gợi ý đã chọn. Hãy nhớ chỉ định tham số fields để đảm bảo rằng bạn chỉ yêu cầu trường dữ liệu địa điểm mà bạn cần.

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

1. Mã địa điểm trong phản hồi Tự động hoàn thành về đị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 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 Chi tiết địa điểm cho ứng dụng của bạn, tuỳ thuộc vào hiệu suất của việc sử dụng tính năng Tự động hoàn thành địa điểm. 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 người dùng đang nhập, nơi ứng dụng đang được dùng và việc các phương pháp hay nhất để tối ưu hoá hiệu suất có được triển khai hay không.

Để trả lời câu hỏi sau, hãy phân tích số lượng ký tự trung bình người dùng nhập vào trước khi chọn 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ó chọn một cụm từ gợi ý của tính năng Tự động hoàn thành về địa điểm trong tối đa 4 yêu cầu không?

Có

Triển khai tính năng Tự động hoàn thành địa điểm theo phương thức lập trình mà không cần mã thông báo phiên và gọi API mã hoá địa lý trên thông tin dự đoán về địa điểm đã chọn.
API mã hoá địa lý cung cấp các địa chỉ và vĩ độ/kinh độ của địa chỉ $0,005 cho mỗi yêu cầu. Việc tạo 4 yêu cầu Tự động hoàn thành theo địa điểm – Theo yêu cầu có chi phí là 0,01132 USD, 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 được chọn sẽ là 0,01632 USD, thấp hơn giá Tự động hoàn thành mỗi phiên là 0,017 USD/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 gợi ý mà họ đang tìm với í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 cùng với Thông tin chi tiết về địa điểm.
Vì số lượng yêu cầu trung bình mà bạn dự kiến sẽ thực hiện trước khi người dùng chọn thông tin dự đoán của tính năng Tự động hoàn thành về địa điểm vượt quá chi phí để tí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 phải dùng một mã thông báo phiên cho cả yêu cầu Tự động hoàn thành về địa điểm và yêu cầu Thông tin chi tiết về địa điểm được liên kết, với tổng chi phí là 0,017 USD 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 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à thông tin chi tiết về địa điểm trên 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 phiên với các yêu cầu Tự động hoàn thành địa điểm. Khi yêu cầu Thông tin chi tiết về địa điểm về cụm từ gợi ý đã chọn, hãy bao gồm các thông số sau:

1. Mã địa điểm trong phản hồi Tự động hoàn thành về đị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 trì hoãn các yêu cầu Tự động hoàn thành địa điểm
Bạn có thể sử dụng các chiến lược như trì hoãn yêu cầu Tự động hoàn thành địa điểm cho đến khi người dùng nhập 3 hoặc 4 ký tự đầu tiên để ứng dụng của bạn đưa ra ít yêu cầu hơn. Ví dụ: thực hiện yêu cầu Tự động hoàn thành địa điểm cho mỗi ký tự sau khi người dùng đã nhập ký tự thứ ba có nghĩa là nếu người dùng nhập 7 ký tự sau đó chọn gợi ý mà bạn thực hiện một yêu cầu API mã hóa địa lý, tổng chi phí sẽ là $0,01632 (4 * $0,00283 Tự động hoàn thành mỗi yêu cầu + $0,005 Mã hóa địa lý).¹

Nếu việc trì hoãn 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 bằng cách sử dụng API mã hoá địa lý. Lưu ý rằng việc trì hoãn yêu cầu có thể được xem là độ trễ của người dùng vì họ có thể thấy cụm từ gợi ý mỗi khi nhấn phím mới.

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 gợi ý mà họ đang tìm kiếm với ít ký tự hơn.

---

1. Các chi phí được liệt kê ở đây được tính bằng đô la Mỹ. Vui lòng tham khảo trang Thanh toán trên Nền tảng Google Maps để biết thông tin đầy đủ về giá.

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

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 về địa điểm:

• Thêm hạn chế theo quốc gia, thiên vị vị trí, và lựa chọn ngôn ngữ ưu tiên (đối với việc triển khai có lập trình) cho tính năng Tự động hoàn thành địa điểm trong quá trình triển khai. Không cần lựa chọn ưu tiên ngôn ngữ với các tiện ích vì chúng chọn tuỳ chọn ngôn ngữ từ trình duyệt hoặc thiết bị di động của người dùng.
• Nếu tính năng Tự động hoàn thành địa điểm đi kèm với một bản đồ, thì bạn có thể dịch chuyển vị trí theo chế độ xem 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, bởi vì không có dự đoán nào trong số đó là địa chỉ kết quả mong muốn, nên bạn có thể sử dụng lại hoạt động đầu vào của người dùng để cố gắng nhận được kết quả có liên quan 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 truy vấn về 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ỉ dự kiến có ở một khu vực cụ thể, hãy sử dụng xu hướng vị trí.
  Các trường hợp khác trong đó bạn nên quay lại sử dụng API mã hoá địa lý bao gồm:
  • Người dùng nhập địa chỉ con ở những quốc gia có hỗ trợ tính năng Tự động hoàn thành bằng địa điểm địa chỉ phụ không hoàn chỉnh, ví dụ: Cộng hoà Séc, Estonia và Lithuania. Ví dụ: Địa chỉ bằng tiếng Séc "Stroupe Sửanického 3191/17, Praha" đưa ra dự đoán một phần tại vị trí Tự động hoàn thành.
  • Người dùng nhập địa chỉ có tiền tố đoạn đường như "23-30 29th St, Queens" inch New York City hoặc "47-380 Kamehameha Hwy, Kaneohe" trên đảo Kauai ở Hawaii.

Khắc phục sự cố

Mặc dù có nhiều lỗi có thể xảy ra, nhưng phần lớn lỗi mà ứng dụng của bạn mắc phải nhiều khả năng 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 chính xác) hoặc hạn mức lỗi (ứng dụng của bạn đã vượt quá hạn mức). Xem phần Cách sử dụng Giới hạn cho các lựa chọn khác thông tin về hạn mức.

Lỗi xảy ra khi sử dụng các tùy chọn điều khiển tự động hoàn thành được trả về trong Lệnh gọi lại onActivityResult(). Gọi Autocomplete.getStatus() để biết trạng thái thông báo về kết quả.