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ề gợi ý địa điểm để phản hồi truy vấn tìm kiếm của người dùng. Khi loại người dùng, dịch vụ tự động hoàn thành sẽ trả về các mục đề xuất cho những đị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 theo các cách sau:

Thêm tiện ích tự động hoàn thành

Tiện ích tự động hoàn thành là một hộp thoại tìm kiếm có chức năng tự động hoàn thành tích hợp sẵn. Khi người dùng nhập cụm từ tìm kiếm, tiện ích sẽ hiển thị danh sách các địa điểm được dự đoán để bạn chọn. Khi người dùng chọn, một thực thể Place sẽ được trả về mà ứng dụng của bạn có thể sử dụng để nhận thông tin chi tiết về địa điểm đã chọn.

Có hai cách để thêm tiện ích tự động hoàn thành vào ứng dụng:

Tuỳ chọn 1: Nhúng AutofillSupportFragment

Để thêm AutocompleteSupportFragment vào ứng dụng, hãy thực hiện 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 AutofillSupportFragment vào một hoạt động

Để thêm AutocompleteSupportFragment vào một hoạt động, hãy thêm một mảnh mới vào bố cục XML. Ví dụ:

<fragment android:id="@+id/autocomplete_fragment"
  android:layout_width="match_parent"
  android:layout_height="wrap_content"
  android:name="com.google.android.libraries.places.widget.AutocompleteSupportFragment"
  />
  • Theo mặc định, mảnh không có đường viền hoặc nền. Để đảm bảo hình ảnh nhất quán, hãy lồng mảnh trong một phần tử bố cục khác, chẳng hạn như CardView.
  • Nếu 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, mảnh sẽ không hoạt động đúng cách.

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

PlaceSelectionListener xử lý việc trả về một địa điểm để phản hồi lựa chọn của người dùng. Đoạn mã sau đây cho thấy cách tạo tệp tham chiếu đến mảnh và thêm trình nghe vào AutocompleteSupportFragment:

Java


    // Initialize the AutocompleteSupportFragment.
    AutocompleteSupportFragment autocompleteFragment = (AutocompleteSupportFragment)
        getSupportFragmentManager().findFragmentById(R.id.autocomplete_fragment);

    // Specify the types of place data to return.
    autocompleteFragment.setPlaceFields(Arrays.asList(Place.Field.ID, Place.Field.NAME));

    // Set up a PlaceSelectionListener to handle the response.
    autocompleteFragment.setOnPlaceSelectedListener(new PlaceSelectionListener() {
        @Override
        public void onPlaceSelected(@NonNull Place place) {
            // TODO: Get info about the selected place.
            Log.i(TAG, "Place: " + place.getName() + ", " + place.getId());
        }


        @Override
        public void onError(@NonNull Status status) {
            // TODO: Handle the error.
            Log.i(TAG, "An error occurred: " + status);
        }
    });

      

Kotlin


    // Initialize the AutocompleteSupportFragment.
    val autocompleteFragment =
        supportFragmentManager.findFragmentById(R.id.autocomplete_fragment)
            as AutocompleteSupportFragment

    // Specify the types of place data to return.
    autocompleteFragment.setPlaceFields(listOf(Place.Field.ID, Place.Field.NAME))

    // Set up a PlaceSelectionListener to handle the response.
    autocompleteFragment.setOnPlaceSelectedListener(object : PlaceSelectionListener {
        override fun onPlaceSelected(place: Place) {
            // TODO: Get info about the selected place.
            Log.i(TAG, "Place: ${place.name}, ${place.id}")
        }

        override fun onError(status: Status) {
            // TODO: Handle the error.
            Log.i(TAG, "An error occurred: $status")
        }
    })

      

Tùy chọn 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 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.

Để 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, chuyển chế độ Autocomplete mong muốn. Ý định phải gọi startActivityForResult, truyền vào một mã yêu cầu xác định ý định.
  2. Ghi đè lệnh gọi lại onActivityResult để nhận địa điểm đã chọn.

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

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

