Place Autocomplete (เดิม) จะแสดงการคาดคะเนสถานที่เพื่อตอบสนองต่อคำค้นหาของผู้ใช้ เมื่อผู้ใช้พิมพ์ บริการเติมข้อความอัตโนมัติจะแสดงคำแนะนำสำหรับสถานที่ เช่น ธุรกิจ ที่อยู่ Plus Codes และจุดที่น่าสนใจ
คุณเพิ่มการเติมข้อความอัตโนมัติลงในแอปได้ด้วยวิธีต่อไปนี้
- เพิ่มวิดเจ็ตการเติมข้อความอัตโนมัติเพื่อประหยัดเวลาในการพัฒนาและมอบประสบการณ์ที่สอดคล้องกันแก่ผู้ใช้
- รับการคาดคะเนสถานที่แบบเป็นโปรแกรมเพื่อสร้างประสบการณ์ของผู้ใช้ที่ปรับแต่งเอง
เพิ่มวิดเจ็ตการเติมข้อความอัตโนมัติ
วิดเจ็ตการเติมข้อความอัตโนมัติคือกล่องโต้ตอบการค้นหาที่มีฟังก์ชันการเติมข้อความอัตโนมัติในตัว เมื่อผู้ใช้ป้อนข้อความค้นหา วิดเจ็ตจะแสดงรายการสถานที่ที่คาดการณ์ไว้ให้เลือก เมื่อผู้ใช้เลือก ระบบจะแสดงผลอินสแตนซ์ Place ซึ่งแอปของคุณสามารถใช้เพื่อดูรายละเอียดเกี่ยวกับสถานที่ที่เลือกได้
การเพิ่มวิดเจ็ตการเติมข้อความอัตโนมัติลงในแอปมี 2 ตัวเลือกดังนี้
- ตัวเลือกที่ 1: ฝัง
AutocompleteSupportFragment - ตัวเลือกที่ 2: ใช้ Intent เพื่อเปิดกิจกรรมการเติมข้อความอัตโนมัติ
ตัวเลือกที่ 1: ฝัง AutocompleteSupportFragment
หากต้องการเพิ่ม AutocompleteSupportFragment ลงในแอป ให้ทำตามขั้นตอนต่อไปนี้
- เพิ่ม Fragment ลงในเลย์เอาต์ XML ของกิจกรรม
- เพิ่ม Listener ลงในกิจกรรมหรือ Fragment
เพิ่ม AutocompleteSupportFragment ลงในกิจกรรม
หากต้องการเพิ่ม AutocompleteSupportFragment ลงในกิจกรรม ให้เพิ่ม Fragment ใหม่ลงในเลย์เอาต์ XML เช่น
<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"
/>
- โดยค่าเริ่มต้น ส่วนย่อยจะไม่มีเส้นขอบหรือพื้นหลัง หากต้องการให้มีลักษณะที่สอดคล้องกัน ให้ฝัง Fragment ไว้ภายในองค์ประกอบเลย์เอาต์อื่น เช่น CardView
- หากคุณใช้ส่วนย่อยของการเติมข้อความอัตโนมัติและต้องการลบล้าง
onActivityResultคุณต้องเรียกใช้super.onActivityResultไม่เช่นนั้นส่วนย่อยจะทำงานไม่ถูกต้อง
เพิ่ม PlaceSelectionListener ลงในกิจกรรม
PlaceSelectionListener จะจัดการการแสดงผลสถานที่เพื่อตอบสนองต่อการเลือกของผู้ใช้ โค้ดต่อไปนี้แสดงการสร้างการอ้างอิงไปยัง Fragment และการเพิ่ม Listener ลงใน AutocompleteSupportFragment
Kotlin
// Build a BasicPlaceAutocomplete intent to allow the user to select a place. val basicAutocompleteIntent = BasicPlaceAutocomplete.createIntent(this) { setCountries(listOf("AU", "NZ")) }
Java
// Build a BasicPlaceAutocomplete intent to allow the user to select a place. Intent basicAutocompleteIntent = new BasicPlaceAutocomplete.IntentBuilder() .setCountries(List.of("AU", "NZ")) .build(this);
ตัวเลือกที่ 2: ใช้ Intent เพื่อเปิดกิจกรรมการเติมข้อความอัตโนมัติ
หากต้องการให้แอปใช้ขั้นตอนการนําทางอื่น (เช่น เพื่อทริกเกอร์ประสบการณ์การเติมข้อความอัตโนมัติจากไอคอนแทนช่องค้นหา) แอปจะเปิดการเติมข้อความอัตโนมัติได้โดยใช้ Intent
หากต้องการเปิดใช้วิดเจ็ตการเติมข้อความอัตโนมัติโดยใช้ Intent ให้ทำตามขั้นตอนต่อไปนี้
- ใช้
Autocomplete.IntentBuilderเพื่อสร้าง Intent โดยส่งโหมดAutocompleteที่ต้องการ - กำหนดตัวเปิดผลลัพธ์กิจกรรม
registerForActivityResultที่สามารถใช้เพื่อเปิด Intent และจัดการการคาดคะเนสถานที่ที่ผู้ใช้เลือกในผลลัพธ์
สร้าง Intent การเติมข้อความอัตโนมัติ
ตัวอย่างด้านล่างใช้
Autocomplete.IntentBuilder
เพื่อสร้าง Intent เพื่อเปิดใช้วิดเจ็ตการเติมข้อความอัตโนมัติเป็น Intent
Kotlin
val intent = PlaceAutocomplete.createIntent(this) { setTypesFilter(listOf(PlaceTypes.ESTABLISHMENT)) } startAutocomplete.launch(intent)
Java
// Start the autocomplete intent. Intent intent = new PlaceAutocomplete.IntentBuilder() .setTypesFilter(List.of(PlaceTypes.ESTABLISHMENT)) .build(this); startAutocomplete.launch(intent);
เมื่อใช้ Intent เพื่อเปิดวิดเจ็ตการเติมข้อความอัตโนมัติ คุณสามารถเลือกโหมดการแสดงผลแบบวางซ้อนหรือแบบเต็มหน้าจอได้ ภาพหน้าจอต่อไปนี้แสดงโหมดการแสดงผลแต่ละโหมดตามลำดับ
ลงทะเบียน Callback สำหรับผลลัพธ์ของ Intent
หากต้องการรับการแจ้งเตือนเมื่อผู้ใช้เลือกสถานที่ ให้กำหนด Launcher registerForActivityResult() ซึ่งจะเปิดกิจกรรมและจัดการผลลัพธ์ด้วย ดังที่แสดงในตัวอย่างต่อไปนี้ หากผู้ใช้เลือกการคาดคะเน ระบบจะส่งการคาดคะเนนั้นใน Intent ที่มีอยู่ในออบเจ็กต์ผลลัพธ์ เนื่องจาก Intent สร้างขึ้นโดย Autocomplete.IntentBuilder เมธอด Autocomplete.getPlaceFromIntent() จึงสามารถดึงออบเจ็กต์ Place ออกมาได้
Kotlin
private val startAutocomplete = registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult -> if (result.resultCode == RESULT_OK) { val intent = result.data if (intent != null) { val prediction = PlaceAutocomplete.getPredictionFromIntent(intent) if (prediction != null) { binding.autocompleteResult.text = getString( R.string.place_selection, prediction.getPrimaryText(null), prediction.placeId, prediction.getSecondaryText(null), ) Log.i( TAG, "Place: ${prediction.getPrimaryText(null)}, ${prediction.placeId}", ) } } } else if (result.resultCode == RESULT_CANCELED) { // The user canceled the operation. binding.autocompleteResult.setText(R.string.user_canceled_autocomplete) Log.i(TAG, "User canceled autocomplete") } else if (result.resultCode == PlacesSdkAutocompleteActivity.RESULT_ERROR) { val intent = result.data if (intent != null) { val status = PlaceAutocomplete.getResultStatusFromIntent(intent) Log.e(TAG, "An error occurred: ${status?.statusMessage}") } } }
Java
private final ActivityResultLauncher<Intent> startAutocomplete = registerForActivityResult( new ActivityResultContracts.StartActivityForResult(), result -> { if (result.getResultCode() == Activity.RESULT_OK) { Intent intent = result.getData(); if (intent != null) { AutocompletePrediction prediction = PlaceAutocomplete.getPredictionFromIntent(intent); if (prediction != null) { binding.autocompleteResult.setText( getString( R.string.place_selection, prediction.getPrimaryText(null), prediction.getPlaceId(), prediction.getSecondaryText(null))); Log.i( TAG, "Place: " + prediction.getPrimaryText(null) + ", " + prediction.getPlaceId()); } } } else if (result.getResultCode() == Activity.RESULT_CANCELED) { // The user canceled the operation. binding.autocompleteResult.setText(R.string.user_canceled_autocomplete); Log.i(TAG, "User canceled autocomplete"); } else if (result.getResultCode() == com.google.android.libraries.places.widget .PlaceAutocompleteActivity.RESULT_ERROR) { Intent intent = result.getData(); if (intent != null) { Status status = PlaceAutocomplete.getResultStatusFromIntent(intent); if (status != null) { Log.e(TAG, "An error occurred: " + status.getStatusMessage()); } } } });
การรับการคาดคะเนสถานที่แบบเป็นโปรแกรม
คุณสามารถสร้าง UI การค้นหาที่กำหนดเองเป็นทางเลือกแทน UI ที่วิดเจ็ตการเติมข้อความอัตโนมัติมีให้ โดยแอปของคุณต้องรับการคาดคะเนสถานที่แบบเป็นโปรแกรม แอปของคุณสามารถรับรายการชื่อและ/หรือที่อยู่ของสถานที่ที่คาดการณ์ไว้จาก Autocomplete API โดยเรียกใช้ PlacesClient.findAutocompletePredictions() และส่งออบเจ็กต์ FindAutocompletePredictionsRequest พร้อมพารามิเตอร์ต่อไปนี้
- ต้องระบุ: สตริง
queryที่มีข้อความที่ผู้ใช้พิมพ์ - แนะนำ:
AutocompleteSessionTokenซึ่งจะจัดกลุ่มระยะการค้นหาและการเลือกของการค้นหาของผู้ใช้เป็นเซสชันแยกกันเพื่อวัตถุประสงค์ในการเรียกเก็บเงิน เซสชันจะเริ่มต้นเมื่อผู้ใช้เริ่มพิมพ์คำค้นหา และสิ้นสุดเมื่อผู้ใช้เลือกสถานที่ - แนะนำ: ออบเจ็กต์
RectangularBoundsซึ่งระบุขอบเขตละติจูดและลองจิจูดเพื่อจำกัดผลลัพธ์ให้อยู่ในภูมิภาคที่ระบุ - ไม่บังคับ: รหัสประเทศ (ISO 3166-1 Alpha-2) แบบ 2 ตัวอักษรอย่างน้อย 1 รหัส ซึ่งระบุประเทศที่ควรจำกัดผลลัพธ์
ไม่บังคับ:
TypeFilterซึ่งคุณสามารถใช้เพื่อจำกัดผลการค้นหาให้อยู่ในประเภทสถานที่ที่ระบุ ระบบรองรับประเภทสถานที่ต่อไปนี้TypeFilter.GEOCODE– แสดงเฉพาะผลลัพธ์การเข้ารหัสพิกัดภูมิศาสตร์ ไม่ใช่ธุรกิจ ใช้คำขอนี้เพื่อแก้ความกำกวมของผลลัพธ์ที่สถานที่ตั้งที่ระบุอาจไม่แน่นอนTypeFilter.ADDRESS– แสดงเฉพาะผลลัพธ์การเติมข้อความอัตโนมัติที่มีที่อยู่ที่แน่นอน ใช้ประเภทนี้เมื่อคุณทราบว่าผู้ใช้กำลังมองหาที่อยู่ที่ระบุไว้อย่างครบถ้วนTypeFilter.ESTABLISHMENT– แสดงเฉพาะสถานที่ที่เป็นธุรกิจTypeFilter.REGIONS– แสดงผลเฉพาะสถานที่ที่ตรงกับประเภทใดประเภทหนึ่งต่อไปนี้LOCALITYSUBLOCALITYPOSTAL_CODECOUNTRYADMINISTRATIVE_AREA_LEVEL_1ADMINISTRATIVE_AREA_LEVEL_2TypeFilter.CITIES– แสดงเฉพาะผลลัพธ์ที่ตรงกับLOCALITYหรือADMINISTRATIVE_AREA_LEVEL_3
ไม่บังคับ:
LatLngที่ระบุตำแหน่งต้นทางของคำขอ เมื่อคุณเรียกใช้setOrigin()บริการจะแสดงผลระยะทางเป็นเมตร (distanceMeters) จากจุดเริ่มต้นที่ระบุสำหรับการคาดคะเนการเติมข้อความอัตโนมัติแต่ละรายการในการตอบกลับ
ดูข้อมูลเกี่ยวกับประเภทสถานที่ได้ที่คู่มือประเภทสถานที่
ตัวอย่างด้านล่างแสดงการเรียกใช้ 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.ESTABLISHMENT)) .setSessionToken(token) .setQuery(query) .build() placesClient.findAutocompletePredictions(request) .addOnSuccessListener { response: FindAutocompletePredictionsResponse -> val builder = StringBuilder() for (prediction in response.autocompletePredictions) { builder.append(prediction.getPrimaryText(null).toString()).append("\n") Log.i(TAG, prediction.placeId) Log.i(TAG, prediction.getPrimaryText(null).toString()) } binding.autocompleteResult.text = builder.toString() }.addOnFailureListener { exception: Exception? -> if (exception is ApiException) { Log.e(TAG, "Place not found: ${exception.statusCode}") binding.autocompleteResult.text = getString(R.string.place_not_found, exception.message) } }
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(List.of(PlaceTypes.ESTABLISHMENT)) .setSessionToken(token) .setQuery(query) .build(); placesClient .findAutocompletePredictions(request) .addOnSuccessListener( (response) -> { StringBuilder builder = new StringBuilder(); for (AutocompletePrediction prediction : response.getAutocompletePredictions()) { builder.append(prediction.getPrimaryText(null).toString()) .append("\n"); Log.i(TAG, prediction.getPlaceId()); Log.i(TAG, prediction.getPrimaryText(null).toString()); } binding.autocompleteResult.setText(builder.toString()); }) .addOnFailureListener( (exception) -> { if (exception instanceof ApiException apiException) { Log.e(TAG, "Place not found: " + apiException.getStatusCode()); binding.autocompleteResult.setText( getString( R.string.place_not_found, apiException.getMessage())); } });
API จะแสดงผล FindAutocompletePredictionsResponse ใน
Task FindAutocompletePredictionsResponse มีรายการออบเจ็กต์ AutocompletePrediction ที่แสดงสถานที่ที่คาดการณ์ไว้ รายการอาจว่างเปล่าหากไม่มีสถานที่ที่รู้จักซึ่งสอดคล้องกับคำค้นหาและเกณฑ์ตัวกรอง
สำหรับสถานที่ที่คาดการณ์แต่ละแห่ง คุณสามารถเรียกใช้เมธอดต่อไปนี้เพื่อดึงข้อมูลรายละเอียดสถานที่ได้
getFullText(CharacterStyle)แสดงข้อความทั้งหมดของคำอธิบายสถานที่ ซึ่งเป็นการรวมข้อความหลักและข้อความรองเข้าด้วยกัน ตัวอย่างเช่น "Eiffel Tower, Avenue Anatole France, Paris, France" นอกจากนี้ วิธีนี้ยังช่วยให้คุณไฮไลต์ส่วนของคำอธิบายที่ตรงกับการค้นหาด้วยสไตล์ที่คุณเลือกได้โดยใช้CharacterStyleพารามิเตอร์CharacterStyleเป็นพารามิเตอร์ที่ไม่บังคับ ตั้งค่าเป็น Null หากไม่ต้องการไฮไลต์getPrimaryText(CharacterStyle)แสดงข้อความหลักที่อธิบายสถานที่ ซึ่งโดยปกติแล้วจะเป็นชื่อของสถานที่ ตัวอย่าง: "หอไอเฟล" และ "123 ถนนสุขุมวิท"getSecondaryText(CharacterStyle)แสดงข้อความย่อยของคำอธิบายสถานที่ ซึ่งจะมีประโยชน์ เช่น เป็นบรรทัดที่ 2 เมื่อแสดงการคาดคะเนการเติมข้อความอัตโนมัติ ตัวอย่างเช่น "Avenue Anatole France, Paris, France" และ "Sydney, New South Wales"getPlaceId()แสดงรหัสสถานที่ของสถานที่ที่คาดการณ์ไว้ รหัสสถานที่เป็นตัวระบุแบบข้อความที่ระบุสถานที่ตั้งแบบไม่ซ้ำกัน ซึ่งคุณสามารถใช้เพื่อดึงข้อมูลออบเจ็กต์Placeอีกครั้งในภายหลังได้ ดูข้อมูลเพิ่มเติมเกี่ยวกับรหัสสถานที่ใน Places SDK สำหรับ Android ได้ที่รายละเอียดสถานที่ ดูข้อมูลทั่วไปเกี่ยวกับรหัสสถานที่ได้ที่ภาพรวมของรหัสสถานที่getPlaceTypes()แสดงรายการประเภทสถานที่ที่เชื่อมโยงกับสถานที่นี้getDistanceMeters()แสดงระยะทางแบบเส้นตรงเป็นเมตรระหว่างสถานที่นี้กับจุดเริ่มต้นที่ระบุในคำขอ
โทเค็นของเซสชัน
โทเค็นของเซสชันจะจัดกลุ่มระยะการค้นหาและการเลือกของการค้นหาด้วยการเติมข้อความอัตโนมัติของผู้ใช้ไว้ในเซสชันแยกต่างหากเพื่อวัตถุประสงค์ในการเรียกเก็บเงิน เซสชันจะเริ่มต้นเมื่อผู้ใช้เริ่มพิมพ์คำค้นหา และสิ้นสุดเมื่อผู้ใช้เลือกสถานที่ แต่ละเซสชันสามารถมีคำค้นหาได้หลายรายการ ตามด้วยการเลือกสถานที่ 1 แห่ง เมื่อเซสชันสิ้นสุดลง โทเค็นจะใช้ไม่ได้อีกต่อไป แอปของคุณต้องสร้างโทเค็นใหม่สำหรับแต่ละเซสชัน เราขอแนะนำให้ใช้โทเค็นของเซสชันสำหรับเซสชันการเติมข้อความอัตโนมัติแบบเป็นโปรแกรมทั้งหมด (เมื่อคุณฝังส่วนย่อยหรือเปิดใช้การเติมข้อความอัตโนมัติโดยใช้ Intent, API จะจัดการเรื่องนี้ให้โดยอัตโนมัติ)
Places SDK สำหรับ Android ใช้ AutocompleteSessionToken เพื่อระบุแต่ละเซสชัน แอปควรส่งโทเค็นของเซสชันใหม่เมื่อเริ่มเซสชันใหม่แต่ละเซสชัน จากนั้นส่งโทเค็นเดียวกันนั้นพร้อมกับรหัสสถานที่ในการเรียกใช้ fetchPlace() ครั้งต่อมาเพื่อดึงข้อมูลรายละเอียดสถานที่สำหรับสถานที่ที่ผู้ใช้เลือก
ดูข้อมูลเพิ่มเติมเกี่ยวกับโทเค็นของเซสชัน
จำกัดผลการเติมข้อความอัตโนมัติ
คุณสามารถจำกัดผลการเติมข้อความอัตโนมัติให้อยู่ในภูมิภาคทางภูมิศาสตร์ที่เฉพาะเจาะจง และ/หรือกรองผลลัพธ์เป็นประเภทสถานที่อย่างน้อย 1 ประเภท หรือสูงสุด 5 ประเทศ คุณสามารถใช้ข้อจำกัดเหล่านี้กับกิจกรรมการเติมข้อความอัตโนมัติ, AutocompleteSupportFragment และ API การเติมข้อความอัตโนมัติแบบเป็นโปรแกรม
หากต้องการจำกัดผลลัพธ์ ให้ทำดังนี้
- หากต้องการเลือกผลลัพธ์ภายในภูมิภาคที่กำหนด ให้เรียกใช้
setLocationBias()(ระบบอาจยังคงแสดงผลลัพธ์บางรายการจากภายนอกภูมิภาคที่กำหนด) - หากต้องการแสดงเฉพาะผลลัพธ์ภายในภูมิภาคที่กำหนด ให้เรียกใช้
setLocationRestriction()(ระบบจะแสดงเฉพาะผลลัพธ์ภายในภูมิภาคที่กำหนดเท่านั้น) - หากต้องการแสดงเฉพาะผลลัพธ์ที่สอดคล้องกับประเภทสถานที่หนึ่งๆ ให้เรียกใช้
setTypesFilter()(เช่น การระบุTypeFilter.ADDRESSจะแสดงเฉพาะผลลัพธ์ที่มีที่อยู่ที่แน่นอน) - หากต้องการแสดงเฉพาะผลลัพธ์ภายในประเทศที่ระบุไม่เกิน 5 ประเทศ ให้เรียกใช้
setCountries()ต้องส่งประเทศเป็นรหัสประเทศ 2 อักขระที่เข้ากันได้กับ ISO 3166-1 Alpha-2
ให้น้ำหนักผลการค้นหาตามภูมิภาคที่เฉพาะเจาะจง
หากต้องการให้น้ำหนักผลการเติมข้อความอัตโนมัติกับภูมิภาคทางภูมิศาสตร์ที่เฉพาะเจาะจง ให้เรียกใช้ setLocationBias() โดยส่ง RectangularBounds
ตัวอย่างโค้ดต่อไปนี้แสดงการเรียก setLocationBias() ในอินสแตนซ์ Fragment เพื่อให้น้ำหนักคำแนะนำที่เติมข้อความอัตโนมัติไปยังภูมิภาคซิดนีย์ ประเทศออสเตรเลีย
Kotlin
intentBuilder.setLocationBias(bounds)
Java
intentBuilder.setLocationBias( RectangularBounds.newInstance( new LatLng(-33.880490, 151.184363), new LatLng(-33.858754, 151.229596)));
จำกัดผลการค้นหาเฉพาะภูมิภาคที่กำหนด
หากต้องการจำกัดผลการเติมข้อความอัตโนมัติให้อยู่ในภูมิภาคทางภูมิศาสตร์ที่เฉพาะเจาะจง ให้เรียกใช้ setLocationRestriction() โดยส่ง RectangularBounds
ตัวอย่างโค้ดต่อไปนี้แสดงการเรียก setLocationRestriction() ในอินสแตนซ์ Fragment เพื่อให้น้ำหนักคำแนะนำที่เติมข้อความอัตโนมัติไปยังภูมิภาคซิดนีย์ ประเทศออสเตรเลีย
Kotlin
intentBuilder.setLocationRestriction(bounds)
Java
intentBuilder.setLocationRestriction( RectangularBounds.newInstance( new LatLng(-33.880490, 151.184363), new LatLng(-33.858754, 151.229596)));
หมายเหตุ: ข้อจำกัดนี้มีผลกับทั้งเส้นทางเท่านั้น ระบบอาจแสดงผลลัพธ์สังเคราะห์ที่อยู่นอกขอบเขตสี่เหลี่ยมผืนผ้าตามเส้นทางที่ทับซ้อนกับข้อจำกัดตำแหน่ง
กรองผลการค้นหาตามประเภทสถานที่หรือคอลเล็กชันประเภท
คุณสามารถจำกัดผลลัพธ์จากคำขอเติมข้อความอัตโนมัติเพื่อให้แสดงผลเฉพาะสถานที่บางประเภทเท่านั้น ระบุตัวกรองโดยใช้ประเภทสถานที่หรือคอลเล็กชันประเภทที่แสดงในตารางที่ 1, 2 และ 3 ในประเภทสถานที่ หากไม่ได้ระบุ ระบบจะแสดงผลทุกประเภท
หากต้องการกรองผลการเติมข้อความอัตโนมัติ ให้เรียกใช้
setTypesFilter()
เพื่อตั้งค่าตัวกรอง
วิธีระบุตัวกรองประเภทหรือคอลเล็กชันประเภท
เรียก
setTypesFilter()และระบุค่า type สูงสุด 5 ค่าจากตารางที่ 1 และตารางที่ 2 ที่แสดงในประเภทสถานที่ ค่าประเภทจะกำหนดโดยค่าคงที่ในPlaceTypesเรียกใช้
setTypesFilter()และระบุคอลเล็กชันประเภทจากตารางที่ 3 ที่แสดงในประเภทสถานที่ ค่าคอลเล็กชันจะกำหนดโดยค่าคงที่ในPlaceTypesอนุญาตให้ใช้ประเภทเดียวจากตารางที่ 3 ในคำขอ หากระบุค่าจากตารางที่ 3 คุณจะระบุค่าจากตารางที่ 1 หรือตารางที่ 2 ไม่ได้ มิฉะนั้นแล้ว จะเกิดข้อผิดพลาดขึ้น
ตัวอย่างโค้ดต่อไปนี้เรียกใช้ setTypesFilter() ใน AutocompleteSupportFragment และระบุค่าประเภทหลายค่า
Kotlin
intentBuilder.setTypesFilter(listOf("landmark", "restaurant", "store"))
Java
intentBuilder.setTypesFilter(List.of("landmark", "restaurant", "store"));
ตัวอย่างโค้ดต่อไปนี้แสดงการเรียก setTypesFilter() ใน AutocompleteSupportFragment เพื่อตั้งค่าตัวกรองที่แสดงเฉพาะผลลัพธ์ที่มีที่อยู่ที่แน่นอนโดยระบุคอลเล็กชันประเภท
Kotlin
intentBuilder.setTypesFilter(listOf(PlaceTypes.ADDRESS))
Java
intentBuilder.setTypesFilter(List.of(PlaceTypes.ESTABLISHMENT));
ตัวอย่างโค้ดต่อไปนี้แสดงการเรียก setTypesFilter() ใน IntentBuilder เพื่อตั้งค่าตัวกรองที่แสดงเฉพาะผลลัพธ์ที่มีที่อยู่ที่แน่นอนโดยระบุคอลเล็กชันประเภท
Kotlin
val intent = PlaceAutocomplete.createIntent(this) { setTypesFilter(listOf(PlaceTypes.ESTABLISHMENT)) }
Java
Intent intent = new PlaceAutocomplete.IntentBuilder() .setTypesFilter(List.of(PlaceTypes.ESTABLISHMENT)) .build(this);
กรองผลลัพธ์ตามประเทศ
หากต้องการกรองผลการเติมข้อความอัตโนมัติได้สูงสุด 5 ประเทศ ให้เรียกใช้
setCountries()
เพื่อตั้งค่ารหัสประเทศ
จากนั้นส่งตัวกรองไปยัง Fragment หรือ Intent ต้องส่งประเทศเป็นรหัสประเทศ 2 อักขระที่เข้ากันได้กับ ISO 3166-1 Alpha-2
ตัวอย่างโค้ดต่อไปนี้แสดงการเรียก setCountries() ใน AutocompleteSupportFragment เพื่อตั้งค่าตัวกรองที่แสดงเฉพาะผลลัพธ์ภายในประเทศที่ระบุ
Kotlin
intentBuilder.setCountries(listOf("AU", "NZ"))
Java
intentBuilder.setCountries(List.of("AU", "NZ"));
ขีดจำกัดการใช้งาน
การใช้งาน Places API (เดิม) รวมถึง Places SDK สำหรับ Android (เดิม) จะไม่จำกัดจำนวนคำขอสูงสุดต่อวัน (QPD) อีกต่อไป อย่างไรก็ตาม ขีดจำกัดการใช้งานต่อไปนี้จะยังคงมีผลอยู่
- ขีดจำกัดอัตราคือ 6,000 QPM (คำขอต่อนาที) ซึ่งคำนวณเป็นผลรวมของคำขอฝั่งไคลเอ็นต์และฝั่งเซิร์ฟเวอร์สำหรับแอปพลิเคชันทั้งหมดที่ใช้ข้อมูลเข้าสู่ระบบของโปรเจ็กต์เดียวกัน
แสดงการระบุแหล่งที่มาในแอป
- หากแอปใช้บริการเติมข้อความอัตโนมัติแบบเป็นโปรแกรม UI ของคุณต้องแสดงการระบุแหล่งที่มา "ขับเคลื่อนโดย Google" หรือปรากฏภายในแผนที่ที่มีแบรนด์ Google
- หากแอปใช้วิดเจ็ตการเติมข้อความอัตโนมัติ คุณไม่จำเป็นต้องดำเนินการใดๆ เพิ่มเติม (การระบุแหล่งที่มาที่จำเป็นจะแสดงโดยค่าเริ่มต้น)
- หากคุณดึงข้อมูลและแสดงข้อมูลสถานที่เพิ่มเติมหลังจากรับสถานที่ตามรหัส คุณต้องแสดงการระบุแหล่งที่มาของบุคคลที่สามด้วย
ดูรายละเอียดเพิ่มเติมได้ในเอกสารประกอบเกี่ยวกับการระบุแหล่งที่มา
การเพิ่มประสิทธิภาพ Place Autocomplete (เดิม)
ส่วนนี้อธิบายแนวทางปฏิบัติแนะนำเพื่อช่วยให้คุณใช้ประโยชน์จากบริการ Place Autocomplete (เดิม) ได้อย่างเต็มที่
หลักเกณฑ์ทั่วไปมีดังนี้
- วิธีที่เร็วที่สุดในการพัฒนาอินเทอร์เฟซผู้ใช้ที่ใช้งานได้คือการใช้ วิดเจ็ต Place Autocomplete (เดิม) ของ Maps JavaScript API, วิดเจ็ต Place Autocomplete (เดิม) ของ Places SDK สำหรับ Android หรือตัวควบคุม UI Place Autocomplete (เดิม) ของ Places SDK สำหรับ iOS
- ทำความเข้าใจฟิลด์ข้อมูลที่สำคัญของ Place Autocomplete (เดิม) ตั้งแต่เริ่มต้น
- ช่องการให้น้ำหนักตามสถานที่และการจำกัดสถานที่ตั้งเป็นช่องที่ไม่บังคับ แต่ก็อาจส่งผลต่อประสิทธิภาพการเติมข้อความอัตโนมัติอย่างมาก
- ใช้การจัดการข้อผิดพลาดเพื่อให้แน่ใจว่าแอปจะลดระดับลงอย่างราบรื่นหาก API แสดงข้อผิดพลาด
- ตรวจสอบว่าแอปของคุณจัดการกรณีที่ไม่มีการเลือกและเสนอวิธีให้ผู้ใช้ดำเนินการต่อ
แนวทางปฏิบัติแนะนำในการเพิ่มประสิทธิภาพต้นทุน
การเพิ่มประสิทธิภาพต้นทุนพื้นฐาน
หากต้องการเพิ่มประสิทธิภาพค่าใช้จ่ายในการใช้บริการ Place Autocomplete (เดิม) ให้ใช้มาสก์ฟิลด์ในวิดเจ็ตรายละเอียดสถานที่ (เดิม) และ Place Autocomplete (เดิม) เพื่อแสดงเฉพาะฟิลด์ข้อมูลของ Place Autocomplete (เดิม) ที่คุณต้องการ
การเพิ่มประสิทธิภาพต้นทุนขั้นสูง
พิจารณาการติดตั้งใช้งาน Place Autocomplete (เดิม) แบบเป็นโปรแกรมเพื่อเข้าถึง SKU: Autocomplete - ราคาต่อคำขอ และขอผลลัพธ์ Geocoding API เกี่ยวกับสถานที่ที่เลือกแทนรายละเอียดสถานที่ (เดิม) ราคาต่อคำขอที่จับคู่กับ Geocoding API จะคุ้มค่ากว่าราคาต่อเซสชัน (อิงตามเซสชัน) หากเป็นไปตามเงื่อนไขทั้ง 2 ข้อต่อไปนี้
- หากต้องการเพียงละติจูดและลองจิจูดหรือที่อยู่ของสถานที่ที่ผู้ใช้เลือก Geocoding API จะให้ข้อมูลนี้โดยมีค่าใช้จ่ายน้อยกว่าการเรียกใช้รายละเอียดสถานที่ (เดิม)
- หากผู้ใช้เลือกการคาดคะเนการเติมข้อความอัตโนมัติภายในคำขอ Place Autocomplete (เดิม) โดยเฉลี่ย 4 รายการหรือน้อยกว่า การกำหนดราคาต่อคำขออาจคุ้มค่ากว่าการกำหนดราคาต่อเซสชัน
แอปพลิเคชันของคุณต้องการข้อมูลอื่นนอกเหนือจากที่อยู่และละติจูด/ลองจิจูดของการคาดคะเนที่เลือกหรือไม่
ใช่ ต้องการรายละเอียดเพิ่มเติม
ใช้ Place Autocomplete ตามเซสชัน (เดิม) กับรายละเอียดสถานที่ (เดิม)
เนื่องจากแอปพลิเคชันของคุณต้องใช้รายละเอียดสถานที่ (เดิม) เช่น ชื่อสถานที่ สถานะธุรกิจ หรือเวลาทำการ การติดตั้งใช้งานการเติมข้อความอัตโนมัติสำหรับสถานที่ (เดิม) จึงควรใช้โทเค็นของเซสชัน (แบบเป็นโปรแกรมหรือสร้างไว้ในวิดเจ็ต JavaScript, Android หรือ iOS) ต่อเซสชัน รวมถึง SKU ข้อมูล Places ที่เกี่ยวข้อง โดยขึ้นอยู่กับฟิลด์ข้อมูลสถานที่ที่คุณขอ1
การติดตั้งใช้งานวิดเจ็ต
การจัดการเซสชันจะติดตั้งมาในวิดเจ็ต JavaScript, Android หรือ iOS โดยอัตโนมัติ ซึ่งรวมถึงทั้งคำขอ Place Autocomplete (เดิม) และคำขอรายละเอียดสถานที่ (เดิม) ในการคาดคะเนที่เลือก อย่าลืมระบุพารามิเตอร์ fields เพื่อให้มั่นใจว่าคุณขอเฉพาะฟิลด์ข้อมูลของ Place Autocomplete (เดิม) ที่ต้องการเท่านั้น
การติดตั้งใช้งานแบบเป็นโปรแกรม
ใช้โทเค็นของเซสชันกับคำขอ Place Autocomplete (เดิม) เมื่อขอรายละเอียดสถานที่ (เดิม) เกี่ยวกับการคาดคะเนที่เลือก ให้ใส่พารามิเตอร์ต่อไปนี้
- รหัสสถานที่จากการตอบกลับของ Place Autocomplete (เดิม)
- โทเค็นของเซสชันที่ใช้ในคำขอ Place Autocomplete (เดิม)
- พารามิเตอร์
fieldsที่ระบุฟิลด์ข้อมูลของ Place Autocomplete (เดิม) ที่คุณต้องการ
ไม่ ต้องใช้เพียงที่อยู่และสถานที่ตั้ง
Geocoding API อาจเป็นตัวเลือกที่คุ้มค่ากว่ารายละเอียดสถานที่ (เดิม) สำหรับแอปพลิเคชันของคุณ ทั้งนี้ขึ้นอยู่กับประสิทธิภาพการใช้งาน Place Autocomplete (เดิม) ประสิทธิภาพของ Place Autocomplete (เดิม) ของแต่ละแอปพลิเคชันจะแตกต่างกันไปตามสิ่งที่ผู้ใช้ป้อน สถานที่ที่ใช้แอปพลิเคชัน และมีการใช้แนวทางปฏิบัติแนะนำในการเพิ่มประสิทธิภาพหรือไม่
หากต้องการตอบคำถามต่อไปนี้ ให้วิเคราะห์จำนวนอักขระที่ผู้ใช้พิมพ์โดยเฉลี่ยก่อนเลือกการคาดคะเน Place Autocomplete (เดิม) ในแอปพลิเคชันของคุณ
โดยเฉลี่ยแล้ว ผู้ใช้เลือกการคาดคะเนของ Place Autocomplete (เดิม) ในคำขอไม่เกิน 4 รายการใช่ไหม
ใช่
ใช้ Place Autocomplete (เดิม) แบบเป็นโปรแกรมโดยไม่มีโทเค็นของเซสชัน และเรียกใช้ Geocoding API ในการคาดคะเนสถานที่ที่เลือก
Geocoding API จะแสดงที่อยู่และพิกัดละติจูด/ลองจิจูด
การส่งคำขอ Autocomplete - ต่อคำขอ 4 รายการบวกกับการเรียกใช้ Geocoding API เกี่ยวกับการคาดคะเนสถานที่ที่เลือกจะมีค่าใช้จ่ายน้อยกว่า Place Autocomplete (เดิม) ต่อเซสชัน1
ลองใช้แนวทางปฏิบัติแนะนำด้านประสิทธิภาพเพื่อช่วยให้ผู้ใช้ได้รับการคาดคะเนที่ต้องการโดยใช้อักขระน้อยลง
ไม่ใช่
ใช้ Place Autocomplete ตามเซสชัน (เดิม) กับรายละเอียดสถานที่ (เดิม)
เนื่องจากจำนวนคำขอเฉลี่ยที่คุณคาดว่าจะทำก่อนที่ผู้ใช้จะเลือกการคาดคะเนของ Place Autocomplete (เดิม) เกินค่าใช้จ่ายของการกำหนดราคาต่อเซสชัน การใช้งาน Place Autocomplete (เดิม) ของคุณจึงควรใช้โทเค็นของเซสชันสำหรับทั้งคำขอ Place Autocomplete (เดิม) และคำขอรายละเอียดสถานที่ (เดิม) ที่เกี่ยวข้อง
ต่อเซสชัน
1
การติดตั้งใช้งานวิดเจ็ต
การจัดการเซสชันจะติดตั้งมาในวิดเจ็ต JavaScript, Android หรือ iOS โดยอัตโนมัติ ซึ่งรวมถึงทั้งคำขอ Place Autocomplete (เดิม) และคำขอรายละเอียดสถานที่ (เดิม) ในการคาดคะเนที่เลือก อย่าลืมระบุพารามิเตอร์ fields เพื่อให้แน่ใจว่าคุณขอเฉพาะช่องที่ต้องการเท่านั้น
การติดตั้งใช้งานแบบเป็นโปรแกรม
ใช้โทเค็นของเซสชันกับคำขอ Place Autocomplete (เดิม)
เมื่อขอรายละเอียดสถานที่ (เดิม) เกี่ยวกับการคาดคะเนที่เลือก ให้ใส่พารามิเตอร์ต่อไปนี้
- รหัสสถานที่จากการตอบกลับของ Place Autocomplete (เดิม)
- โทเค็นของเซสชันที่ใช้ในคำขอ Place Autocomplete (เดิม)
- พารามิเตอร์
fieldsที่ระบุฟิลด์ข้อมูลพื้นฐาน เช่น ที่อยู่และเรขาคณิต
พิจารณาการหน่วงเวลาคำขอ Place Autocomplete (เดิม)
คุณสามารถใช้กลยุทธ์ต่างๆ เช่น การหน่วงเวลาคำขอ Place Autocomplete (เดิม) จนกว่าผู้ใช้จะพิมพ์อักขระ 3 หรือ 4 ตัวแรก เพื่อให้แอปพลิเคชันส่งคำขอน้อยลง ตัวอย่างเช่น การส่งคำขอ Place Autocomplete (เดิม) สำหรับอักขระแต่ละตัวหลังจากที่ผู้ใช้พิมพ์อักขระตัวที่ 3 หมายความว่าหากผู้ใช้พิมพ์อักขระ 7 ตัวแล้วเลือกการคาดคะเนที่คุณส่งคำขอ Geocoding API 1 รายการ ค่าใช้จ่ายทั้งหมดจะเป็นค่าใช้จ่ายสำหรับ Place Autocomplete (เดิม) 4 รายการต่อคำขอ + การเข้ารหัสพิกัดภูมิศาสตร์1
หากการหน่วงเวลาคำขอช่วยให้คำขอแบบเป็นโปรแกรมโดยเฉลี่ยต่ำกว่า 4 รายการ คุณสามารถทำตามคำแนะนำสำหรับการติดตั้งใช้งาน Place Autocomplete (เดิม) ที่มีประสิทธิภาพด้วย Geocoding API โปรดทราบว่าการหน่วงเวลาคำขออาจทำให้ผู้ใช้ที่คาดหวังว่าจะเห็นการคาดคะเนทุกครั้งที่กดแป้นพิมพ์ใหม่มองว่าเป็นเวลาในการตอบสนอง
ลองใช้แนวทางปฏิบัติแนะนำด้านประสิทธิภาพเพื่อช่วยให้ผู้ใช้ได้รับการคาดคะเนที่ต้องการโดยใช้อักขระน้อยลง
-
ดูค่าใช้จ่ายได้ที่รายการราคาของ Google Maps Platform
แนวทางปฏิบัติแนะนำด้านประสิทธิภาพ
หลักเกณฑ์ต่อไปนี้อธิบายวิธีเพิ่มประสิทธิภาพ Place Autocomplete (เดิม)
- เพิ่มข้อจำกัดในแต่ละประเทศ การให้น้ำหนักสถานที่ตั้ง และ (สำหรับการใช้งานแบบเป็นโปรแกรม) ค่ากำหนดภาษาลงในการใช้งาน Place Autocomplete (เดิม) ไม่จำเป็นต้องใช้ค่ากำหนดภาษาสำหรับวิดเจ็ต เนื่องจากวิดเจ็ตจะเลือกค่ากำหนดภาษาจากเบราว์เซอร์หรืออุปกรณ์เคลื่อนที่ของผู้ใช้
- หาก Place Autocomplete (เดิม) มาพร้อมกับแผนที่ คุณสามารถให้น้ำหนักสถานที่ตามวิวพอร์ตของแผนที่ได้
- ในสถานการณ์ที่ผู้ใช้ไม่ได้เลือกการคาดคะเน Place Autocomplete (เดิม) รายการใดรายการหนึ่ง โดยทั่วไปเป็นเพราะไม่มีการคาดคะเนใดที่เป็นที่อยู่ผลลัพธ์ที่ต้องการ คุณสามารถนำข้อมูลที่ผู้ใช้ป้อนไว้เดิมมาใช้ซ้ำเพื่อพยายามรับผลลัพธ์ที่เกี่ยวข้องมากขึ้นได้ ดังนี้
- หากคาดว่าผู้ใช้จะป้อนเฉพาะข้อมูลที่อยู่ ให้นำข้อมูลที่ผู้ใช้ป้อนไว้เดิมมาใช้ซ้ำในการเรียกใช้ Geocoding API
- หากคุณคาดหวังให้ผู้ใช้ป้อนคำค้นหาสำหรับสถานที่ที่เฉพาะเจาะจงตามชื่อหรือที่อยู่ ให้ใช้คำขอรายละเอียดสถานที่ (เดิม) หากคาดว่าผลลัพธ์จะอยู่ในภูมิภาคที่เฉพาะเจาะจงเท่านั้น ให้ใช้การให้น้ำหนักสถานที่ตั้ง
- ผู้ใช้ป้อนที่อยู่ย่อย เช่น ที่อยู่ของยูนิตหรืออพาร์ตเมนต์ที่เฉพาะเจาะจงภายในอาคาร เช่น ที่อยู่ภาษาเช็ก "Stroupežnického 3191/17, Praha" จะแสดงการคาดคะเนบางส่วนใน Place Autocomplete (เดิม)
- ผู้ใช้ป้อนที่อยู่ที่มีคำนำหน้าส่วนถนน เช่น "23-30 29th St, Queens" ในนครนิวยอร์ก หรือ "47-380 Kamehameha Hwy, Kaneohe" บนเกาะคาไวในฮาวาย
การให้น้ำหนักพิเศษกับบางตำแหน่ง
ให้น้ำหนักผลการค้นหาไปยังพื้นที่ที่ระบุโดยส่งพารามิเตอร์ location และพารามิเตอร์ radius ซึ่งจะสั่งให้ Place Autocomplete (เดิม) เลือกแสดงผลลัพธ์ภายในพื้นที่ที่กำหนด ผลลัพธ์ที่อยู่นอกพื้นที่ที่กำหนดอาจยังคงแสดงอยู่ คุณสามารถใช้พารามิเตอร์ includedRegionCodes เพื่อกรองผลลัพธ์ให้แสดงเฉพาะสถานที่ภายในประเทศที่ระบุได้
การจำกัดสถานที่ตั้ง
จำกัดผลการค้นหาให้อยู่ในพื้นที่ที่ระบุโดยส่งพารามิเตอร์ locationRestriction
นอกจากนี้ คุณยังจำกัดผลการค้นหาให้อยู่ในภูมิภาคที่กำหนดโดย location และพารามิเตอร์ radius ได้ด้วยการเพิ่มพารามิเตอร์ strictbounds ซึ่งจะสั่งให้ Place Autocomplete (เดิม) แสดงผลลัพธ์เฉพาะภายในภูมิภาคนั้น
การแก้ปัญหา
แม้ว่าข้อผิดพลาดจะเกิดขึ้นได้หลากหลาย แต่ข้อผิดพลาดส่วนใหญ่ที่แอปของคุณอาจพบมักเกิดจากข้อผิดพลาดในการกำหนดค่า (เช่น มีการใช้คีย์ API ที่ไม่ถูกต้อง หรือมีการกำหนดค่าคีย์ API ไม่ถูกต้อง) หรือข้อผิดพลาดเกี่ยวกับโควต้า (แอปของคุณใช้โควต้าเกิน) ดูข้อมูลเพิ่มเติมเกี่ยวกับโควต้าได้ที่ขีดจำกัดการใช้งาน
ข้อผิดพลาดที่เกิดขึ้นในการใช้ตัวควบคุมการเติมข้อความอัตโนมัติจะแสดงใน Callback onActivityResult() เรียกใช้ Autocomplete.getStatus() เพื่อรับข้อความสถานะสำหรับผลลัพธ์