บริการเติมข้อความอัตโนมัติใน Places SDK สำหรับ Android ส่งคืน การคาดคะเนตอบกลับคำค้นหาของผู้ใช้ ตามที่ผู้ใช้พิมพ์ พารามิเตอร์ บริการเติมข้อความอัตโนมัติจะแสดงคำแนะนำสถานที่ต่างๆ เช่น ธุรกิจต่างๆ ที่อยู่ โค้ด Plus และ จุดที่น่าสนใจ
คุณสามารถเพิ่มการเติมข้อความอัตโนมัติในแอปได้ด้วยวิธีต่อไปนี้
- เพิ่มวิดเจ็ตการเติมข้อความอัตโนมัติเพื่อบันทึก เวลาในการพัฒนา และทำให้ผู้ใช้ได้รับประสบการณ์ที่สอดคล้องกัน
- รับการคาดคะเนสถานที่ แบบเป็นโปรแกรมเพื่อสร้าง ประสบการณ์ของผู้ใช้ที่กำหนดเอง
เพิ่มวิดเจ็ตการเติมข้อความอัตโนมัติ
วิดเจ็ตเติมข้อความอัตโนมัติเป็นกล่องโต้ตอบการค้นหาที่มีการเติมข้อความอัตโนมัติในตัว
ขณะที่ผู้ใช้ป้อนข้อความค้นหา วิดเจ็ตจะแสดงรายการ
สถานที่ที่คาดคะเนไว้ให้เลือกสรร เมื่อผู้ใช้เลือก
Place
ซึ่งแอปสามารถใช้เพื่อรับรายละเอียดเกี่ยวกับ
สถานที่ที่เลือก
การเพิ่มวิดเจ็ตการเติมข้อความอัตโนมัติลงในแอปทำได้ 2 วิธีดังนี้
- ตัวเลือกที่ 1: ฝัง
AutocompleteSupportFragment
- ตัวเลือกที่ 2: ใช้ Intent เพื่อเปิดกิจกรรมการเติมข้อความอัตโนมัติ
ตัวเลือกที่ 1: ฝัง AutocompleteSupportFragment
หากต้องการเพิ่ม AutocompleteSupportFragment
ลงในแอป ให้ทำตามขั้นตอนต่อไปนี้
- เพิ่มส่วนย่อยในเลย์เอาต์ XML ของกิจกรรม
- เพิ่ม Listener ลงในกิจกรรมหรือส่วนย่อย
เพิ่ม AutocompleteSupportFragment ในกิจกรรม
หากต้องการเพิ่ม AutocompleteSupportFragment
ในกิจกรรม ให้เพิ่มส่วนย่อยใหม่ลงใน
เลย์เอาต์ 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"
/>
- ส่วนย่อยที่ไม่มีเส้นขอบหรือพื้นหลังโดยค่าเริ่มต้น หากต้องการจัดเตรียม รูปลักษณ์ที่สอดคล้องกัน ฝังส่วนย่อยภายในเลย์เอาต์อื่น องค์ประกอบ เช่น CardView
- หากคุณกำลังใช้ส่วนการเติมข้อความอัตโนมัติและจำเป็นต้องลบล้าง
onActivityResult
คุณต้องโทรหาsuper.onActivityResult
ไม่เช่นนั้น ส่วนย่อยทำงานไม่ถูกต้อง
เพิ่ม PlaceSelectionListener ลงในกิจกรรม
PlaceSelectionListener
จัดการกับการแสดงผลสถานที่ตอบกลับผู้ใช้
มากมาย โค้ดต่อไปนี้จะแสดงการสร้างการอ้างอิงไปยังส่วนย่อยและ
กำลังเพิ่ม Listener ลงใน 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); } });
ตัวเลือกที่ 2: ใช้ความตั้งใจเพื่อเปิดกิจกรรมการเติมข้อความอัตโนมัติ
หากคุณต้องการให้แอปใช้ขั้นตอนการนำทางที่ต่างออกไป (เช่น เรียกใช้การเติมข้อความอัตโนมัติจากไอคอนแทนที่จะเป็นช่องค้นหา) แอปของคุณสามารถเปิดการเติมข้อความอัตโนมัติโดยใช้ Intent
หากต้องการเปิดใช้งานวิดเจ็ตการเติมข้อความอัตโนมัติโดยใช้ความตั้งใจ ให้ทำตามขั้นตอนต่อไปนี้
- ใช้
Autocomplete.IntentBuilder
เพื่อสร้าง Intent โดยผ่านโหมดAutocomplete
ที่ต้องการ - กำหนดตัวเปิดผลลัพธ์กิจกรรม
registerForActivityResult
ซึ่งสามารถใช้เพื่อแสดงความตั้งใจและจัดการกับสถานที่ที่ผู้ใช้เลือก การคาดการณ์ในผลลัพธ์
สร้าง Intent ในการเติมข้อความอัตโนมัติ
ตัวอย่างด้านล่างใช้
Autocomplete.IntentBuilder
ในการสร้างความตั้งใจที่จะเปิดวิดเจ็ตการเติมข้อความอัตโนมัติเป็น Intent
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);
เมื่อใช้การเปิดวิดเจ็ตเติมข้อความอัตโนมัติ คุณสามารถเลือก โหมดวางซ้อนหรือโหมดการแสดงผลแบบเต็มหน้าจอ ภาพหน้าจอต่อไปนี้แสดง โหมดการแสดงผลตามลำดับ
![เมื่อแสดงในโหมดวางซ้อน วิดเจ็ตเติมข้อความอัตโนมัติจะปรากฏซ้อนทับ UI การเรียกใช้](https://developers-dot-devsite-v2-prod.appspot.com/static/maps/documentation/places/images/acw_overlay.png?authuser=19&hl=th)
![เมื่อแสดงในโหมดเต็มหน้าจอ วิดเจ็ตเติมข้อความอัตโนมัติจะแสดงเต็มหน้าจอ](https://developers-dot-devsite-v2-prod.appspot.com/static/maps/documentation/places/images/acw_fullscreen.png?authuser=19&hl=th)
ลงทะเบียน Callback สำหรับผลลัพธ์ของ Intent
หากต้องการรับการแจ้งเตือนเมื่อผู้ใช้เลือกสถานที่ ให้กำหนด
Launcher ของ registerForActivityResult()
ซึ่งจะเปิดกิจกรรมและจัดการ
ดังที่แสดงในตัวอย่างต่อไปนี้ หากผู้ใช้เลือกการคาดการณ์
จะแสดงใน Intent ที่มีอยู่ในออบเจ็กต์ผลลัพธ์ เนื่องจากความตั้งใจ
สร้างโดย Autocomplete.IntentBuilder
Autocomplete.getPlaceFromIntent()
สามารถแยกวัตถุสถานที่ออก
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"); } });
การรับการคาดคะเนสถานที่แบบเป็นโปรแกรม
คุณสามารถสร้าง UI การค้นหาที่กำหนดเองเป็นทางเลือกแทน UI ที่
วิดเจ็ตการเติมข้อความอัตโนมัติ โดยแอปต้องได้รับการคาดคะเนสถานที่จึงจะดำเนินการนี้ได้
แบบเป็นโปรแกรม แอปของคุณสามารถรับรายการชื่อสถานที่ที่คาดการณ์ไว้ และ/หรือ
จาก API การเติมข้อความอัตโนมัติด้วยการเรียก
PlacesClient.findAutocompletePredictions()
การส่งผ่าน
FindAutocompletePredictionsRequest
ที่มีพารามิเตอร์ต่อไปนี้
- ต้องระบุ: สตริง
query
ที่มีข้อความที่ผู้ใช้พิมพ์ - แนะนำ: A
AutocompleteSessionToken
ซึ่งจัดกลุ่มขั้นตอนการค้นหาและการเลือกของผู้ใช้เป็นการค้นหาแบบแยกกัน เซสชันเพื่อจุดประสงค์ในการเรียกเก็บเงิน เซสชันจะเริ่มต้นเมื่อผู้ใช้เริ่มพิมพ์ ข้อความค้นหา และสรุปเมื่อผู้อ่านเลือกสถานที่ - แนะนำ:
RectangularBounds
ซึ่งระบุขอบเขตละติจูดและลองจิจูดเพื่อจำกัดผลลัพธ์เป็น ภูมิภาคที่ระบุ - ไม่บังคับ: country ที่มีตัวอักษร 2 ตัวขึ้นไป รหัส (ISO 3166-1 Alpha-2) ระบุประเทศที่จะให้ผลการค้นหาปรากฏ แบบจำกัด
ไม่บังคับ: ตอบ
TypeFilter
ซึ่งคุณสามารถใช้เพื่อจำกัดผลลัพธ์ให้อยู่ในประเภทสถานที่ที่ระบุ ประเภทสถานที่ที่ได้รับการสนับสนุนมีดังนี้TypeFilter.GEOCODE
– แสดงเฉพาะผลลัพธ์การระบุพิกัดทางภูมิศาสตร์ ไม่ใช่ ธุรกิจ ใช้คำขอนี้เพื่อชี้แจงผลลัพธ์ที่มี อาจไม่ทราบตำแหน่งTypeFilter.ADDRESS
– แสดงเฉพาะผลลัพธ์การเติมข้อความอัตโนมัติด้วย ที่ถูกต้อง ใช้ประเภทนี้เมื่อคุณทราบว่าผู้ใช้กำลังมองหา ที่อยู่ที่ระบุไว้โดยสมบูรณ์TypeFilter.ESTABLISHMENT
– แสดงเฉพาะสถานที่ที่ ธุรกิจTypeFilter.REGIONS
– แสดงเฉพาะสถานที่ที่ตรงกับหนึ่งใน ประเภทต่อไปนี้LOCALITY
SUBLOCALITY
POSTAL_CODE
COUNTRY
ADMINISTRATIVE_AREA_LEVEL_1
ADMINISTRATIVE_AREA_LEVEL_2
TypeFilter.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.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 จะแสดงผล
FindAutocompletePredictionsResponse
ใน
Task
FindAutocompletePredictionsResponse
มีรายการของ
AutocompletePrediction
ซึ่งแสดงสถานที่ที่คาดการณ์ไว้ รายการอาจว่างเปล่าหากไม่มี
ตำแหน่งที่ทราบ ซึ่งตรงกับข้อความค้นหาและเกณฑ์ตัวกรอง
สำหรับสถานที่ที่คาดคะเนไว้แต่ละแห่ง คุณสามารถเรียกใช้วิธีต่อไปนี้เพื่อเรียกข้อมูลสถานที่ได้ รายละเอียด:
getFullText(CharacterStyle)
จะแสดงข้อความทั้งหมดของคำอธิบายสถานที่ โดยเป็นการรวมระหว่าง ข้อความหลักและรอง ตัวอย่าง: "Eiffel Tower, Avenue Anatole France, ปารีส ฝรั่งเศส" นอกจากนี้ วิธีการนี้ช่วยให้คุณไฮไลต์ส่วนของ ที่ตรงกับการค้นหากับรูปแบบที่คุณต้องการ โดยใช้CharacterStyle
คุณจะระบุพารามิเตอร์CharacterStyle
หรือไม่ก็ได้ ตั้งค่าเป็น Null หากคุณไม่ตั้งค่า ต้องการไฮไลต์getPrimaryText(CharacterStyle)
จะแสดงข้อความหลักที่อธิบายสถานที่ ซึ่งโดยปกติจะเป็นชื่อของ ตัวอย่างเช่น "Eiffel Tower" และ "123 Pitt Street"getSecondaryText(CharacterStyle)
แสดงข้อความของบริษัทในเครือของคำอธิบายสถานที่ ซึ่งจะเป็นประโยชน์สำหรับ เช่น ในบรรทัดที่สองเมื่อแสดงการคาดคะเนการเติมข้อความอัตโนมัติ ตัวอย่าง: "Avenue Anatole France, Paris, France" และ "ซิดนีย์ นิวเซาท์เวลส์"getPlaceId()
จะแสดงรหัสสถานที่ของสถานที่ที่คาดคะเน รหัสสถานที่เป็นข้อความ ข้อมูลที่ใช้ในการระบุสถานที่แบบไม่ซ้ำ ซึ่งคุณสามารถใช้เพื่อเรียกดู เวลาPlace
อีกครั้งในภายหลัง สำหรับข้อมูลเพิ่มเติมเกี่ยวกับรหัสสถานที่ใน Places SDK สำหรับ Android โปรดดูสถานที่ รายละเอียด ทั่วไป ข้อมูลเกี่ยวกับรหัสสถานที่ โปรดดูรหัสสถานที่ ภาพรวมgetPlaceTypes()
แสดงรายการประเภทสถานที่ที่เชื่อมโยงกับสถานที่นี้getDistanceMeters()
จะแสดงระยะทางของเส้นตรงเป็นเมตรระหว่างสถานที่นี้กับ ต้นทางที่ระบุไว้ในคำขอ
โทเค็นของเซสชัน
โทเค็นเซสชันจะจัดกลุ่มขั้นตอนการค้นหาและการเลือกของการเติมข้อความอัตโนมัติของผู้ใช้ ค้นหาในเซสชันที่แยกกันโดยสิ้นเชิงเพื่อจุดประสงค์ในการเรียกเก็บเงิน เซสชันจะเริ่มต้นเมื่อ ผู้ใช้เริ่มพิมพ์ข้อความค้นหา และสรุปผลเมื่อเลือกสถานที่ แต่ละเซสชัน สามารถมีข้อความค้นหาได้หลายรายการ ตามด้วยตัวเลือกสถานที่ 1 แห่ง เมื่อเซสชันมี และได้ข้อสรุป โทเค็นนั้นใช้ไม่ได้แล้ว แอปของคุณต้องสร้างโทเค็นใหม่ สำหรับแต่ละเซสชัน เราขอแนะนำให้ใช้โทเค็นเซสชันสำหรับการดำเนินการแบบเป็นโปรแกรมทั้งหมด เซสชันการเติมข้อความอัตโนมัติ (เมื่อคุณฝังส่วนย่อย หรือเปิดใช้งานการเติมข้อความอัตโนมัติโดยใช้ 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()
ในส่วนย่อย
เพื่อทำให้ข้อเสนอแนะในการเติมข้อความอัตโนมัติให้น้ำหนักพิเศษกับภูมิภาคของซิดนีย์ ออสเตรเลีย
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)));
จำกัดผลการค้นหาไปยังภูมิภาคที่เฉพาะเจาะจง
หากต้องการจำกัดผลลัพธ์ของการเติมข้อความอัตโนมัติในพื้นที่ทางภูมิศาสตร์ที่เฉพาะเจาะจง ให้โทร
setLocationRestriction()
ผ่าน
RectangularBounds
ตัวอย่างโค้ดต่อไปนี้แสดงการเรียกใช้ setLocationRestriction()
บน
แบ่งอินสแตนซ์เพื่อลำเอียงให้ข้อเสนอแนะการเติมข้อความอัตโนมัติกับภูมิภาคของซิดนีย์
ออสเตรเลีย
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)));
หมายเหตุ: ข้อจำกัดนี้มีผลกับทั้งเส้นทาง ผลการค้นหาสังเคราะห์เท่านั้น ซึ่งอยู่นอกขอบเขตสี่เหลี่ยมผืนผ้าอาจส่งคืนได้ตามเส้นทางที่ ทับซ้อนกับการจำกัดสถานที่
กรองผลการค้นหาตามประเภทสถานที่หรือการรวบรวมประเภท
คุณสามารถจำกัดผลลัพธ์จากคำขอเติมข้อความอัตโนมัติ เพื่อให้คำขอแสดงเฉพาะผลลัพธ์ สถานที่บางประเภท ระบุตัวกรองโดยใช้ประเภทสถานที่หรือคอลเล็กชันประเภท แสดงในตารางที่ 1, 2 และ 3 เรื่องประเภทสถานที่ หากไม่มีสิ่งใด ที่ระบุไว้ ระบบจะแสดงผลทุกประเภท
หากต้องการกรองผลการค้นหาการเติมข้อความอัตโนมัติ ให้โทร
setTypesFilter()
เพื่อตั้งค่าตัวกรอง
ในการระบุประเภทหรือตัวกรองคอลเล็กชัน:
เรียกใช้
setTypesFilter()
และระบุค่า type ได้สูงสุด 5 ค่าจากตาราง 1 และตาราง 2 ซึ่งแสดงในประเภทสถานที่ ค่าประเภทคือ ที่กำหนดโดยค่าคงที่ใน PlaceTypesเรียกใช้
setTypesFilter()
และระบุการรวบรวมประเภทจากตาราง 3 ที่แสดง เกี่ยวกับประเภทสถานที่ ค่าคอลเล็กชันจะกำหนดโดย ค่าคงที่ใน PlaceTypesคำขอจะมีเพียงประเภทเดียวจากตาราง 3 หากคุณระบุ จากตาราง 3 คุณไม่สามารถระบุค่าจากตาราง 1 หรือตาราง 2 ได้ ถ้า แล้วเกิดข้อผิดพลาดขึ้น
ตัวอย่างโค้ดต่อไปนี้เรียก setTypesFilter()
ใน
AutocompleteSupportFragment
และระบุค่าหลายประเภท
Kotlin
autocompleteFragment.setTypesFilter(listOf("landmark", "restaurant", "store"))
Java
autocompleteFragment.setTypesFilter(Arrays.asList("landmark", "restaurant", "store"));
ตัวอย่างโค้ดต่อไปนี้แสดงการเรียกใช้ setTypesFilter()
ใน
AutocompleteSupportFragment
เพื่อตั้งค่าตัวกรองซึ่งแสดงเฉพาะผลลัพธ์ที่มี
ที่อยู่อย่างละเอียดได้ด้วยการระบุประเภทคอลเล็กชัน
Kotlin
autocompleteFragment.setTypesFilter(listOf(PlaceTypes.ADDRESS))
Java
autocompleteFragment.setTypesFilter(Arrays.asList(PlaceTypes.ADDRESS, PlaceTypes.ESTABLISHMENT));
ตัวอย่างโค้ดต่อไปนี้แสดงการเรียกใช้ setTypesFilter()
ใน
IntentBuilder
เพื่อตั้งค่าตัวกรองซึ่งแสดงเฉพาะผลลัพธ์ที่มีที่อยู่ที่ถูกต้องภายในวันที่
ระบุคอลเล็กชันประเภท
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);
กรองผลการค้นหาตามประเทศ
หากต้องการกรองผลการค้นหาการเติมข้อความอัตโนมัติให้ไม่เกิน 5 ประเทศ ให้โทรหา
setCountries()
เพื่อตั้งค่ารหัสประเทศ
จากนั้นส่งตัวกรองไปยังส่วนย่อยหรือ Intent ต้องส่งประเทศเป็น
แบบ 2 อักขระ รองรับ ISO 3166-1 Alpha-2 ประเทศ
รหัส
ตัวอย่างโค้ดต่อไปนี้แสดงการเรียกใช้ setCountries()
ใน
AutocompleteSupportFragment
เพื่อตั้งค่าตัวกรองที่แสดงเฉพาะผลลัพธ์ภายใน
ประเทศที่ระบุ
Kotlin
autocompleteFragment.setCountries("AU", "NZ")
Java
autocompleteFragment.setCountries("AU", "NZ");
ขีดจำกัดการใช้งาน
การใช้งาน Places API รวมถึง Places SDK สำหรับ Android ของคุณ ไม่จำกัดจำนวนคำขอสูงสุดต่อวัน (QPD) อีกต่อไป อย่างไรก็ตาม ยังคงมีการจำกัดการใช้งานดังต่อไปนี้
- ขีดจำกัดอัตราคือ 6,000 QPM (คำขอต่อนาที) ใช่เลย ซึ่งคำนวณเป็นผลรวมของคำขอจากฝั่งไคลเอ็นต์และฝั่งเซิร์ฟเวอร์ โดยใช้ข้อมูลรับรองของโปรเจ็กต์เดียวกัน
แสดงการระบุแหล่งที่มาในแอปของคุณ
- หากแอปใช้บริการเติมข้อความอัตโนมัติแบบเป็นโปรแกรม UI จะต้อง แสดงหน้าจอ "ขับเคลื่อนโดย Google" หรือปรากฏใน แผนที่ที่เป็นแบรนด์ Google
- หากแอปใช้วิดเจ็ตการเติมข้อความอัตโนมัติ คุณก็ไม่ต้องดำเนินการใดๆ เพิ่มเติม (การระบุแหล่งที่มาที่จำเป็นจะแสดงโดยค่าเริ่มต้น)
- หากคุณเรียกและแสดงข้อมูลสถานที่เพิ่มเติมหลังจากรับข้อมูล สถานที่โดย รหัส คุณ ต้องแสดงการระบุแหล่งที่มาของบุคคลที่สามด้วย
ดูรายละเอียดเพิ่มเติมได้ในเอกสาร การระบุแหล่งที่มา
การเพิ่มประสิทธิภาพการเติมข้อความอัตโนมัติในสถานที่
ส่วนนี้จะอธิบายแนวทางปฏิบัติแนะนำเพื่อช่วยให้คุณใช้ประโยชน์สูงสุดจาก วางบริการเติมข้อความอัตโนมัติ
หลักเกณฑ์ทั่วไปมีดังนี้
- วิธีที่รวดเร็วที่สุดในการพัฒนาอินเทอร์เฟซผู้ใช้ที่ใช้งานได้คือการใช้ วิดเจ็ตเติมข้อความอัตโนมัติของ Maps JavaScript API วิดเจ็ตเติมข้อความอัตโนมัติของ Places SDK สำหรับ Android หรือ Places SDK สำหรับ iOS การควบคุม UI การเติมข้อความอัตโนมัติ
- พัฒนาความเข้าใจเกี่ยวกับการเติมข้อความอัตโนมัติที่จำเป็นเกี่ยวกับสถานที่ ฟิลด์ข้อมูลตั้งแต่ต้น
- ฟิลด์การให้น้ำหนักสถานที่และการจำกัดตำแหน่งเป็นฟิลด์ที่ไม่บังคับแต่สามารถใส่ได้ จะมีผลอย่างมากต่อประสิทธิภาพการเติมข้อความอัตโนมัติ
- ใช้การจัดการข้อผิดพลาดเพื่อดูแลให้แอปมีประสิทธิภาพลดลง หาก API แสดงผลข้อผิดพลาด
- ตรวจสอบว่าแอปของคุณแฮนเดิลเมื่อไม่ได้เลือกและเสนอทางเลือกให้กับผู้ใช้ เพื่อดำเนินการต่อ
แนวทางปฏิบัติแนะนำในการเพิ่มประสิทธิภาพต้นทุน
การเพิ่มประสิทธิภาพต้นทุนขั้นพื้นฐาน
เพิ่มความคุ้มค่าในการใช้การเติมข้อความอัตโนมัติในสถานที่ ให้ใช้มาสก์ฟิลด์ในรายละเอียดสถานที่ และวิดเจ็ตเติมข้อความอัตโนมัติเพื่อแสดงผลเฉพาะ วางฟิลด์ข้อมูลที่ต้องการ
การเพิ่มประสิทธิภาพต้นทุนขั้นสูง
พิจารณาการใช้การเติมข้อความอัตโนมัติแบบเป็นโปรแกรมเพื่อเข้าถึงการกำหนดราคาตามคำขอ และขอผลลัพธ์ Geocoding API เกี่ยวกับสถานที่ที่เลือกแทนรายละเอียดสถานที่ ราคาต่อคําขอที่จับคู่กับ Geocoding API จะคุ้มค่ากว่าราคาแบบต่อเซสชัน (ตามเซสชัน) หากเป็นไปตามเงื่อนไขทั้ง 2 ข้อต่อไปนี้
- หากคุณต้องการเพียงละติจูด/ลองจิจูดหรือที่อยู่ของสถานที่ที่ผู้ใช้เลือกเท่านั้น Geocoding API จะส่งข้อมูลนี้ให้น้อยกว่าการโทรรายละเอียดสถานที่
- หากผู้ใช้เลือกการคาดคะเนการเติมข้อความอัตโนมัติภายในคำขอการคาดการณ์การเติมข้อความอัตโนมัติโดยเฉลี่ย 4 คำขอหรือน้อยกว่า การกำหนดราคาต่อคำขออาจคุ้มค่ากว่าการกำหนดราคาต่อเซสชัน
แอปพลิเคชันของคุณต้องการข้อมูลอื่นๆ นอกเหนือจากที่อยู่และละติจูด/ลองจิจูดของการคาดการณ์ที่เลือกไหม
ใช่ ต้องขอรายละเอียดเพิ่มเติม
ใช้การเติมข้อความอัตโนมัติเกี่ยวกับสถานที่ตามเซสชันพร้อมรายละเอียดสถานที่
เนื่องจากแอปพลิเคชันของคุณจำเป็นต้องมีรายละเอียดสถานที่ เช่น ชื่อสถานที่ สถานะธุรกิจ หรือเวลาทำการ การใช้การเติมข้อความอัตโนมัติในสถานที่ควรใช้โทเค็นเซสชัน (แบบเป็นโปรแกรมหรือมีอยู่ในวิดเจ็ต JavaScript, Android หรือ iOS) โดยมีค่าใช้จ่ายรวม $0.017 ต่อเซสชัน และ SKU ข้อมูลสถานที่ โดยขึ้นอยู่กับฟิลด์ข้อมูลสถานที่ที่คุณขอ
การใช้งานวิดเจ็ต
การจัดการเซสชันจะมาพร้อมกับวิดเจ็ต JavaScript, Android หรือ iOS โดยอัตโนมัติ ซึ่งจะรวมทั้งคำขอเติมข้อความอัตโนมัติและคำขอรายละเอียดสถานที่ในการคาดการณ์ที่เลือก อย่าลืมระบุพารามิเตอร์ fields
เพื่อให้แน่ใจว่าคุณขอเฉพาะ
วางฟิลด์ข้อมูลที่ต้องการ
การใช้งานแบบเป็นโปรแกรม
ใช้โทเค็นเซสชันกับคำขอเติมข้อความอัตโนมัติเกี่ยวกับสถานที่ เมื่อขอรายละเอียดสถานที่เกี่ยวกับการคาดการณ์ที่เลือก ให้ใส่พารามิเตอร์ต่อไปนี้
- รหัสสถานที่จากการตอบกลับการเติมข้อความอัตโนมัติเกี่ยวกับสถานที่
- โทเค็นเซสชันที่ใช้ในคำขอเติมข้อความอัตโนมัติเกี่ยวกับสถานที่
- พารามิเตอร์
fields
ที่ระบุ วางฟิลด์ข้อมูลที่ต้องการ
ไม่ ต้องใช้เฉพาะที่อยู่และตำแหน่งเท่านั้น
Geocoding API จะเป็นตัวเลือกที่ประหยัดต้นทุนได้ดีกว่ารายละเอียดสถานที่สำหรับแอปพลิเคชันของคุณ ทั้งนี้ขึ้นอยู่กับประสิทธิภาพการใช้งานการเติมข้อความอัตโนมัติใน Place ของคุณ ประสิทธิภาพการเติมข้อความอัตโนมัติของแอปพลิเคชันทุกตัวจะแตกต่างกันไปโดยขึ้นอยู่กับสิ่งที่ผู้ใช้ป้อน ตำแหน่งที่ใช้แอปพลิเคชัน และมีการใช้งานแนวทางปฏิบัติแนะนำสำหรับการเพิ่มประสิทธิภาพหรือไม่
ในการตอบคำถามต่อไปนี้ ให้วิเคราะห์ว่าผู้ใช้พิมพ์โดยเฉลี่ยกี่ตัว ก่อนที่จะเลือกการคาดคะเนการเติมข้อความอัตโนมัติในแอปพลิเคชันของคุณ
ผู้ใช้เลือกการคาดคะเนการเติมข้อความอัตโนมัติใน 4 คำขอโดยเฉลี่ยหรือไม่
ใช่
ใช้การเติมข้อความอัตโนมัติในสถานที่แบบเป็นโปรแกรมโดยไม่ต้องใช้โทเค็นเซสชันและเรียกใช้ Geocoding API ในการคาดการณ์สถานที่ที่เลือก
Geocoding API จะแสดงที่อยู่และพิกัดละติจูด/ลองจิจูดในราคา $0.005 ต่อคำขอ การส่งคำขอเติมข้อความอัตโนมัติเกี่ยวกับสถานที่ - ต่อคำขอ 4 รายการมีค่าใช้จ่าย $0.01132 ดังนั้นค่าใช้จ่ายทั้งหมดของคำขอ 4 รายการพร้อมการเรียก Geocoding API เกี่ยวกับการคาดการณ์สถานที่ที่เลือกจะเป็น $0.01632 ซึ่งต่ำกว่าราคาการเติมข้อความอัตโนมัติต่อเซสชันที่ $0.017 ต่อเซสชัน1
ลองใช้แนวทางปฏิบัติแนะนำด้านประสิทธิภาพเพื่อช่วยให้ผู้ใช้ได้รับการคาดการณ์ที่ต้องการโดยใช้อักขระน้อยลง
ไม่ได้
ใช้การเติมข้อความอัตโนมัติเกี่ยวกับสถานที่ตามเซสชันพร้อมรายละเอียดสถานที่
เนื่องจากจำนวนคำขอเฉลี่ยที่คุณคาดว่าจะสร้างก่อนที่ผู้ใช้จะเลือกการคาดการณ์การเติมข้อความอัตโนมัติเกินราคาต่อเซสชัน การใช้การเติมข้อความอัตโนมัติในสถานที่ควรใช้โทเค็นเซสชันสำหรับทั้งคำขอเติมข้อความอัตโนมัติและคำขอรายละเอียดสถานที่ที่เกี่ยวข้อง โดยมีค่าใช้จ่ายรวม $0.017 ต่อเซสชัน1
การใช้งานวิดเจ็ต
การจัดการเซสชันจะมาพร้อมกับวิดเจ็ต JavaScript, Android หรือ iOS โดยอัตโนมัติ ซึ่งจะรวมทั้งคำขอเติมข้อความอัตโนมัติและคำขอรายละเอียดสถานที่ในการคาดการณ์ที่เลือก ตรวจสอบว่าได้ระบุพารามิเตอร์ fields
แล้ว เพื่อให้แน่ใจว่าคุณขอเฉพาะช่องข้อมูลพื้นฐาน
การใช้งานแบบเป็นโปรแกรม
ใช้โทเค็นเซสชันกับคำขอเติมข้อความอัตโนมัติเกี่ยวกับสถานที่ เมื่อขอรายละเอียดสถานที่เกี่ยวกับการคาดการณ์ที่เลือก ให้ใส่พารามิเตอร์ต่อไปนี้
- รหัสสถานที่จากการตอบกลับการเติมข้อความอัตโนมัติเกี่ยวกับสถานที่
- โทเค็นเซสชันที่ใช้ในคำขอเติมข้อความอัตโนมัติเกี่ยวกับสถานที่
- พารามิเตอร์
fields
ที่ระบุช่องข้อมูลพื้นฐาน เช่น ที่อยู่และเรขาคณิต
พิจารณาชะลอคำขอเติมสถานที่อัตโนมัติ
คุณสามารถใช้กลยุทธ์ต่างๆ เช่น ชะลอคำขอเติมสถานที่อัตโนมัติ จนกว่าผู้ใช้จะพิมพ์อักขระ 3 หรือ 4 ตัวแรกเพื่อให้แอปพลิเคชันส่งคำขอน้อยลง ตัวอย่างเช่น การสร้างคำขอการเติมข้อความอัตโนมัติสำหรับแต่ละอักขระหลังจากที่ผู้ใช้พิมพ์อักขระตัวที่ 3 หมายความว่าหากผู้ใช้พิมพ์อักขระตัวที่ 3 ตัว จากนั้นจะเลือกการคาดคะเนที่คุณขอ Geocoding API 1 รายการ ค่าใช้จ่ายรวมจะเท่ากับ $0.01632 (4 * $0.00283 การเติมข้อความอัตโนมัติต่อคำขอ + $0.005)1
หากความล่าช้าของคำขออาจทำให้คำขอแบบเป็นโปรแกรมโดยเฉลี่ยต่ำกว่า 4 ครั้ง คุณสามารถทำตามคำแนะนำในการใช้งานการเติมข้อความอัตโนมัติเกี่ยวกับสถานที่ด้วย Geocoding API ที่มีประสิทธิภาพ โปรดทราบว่าคำขอล่าช้าอาจถูกมองว่าเป็นเวลาในการตอบสนองโดยผู้ใช้ที่อาจคาดว่าจะเห็นการคาดการณ์ทุกครั้งที่กดแป้นพิมพ์ใหม่
ลองใช้แนวทางปฏิบัติแนะนำด้านประสิทธิภาพเพื่อช่วยให้ผู้ใช้ได้รับการคาดการณ์ที่ต้องการโดยใช้อักขระน้อยลง
-
ค่าใช้จ่ายที่แสดงที่นี่เป็นสกุลเงิน USD โปรดดูหน้าการเรียกเก็บเงินของ Google Maps Platform สำหรับข้อมูลราคาทั้งหมด
แนวทางปฏิบัติแนะนำด้านประสิทธิภาพ
หลักเกณฑ์ต่อไปนี้อธิบายวิธีเพิ่มประสิทธิภาพการเติมข้อความอัตโนมัติในสถานที่
- เพิ่มข้อจำกัดประเทศ การให้น้ำหนักตำแหน่ง และ (สำหรับการติดตั้งแบบเป็นโปรแกรม) ค่ากำหนดภาษาเป็นการเติมข้อความอัตโนมัติในสถานที่ของคุณ การใช้งานของคุณ ไม่จำเป็นต้องตั้งค่าภาษา กับวิดเจ็ตเพราะจะเลือกค่ากำหนดภาษาจากเบราว์เซอร์หรืออุปกรณ์เคลื่อนที่ของผู้ใช้
- หากมีการเติมข้อมูลสถานที่อัตโนมัติปรากฏพร้อมกับแผนที่ คุณสามารถให้น้ำหนักกับตำแหน่งตามวิวพอร์ตของแผนที่ได้
- ในกรณีที่ผู้ใช้ไม่ได้เลือกการคาดคะเนการเติมข้อความอัตโนมัติใดๆ โดยปกติ
เนื่องจากการคาดคะเนเหล่านั้นไม่ใช่ที่อยู่ผลลัพธ์ที่ต้องการ คุณจึงสามารถใช้ที่อยู่เดิม
ข้อมูลจากผู้ใช้เพื่อพยายามให้ได้ผลการค้นหาที่เกี่ยวข้องมากขึ้น:
- ถ้าคุณคาดว่าผู้ใช้จะป้อนข้อมูลที่อยู่อย่างเดียว โปรดใช้ข้อมูลเดิมของผู้ใช้ซ้ำ ในการเรียกใช้ Geocoding API
- หากคุณคาดหวังให้ผู้ใช้ป้อนคำค้นหาสถานที่ใดสถานที่หนึ่งตามชื่อหรือที่อยู่ ให้ใช้คำขอค้นหาสถานที่ หากต้องการผลลัพธ์เฉพาะในภูมิภาคที่กำหนด ให้ใช้ การให้น้ำหนักตำแหน่ง
- ผู้ใช้ป้อนที่อยู่ย่อยในประเทศที่รองรับการเติมข้อความอัตโนมัติ ที่อยู่สถานที่ย่อยไม่สมบูรณ์ เช่น เช็กเกีย เอสโตเนีย และลิทัวเนีย ตัวอย่างเช่น พารามิเตอร์ ที่อยู่ภาษาเช็ก "Stroupeการสมัครnického 3191/17, Praha" ให้การคาดการณ์บางส่วนใน Place เติมข้อความอัตโนมัติ
- ผู้ใช้ป้อนที่อยู่โดยขึ้นต้นด้วยถนนส่วน เช่น "23-30 29th St, Queens" ใน นิวยอร์กซิตี้ หรือ "47-380 Kamehameha Hwy, Kaneohe" บนเกาะคาไวในฮาวาย
การแก้ปัญหา
แม้ว่าเกิดข้อผิดพลาดได้มากมาย แต่ข้อผิดพลาดส่วนใหญ่ของแอป มักเกิดจากข้อผิดพลาดในการกำหนดค่า (เช่น มีการใช้คีย์ API ที่ไม่ถูกต้อง หรือกำหนดค่าคีย์ API ไม่ถูกต้อง) หรือโควต้า (แอปของคุณเกินโควต้าแล้ว) ดูการใช้งาน ขีดจํากัดเพิ่มเติม เกี่ยวกับโควต้า
ข้อผิดพลาดที่เกิดขึ้นในการใช้การควบคุมการเติมข้อความอัตโนมัติจะส่งคืนใน
การติดต่อกลับของ onActivityResult()
โทรติดต่อ Autocomplete.getStatus()
เพื่อดูสถานะ
สำหรับผลลัพธ์