Java


    private static int AUTOCOMPLETE_REQUEST_CODE = 1;

    // Set the fields to specify which types of place data to
    // return after the user has made a selection.
    List<Place.Field> fields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

    // Start the autocomplete intent.
    Intent intent = new Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .build(this);
    startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE);

      

Kotlin


    private val AUTOCOMPLETE_REQUEST_CODE = 1

    // Set the fields to specify which types of place data to
    // return after the user has made a selection.
    val fields = listOf(Place.Field.ID, Place.Field.NAME)

    // Start the autocomplete intent.
    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .build(this)
    startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE)

      

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

Khi được hiển thị ở chế độ lớp phủ, tiện ích tự động hoàn thành sẽ xuất hiện xếp chồng lên giao diện người dùng đang gọi.
Hình 1: Tiện ích tự động hoàn thành ở chế độ TRÙNG LẶP
Khi được hiển thị ở chế độ toàn màn hình, tiện ích tự động hoàn thành sẽ lấp đầy toàn bộ màn hình.
Hình 2: Tiện ích tự động hoàn thành ở chế độ HOÀN CHỈNH

Ghi đè lệnh gọi lại onActivityResult

Để nhận thông báo khi người dùng đã chọn một địa điểm, ứng dụng của bạn sẽ ghi đè onActivityResult() của hoạt động, kiểm tra mã yêu cầu mà bạn đã truyền cho ý định của mình, như trong ví dụ sau.

Java


@Override
protected void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) {
    if (requestCode == AUTOCOMPLETE_REQUEST_CODE) {
        if (resultCode == RESULT_OK) {
            Place place = Autocomplete.getPlaceFromIntent(data);
            Log.i(TAG, "Place: " + place.getName() + ", " + place.getId());
        } else if (resultCode == AutocompleteActivity.RESULT_ERROR) {
            // TODO: Handle the error.
            Status status = Autocomplete.getStatusFromIntent(data);
            Log.i(TAG, status.getStatusMessage());
        } else if (resultCode == RESULT_CANCELED) {
            // The user canceled the operation.
        }
        return;
    }
    super.onActivityResult(requestCode, resultCode, data);
}

      

Kotlin


override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    if (requestCode == AUTOCOMPLETE_REQUEST_CODE) {
        when (resultCode) {
            Activity.RESULT_OK -> {
                data?.let {
                    val place = Autocomplete.getPlaceFromIntent(data)
                    Log.i(TAG, "Place: ${place.name}, ${place.id}")
                }
            }
            AutocompleteActivity.RESULT_ERROR -> {
                // TODO: Handle the error.
                data?.let {
                    val status = Autocomplete.getStatusFromIntent(data)
                    Log.i(TAG, status.statusMessage ?: "")
                }
            }
            Activity.RESULT_CANCELED -> {
                // The user canceled the operation.
            }
        }
        return
    }
    super.onActivityResult(requestCode, resultCode, data)
}

      

Lấy thông tin dự đoán địa điểm theo phương thức lập trình

Bạn có thể tạo một giao diện người dùng tìm kiếm tuỳ chỉnh để thay thế cho giao diện người dùng do tiện ích tự động hoàn thành cung cấp. Để làm đượ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ó thể lấy danh sách tên và/hoặc địa chỉ 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à chọn lọc 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 hoạt động bắt đầu khi người dùng bắt đầu nhập một truy vấn và kết thúc khi họ chọn một địa điểm.
  • Nên dùng: Đối tượng RectangularBounds chỉ định giới hạn vĩ độ và kinh độ để giới hạn kết quả tại khu vực đã chỉ định.
  • Không bắt buộc: Một hoặc nhiều mã quốc gia gồm hai chữ cái (ISO 3166-1 Alpha-2), cho biết quốc gia hoặc các quốc gia bị hạn chế kết quả.
  • Không bắt buộc: Một TypeFilter mà bạn có thể dùng để hạn chế kết quả theo loại địa điểm được chỉ định. Các loại địa điểm sau được hỗ trợ:

    • TypeFilter.GEOCODE – Chỉ trả về kết quả mã hóa địa lý, không phải các doanh nghiệp. Sử dụng yêu cầu này để phân biệt kết quả mà vị trí được chỉ định có thể không xác định.
    • TypeFilter.ADDRESS – Chỉ trả về kết quả tự động hoàn thành có địa chỉ chính xác. Hãy 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ề kết quả khớp với LOCALITY hoặc ADMINISTRATIVE_AREA_LEVEL_3.

  • Không bắt buộc: LatLng xác định vị trí 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ừ nguồn gốc đã chỉ định, cho mỗi cụm từ gợi ý tự động hoàn thành trong phản hồi.

Để biết thông tin về các loại địa điểm, hãy xem hướng dẫn về các loại địa điểm.

Ví dụ bên dưới cho thấy lệnh gọi đầy đủ đến PlacesClient.findAutocompletePredictions().

Java


    // Create a new token for the autocomplete session. Pass this to FindAutocompletePredictionsRequest,
    // and once again when the user makes a selection (for example when calling fetchPlace()).
    AutocompleteSessionToken token = AutocompleteSessionToken.newInstance();

    // Create a RectangularBounds object.
    RectangularBounds bounds = RectangularBounds.newInstance(
        new LatLng(-33.880490, 151.184363),
        new LatLng(-33.858754, 151.229596));
    // Use the builder to create a FindAutocompletePredictionsRequest.
    FindAutocompletePredictionsRequest request = FindAutocompletePredictionsRequest.builder()
        // Call either setLocationBias() OR setLocationRestriction().
        .setLocationBias(bounds)
        //.setLocationRestriction(bounds)
        .setOrigin(new LatLng(-33.8749937,151.2041382))
        .setCountries("AU", "NZ")
        .setTypesFilter(Arrays.asList(TypeFilter.ADDRESS.toString()))
        .setSessionToken(token)
        .setQuery(query)
        .build();

    placesClient.findAutocompletePredictions(request).addOnSuccessListener((response) -> {
        for (AutocompletePrediction prediction : response.getAutocompletePredictions()) {
            Log.i(TAG, prediction.getPlaceId());
            Log.i(TAG, prediction.getPrimaryText(null).toString());
        }
    }).addOnFailureListener((exception) -> {
        if (exception instanceof ApiException) {
            ApiException apiException = (ApiException) exception;
            Log.e(TAG, "Place not found: " + apiException.getStatusCode());
        }
    });

      

Kotlin


    // Create a new token for the autocomplete session. Pass this to FindAutocompletePredictionsRequest,
    // and once again when the user makes a selection (for example when calling fetchPlace()).
    val token = AutocompleteSessionToken.newInstance()

    // Create a RectangularBounds object.
    val bounds = RectangularBounds.newInstance(
        LatLng(-33.880490, 151.184363),
        LatLng(-33.858754, 151.229596)
    )
    // Use the builder to create a FindAutocompletePredictionsRequest.
    val request =
        FindAutocompletePredictionsRequest.builder()
            // Call either setLocationBias() OR setLocationRestriction().
            .setLocationBias(bounds)
            //.setLocationRestriction(bounds)
            .setOrigin(LatLng(-33.8749937, 151.2041382))
            .setCountries("AU", "NZ")
            .setTypesFilter(listOf(TypeFilter.ADDRESS.toString()))
            .setSessionToken(token)
            .setQuery(query)
            .build()
    placesClient.findAutocompletePredictions(request)
        .addOnSuccessListener { response: FindAutocompletePredictionsResponse ->
            for (prediction in response.autocompletePredictions) {
                Log.i(TAG, prediction.placeId)
                Log.i(TAG, prediction.getPrimaryText(null).toString())
            }
        }.addOnFailureListener { exception: Exception? ->
            if (exception is ApiException) {
                Log.e(TAG, "Place not found: " + exception.statusCode)
            }
        }

      

API trả về một FindAutocompletePredictionsResponse trong một 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 đã biết tương ứng với cụm từ tìm kiếm và tiêu chí lọc.

Đối với mỗi địa điểm được dự đoán, bạn có thể gọi các phương thức sau để truy xuất thông tin chi tiết về địa điểm:

  • getFullText(CharacterStyle) trả về toàn bộ nội dung của thông tin mô tả địa điểm. Đây là sự kết hợp giữa văn bản chính và văn bản phụ. Ví dụ: "Eiffel Tower, Avenue Anatole France, Paris, France". Ngoài ra, phương thức này cho phép bạn làm nổi bật các phần của nội dung mô tả khớp với cụm từ tìm kiếm có kiểu mà bạn chọn, bằng cách sử dụng CharacterStyle. Tham số CharacterStyle là không bắt buộc. Hãy đặt giá trị này thành rỗng nếu bạn không cần bất kỳ đặc điểm nổi bật nào.
  • getPrimaryText(CharacterStyle) trả về văn bản chính mô tả một địa điểm. Đây thường là tên của địa điểm. Ví dụ: "Eiffel Tower" và "123 Disneyland Street".
  • getSecondaryText(CharacterStyle) trả về văn bản con của nội dung mô tả về địa điểm. Ví dụ: hữu ích như một dòng thứ hai khi hiển thị tự động hoàn thành cụm từ gợi ý. Ví dụ: "A Hội nghị Anatole Pháp, 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 dạng văn bản giúp xác định riêng một địa điểm. Bạn có thể sử dụng thông tin 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 Chi tiết địa điểm. Để biết thông tin chung về mã địa điểm, hãy xem bài viết Tổng quan về mã địa điểm.
  • getPlaceTypes() trả về danh sách các loại địa điểm liên kết với địa điểm này.
  • getDistanceMeters() trả về khoảng cách đường thẳng tính bằng mét giữa địa điểm này và nguồn gốc đã chỉ định trong yêu cầu.

Mã thông báo phiên

Mã thông báo phiên sẽ nhóm các giai đoạn truy vấn và chọn của 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 hoạt động bắt đầu khi người dùng bắt đầu nhập một truy vấn và kết thúc khi họ chọn một địa điểm. Mỗi phiên có thể có nhiều truy vấn, theo sau là một nơi chọn. 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 hoạt động. Bạn nên sử dụng mã thông báo phiên cho mọi phiên tự động hoàn thành có lập trình (khi bạn nhúng một mảnh hoặc chạy tính năng tự động hoàn thành bằng cách sử dụng một ý định, API sẽ tự động xử lý vấn đề này).

SDK Địa điểm dành cho Android sử dụng AutocompleteSessionToken để xác định từng phiên. Ứng dụng của bạn phải chuyể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ã đị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 của phiên hoạt động.

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

Bạn có thể ràng buộc kết quả tự động hoàn thành với một khu vực địa lý cụ thể và/hoặc lọc kết quả cho một hoặc nhiều loại địa điểm hoặc cho tối đa năm 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 vùng đã xác định, hãy gọi setLocationBias() (một số kết quả ở bên ngoài vùng đã xác định có thể vẫn được trả về).
  • Để chỉ hiển thị kết quả trong khu vực đã xác định, hãy gọi setLocationRestriction() (chỉ trả về kết quả trong khu vực đã xác định).
  • Để chỉ trả về kết quả phù hợp với một loại địa điểm cụ thể, hãy gọi setTypesFilter() (ví dụ: chỉ đị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 phạm vi tối đa năm quốc gia được chỉ định, hãy gọi setCountries(). Quốc gia phải được chuyển dưới dạng mã quốc gia tương thích với ISO 3166-1 Alpha-2.

Xu hướng dẫn đến một khu vực cụ thể

Để tự động hoàn thành kết quả tìm kiếm cho 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 việc gọi setLocationBias() trên thực thể mảnh để thiên về đề xuất tự động hoàn thành tới một khu vực của Sydney, Úc.

Java


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

      

Kotlin


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

      

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

Để hạn chế 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. Ví dụ về mã sau đây cho thấy việc gọi setLocationRestriction() trên thực thể của mảnh để áp dụng đề xuất tự động hoàn thành cho một khu vực của Sydney, Úc.

Java


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

      

Kotlin


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

      

Lưu ý: Quy định hạn chế này chỉ áp dụng cho toàn bộ tuyến đường, do đó, các kết quả tổng hợp nằm ngoài ranh giới hình chữ nhật có thể được trả về dựa trên tuyến đường bị ghi đè do giới hạn 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 để các kết quả đó 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 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ó giá trị nào được chỉ định, tất cả các loại sẽ được trả về.

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

Để chỉ định một 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ị loại từ Bảng 1 và Bảng 2 hiển thị trên Loại địa điểm. Giá trị loại được xác định theo các hằng số trong PlaceTypes.

  • Gọi setTypesFilter() và chỉ định tập hợp kiểu từ Bảng 3 được 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ởi các hằng số trong PlaceTypes.

    Chỉ cho phép một loại từ 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.

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

Java


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

      

Kotlin


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

      

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

Java


    autocompleteFragment.setTypesFilter(Arrays.asList(TypeFilter.ADDRESS.toString()));

      

Kotlin


    autocompleteFragment.setTypesFilter(listOf(TypeFilter.ADDRESS.toString()))

      

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

Java


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

      

Kotlin


    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .setTypesFilter(listOf(TypeFilter.ADDRESS.toString()))
        .build(this)
    startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE)

      

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

Để lọc kết quả tự động hoàn thành tối đa 5 quốc gia, hãy gọi setCountries() để đặt mã quốc gia. Sau đó, hãy chuyển bộ lọc này sang một mảnh (fragment) hoặc ý định (intent). Quốc gia phải được chuyển dưới dạng mã quốc gia tương thích với ISO 3166-1 Alpha-2.

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

Java


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

      

Kotlin


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

      

Hạn mức sử dụng

Việc bạn sử dụng API Địa điểm, bao gồm cả SDK Địa điểm dành cho Android, không còn giới hạn ở số lượng yêu cầu tối đa mỗi ngày (QPD). Tuy nhiên, các hạn mức sử dụng sau vẫn được áp dụng:

  • Giới hạn tốc độ là 100 yêu cầu mỗi giây (QPS). 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 đăng nhập của cùng một dự án.

Hiển thị mô hình phân bổ trong ứng dụng của bạn

  • Nếu ứng dụng của bạn sử dụng dịch vụ tự động hoàn thành theo cách lập trình, giao diện người dùng phải hiển thị thuộc tính "Do Google cung cấp" hoặc xuất hiện trong bản đồ mang thương hiệu Google.
  • Nếu ứng dụng của bạn sử dụng tiện ích tự động hoàn thành, thì bạn không cần làm thêm việc gì (thuộc tính bắt buộc được 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 nhận được địa điểm theo mã nhận dạng, 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 chi tiết, hãy xem tài liệu về mô hình phân bổ.

Tối ưu hoá tính năng Tự động hoàn thành địa điểm

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

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

  • Cách nhanh nhất để phát triển một giao diện người dùng đang hoạt động là sử dụng tiện ích tự động hoàn thành API JavaScript cho Maps, SDK địa điểm dành cho Android tiện ích tự động hoàn thành hoặc SDK địa điểm dành cho quyền kiểm soát giao diện người dùng tự động hoàn thành trên iOS
  • Hiểu rõ về các trường dữ liệu Tự động hoàn thành địa điểm cần thiết ngay từ đầu.
  • Xu hướng vị trí và các trường 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.
  • Hãy sử dụng cách xử lý lỗi để đảm bảo ứng dụng của bạn xuống cấp nhẹ nếu API trả về một lỗi.
  • Hãy đảm bảo rằng ứng dụng của bạn xử lý khi không có lựa chọn nào và hướng dẫn người dùng cách tiếp tục.

Các phương pháp hay nhất về việc tối ưu hóa chi phí

Tối ưu hóa chi phí cơ bản

Để tối ưu hóa chi phí sử dụng dịch vụ Tự động hoàn thành địa điểm, hãy sử dụng mặt nạ trường trong phần Thông tin chi tiết về địa điểm và tiện ích Tự động hoàn thành địa điểm để chỉ trả về các trường dữ liệu địa điểm bạn cần.

Tối ưu hóa 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 Giá theo yêu cầu và yêu cầu kết quả API mã hóa địa lý về địa điểm đã chọn thay vì Thông tin chi tiết về địa điểm. Giá của mỗi Yêu cầu ghép nối với API mã hoá địa lý hiệu quả hơn về chi phí so với giá của 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, API mã hóa địa lý sẽ cung cấp thông tin này cho một lệnh gọi Chi tiết địa điểm ít hơn.
  • Nếu người dùng chọn một cụm từ gợi ý của tính năng tự động hoàn thành trong vòng trung bình 4 yêu cầu tự động hoàn thành hoặc ít hơn, thì giá của mỗi Yêu cầu có thể tiết kiệm chi phí hơn giá của mỗi phiên hoạt động.
Để được trợ giúp chọn phương thức 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 ý bạn đã chọn không?

Có, cần thêm thông tin chi tiết

Sử dụng tính năng Tự động hoàn thành dựa trên phiên hoạt động với thông tin chi tiết về địa điểm.
Vì ứng dụng của bạn yêu cầu thông tin về Địa điểm, chẳng hạn như tên địa điểm, trạng thái doanh nghiệp hoặc giờ mở cửa, nên việc triển khai tính năng Tự động hoàn thành địa điểm phải sử dụng mã thông báo phiên (theo chương trình hoặc tích hợp vào tiện ích JavaScript, Android hoặc iOS) với tổng chi phí $0,017 cho mỗi phiên cộng với SKU dữ liệu địa điểm tùy theo trường 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. Số liệu này bao gồm cả yêu cầu Tự động hoàn thành địa điểm và yêu cầu Thông tin chi tiết về địa điểm trên thông tin dự đoán đã chọn. Hãy nhớ chỉ định thông số fields để đảm bảo bạn chỉ yêu cầu các 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 Đặt chi tiết về gợi ý đã chọn, hãy thêm các thông số sau:

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

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

API mã hóa địa lý có thể là một tùy chọn có hiệu quả về chi phí hơn so với Thông tin chi tiết về địa điểm cho ứng dụng của bạn, tùy 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 vào, vị trí ứng dụng được sử dụng và liệu các phương pháp hay nhất để tối ưu hoá hiệu suất có được triển khai hay không.

Để trả lời câu hỏi sau, hãy phân tích số lượng ký tự trung bình mà một người dùng nhập trước khi chọn cụm từ gợi ý của tính năng Tự động hoàn thành địa điểm trong ứng dụng của bạn.

Người dùng của bạn có chọn trung bình 4 hoặc nhiều yêu cầu hơn cho cụm từ gợi ý của tính năng Tự động hoàn thành địa điểm không?

Triển khai tính năng Tự động hoàn thành địa điểm theo phương thức lập trình mà không cần mã thông báo phiên và gọi API mã hoá địa lý trên thông tin dự đoán địa điểm đã chọn.
API mã hóa địa lý cung cấp địa chỉ và tọa độ có vĩ độ/kinh độ $0,005 cho mỗi yêu cầu. Việc tạo 4 yêu cầu Tự động hoàn thành địa điểm – Mỗi yêu cầu có chi phí là 0,01132 đô la. Do đó, tổng chi phí của 4 yêu cầu cộng với một lệnh gọi API mã hóa địa lý về giá thầu dự kiến cho địa điểm đã chọn sẽ là 0,01632 đô la, thấp hơn giá của tính năng Tự động hoàn thành mỗi phiên là 0,017 đô la cho mỗi phiên.1

Hãy xem xét 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 dự đoán được ít ký tự hơn.

Không

Sử dụng tính năng Tự động hoàn thành dựa trên phiên hoạt động với thông tin chi tiết về địa điểm.
Vì số lượng yêu cầu trung bình mà bạn dự kiến thực hiện trước khi người dùng chọn một cụm từ gợi ý của tính năng Tự động hoàn thành địa điểm vượt quá chi phí định giá cho mỗi phiên hoạt động, nên việc triển khai tính năng Tự động hoàn thành địa điểm 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 và yêu cầu Thông tin chi tiết về địa điểm có liên quan cho tổng chi phí là 0,017 USD cho mỗi phiên.1

Triển khai tiện ích
Tính năng quản lý phiên được tự động tích hợp vào các tiện ích JavaScript, Android hoặc iOS. Số liệu này bao gồm cả yêu cầu Tự động hoàn thành địa điểm và yêu cầu Thông tin chi tiết về địa điểm trên thông tin dự đoán đã chọn. Hãy nhớ chỉ định thông 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 Đặt chi tiết về gợi ý đã chọn, hãy thêm các thông số sau:

  1. Mã địa điểm trong phản hồi Tự động hoàn thành địa điểm
  2. Mã thông báo phiên được sử dụng trong yêu cầu Tự động hoàn thành địa điểm
  3. Thông số fields chỉ định các trường Dữ liệu cơ bản, chẳng hạn như địa chỉ và hình học

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

Nếu các yêu cầu bị trễ có thể nhận được yêu cầu có lập trình trung bình dưới 4, thì bạn có thể làm theo hướng dẫn để triển khai tính năng Tự động hoàn thành về địa điểm bằng API mã hóa địa lý. Xin lưu ý rằng những yêu cầu có độ trễ có thể được coi là độ trễ khi người dùng có thể muốn xem dự đoán về mọi lần nhấn phím mới.

Hãy xem xét 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 dự đoán được ít ký tự hơn.


  1. Chi phí nêu ở đây được tính theo đô la Mỹ. Vui lòng tham khảo trang Thanh toán của 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ác 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 tắc hạn chế theo quốc gia, xu hướng vị trí và (tùy chọn triển khai theo phương thức lập trình) vào phương thức triển khai tính năng Tự động hoàn thành địa điểm. Tùy chọn ngôn ngữ không cần thiết với các tiện ích vì chúng chọn các tùy chọn ngôn ngữ từ trình duyệt hoặc thiết bị di động của người dùng.
  • Nếu tính năng Tự động hoàn thành địa điểm đi kèm với một bản đồ, bạn có thể thiên về vị trí theo khung nhìn bản đồ.
  • Trong trường hợp người dùng không chọn một trong các cụm từ gợi ý của tính năng Tự động hoàn thành, thường thì do không có gợi ý nào trong số đó là địa chỉ kết quả mong muốn, nên bạn có thể sử dụng lại thông tin đầu vào ban đầu của người dùng để cố gắng nhận được kết quả phù hợp hơn:
    • Nếu bạn muốn người dùng chỉ nhập thông tin địa chỉ, hãy sử dụng lại dữ liệu đầu vào của người dùng ban đầu trong lệnh gọi API mã hóa địa lý.
    • Nếu bạn muốn người dùng nhập cụm từ tìm kiếm 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ỉ như mong đợi ở một khu vực cụ thể, hãy sử dụng tính năng xu hướng vị trí.
    Các tình huống khác mà bạn nên quay lại API mã hóa địa lý là:
    • Người dùng nhập địa chỉ phụ ở các quốc gia khác ngoài Úc, New Zealand hoặc Canada. Ví dụ: địa chỉ tại Hoa Kỳ "123 Bowdoin St #456, Boston MA, USA" không được hỗ trợ bởi tính năng Tự động hoàn thành. (Tính năng tự động hoàn thành chỉ hỗ trợ địa chỉ phụ tại Úc, New Zealand và Canada). Định dạng địa chỉ được hỗ trợ tại 3 quốc gia này bao gồm "9/321 Amphitheatre Street, Sydney, New South Wales, Australia" hoặc "14/19 Langana Avenue, Browns Bay, Auckland, New Zealand" hoặc "145-112 Renfrew Dr, Markham, Ontario, Canada".)
    • Người dùng nhập địa chỉ với các tiền tố phân đ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 ở Hawai'i.

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 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ụ: 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 đã vượt quá hạn mức). Hãy xem bài viết 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 trong quá trình sử dụng các thành phần đ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ả.