เติมข้อความอัตโนมัติ (ใหม่)

การเติมข้อความอัตโนมัติ (ใหม่) จะแสดงการคาดคะเนสถานที่ในการตอบกลับคำขอที่มีสตริงการค้นหาข้อความและขอบเขตทางภูมิศาสตร์ที่ควบคุมพื้นที่ค้นหา การเติมข้อความอัตโนมัติจะจับคู่ คำเต็มและสตริงย่อยของข้อมูลที่ป้อนได้ โดยจะแสดงชื่อสถานที่ ที่อยู่ และรหัสพลัส แอปพลิเคชันของคุณสามารถส่งการค้นหา ขณะที่ผู้ใช้พิมพ์ เพื่อแสดงการคาดคะเนสถานที่และการค้นหาแบบเรียลไทม์

ตัวอย่างเช่น คุณเรียกใช้การเติมข้อความอัตโนมัติโดยใช้สตริงที่มีข้อมูลที่ผู้ใช้ป้อนบางส่วน "Sicilian piz" เป็นอินพุต โดยจำกัดพื้นที่การค้นหาไว้ที่ซานฟรานซิสโก รัฐแคลิฟอร์เนีย จากนั้นการตอบกลับจะมีรายการการคาดคะเนสถานที่ ที่ตรงกับสตริงการค้นหาและพื้นที่ค้นหา เช่น ร้านอาหาร ชื่อ "Sicilian Pizza Kitchen" ระบบออกแบบการคาดคะเนสถานที่ที่แสดงเพื่อ นำเสนอต่อผู้ใช้เพื่อช่วยในการเลือกสถานที่ที่ต้องการ คุณสามารถส่งคำขอรายละเอียดสถานที่ (ใหม่) เพื่อรับข้อมูลเพิ่มเติม เกี่ยวกับคำทำนายสถานที่ที่แสดง

คุณสามารถผสานรวมฟังก์ชันการเติมข้อความอัตโนมัติ (ใหม่) เข้ากับแอปได้ 2 วิธีหลักๆ ดังนี้

• เพิ่มวิดเจ็ตการเติมข้อความอัตโนมัติของสถานที่: มอบประสบการณ์การเติมข้อความอัตโนมัติในการค้นหาที่พร้อมใช้งานผ่านคลาส PlaceAutocomplete ซึ่งแสดงการคาดคะเนขณะที่ผู้ใช้พิมพ์
• รับการคาดคะเนสถานที่โดยอัตโนมัติ: เรียกใช้ API โดยตรงเพื่อดึงข้อมูลการคาดคะเนและแสดงในอินเทอร์เฟซผู้ใช้ที่กำหนดเอง

เพิ่มวิดเจ็ต Place Autocomplete

คุณสามารถเพิ่มวิดเจ็ตการเติมข้อความอัตโนมัติของสถานที่ลงในแอปเพื่อให้ประสบการณ์การเติมข้อความอัตโนมัติของสถานที่สอดคล้องกันได้ง่ายขึ้น วิดเจ็ตนี้มีอินเทอร์เฟซแบบเต็มหน้าจอโดยเฉพาะซึ่งจะจัดการอินพุตของผู้ใช้และแสดงการคาดคะเนสถานที่ต่อผู้ใช้ พร้อมทั้งส่งออบเจ็กต์ AutocompletePrediction ไปยังแอป จากนั้นคุณสามารถส่งคำขอรายละเอียดสถานที่ (ใหม่) เพื่อรับข้อมูลเพิ่มเติมเกี่ยวกับการคาดคะเนสถานที่

เช่นเดียวกับเมื่อรับการคาดคะเนสถานที่โดยใช้โปรแกรม วิดเจ็ตการเติมข้อความอัตโนมัติของสถานที่ช่วยให้คุณใช้โทเค็นเซสชันเพื่อ จัดกลุ่มคำขอการเติมข้อความอัตโนมัติเป็นเซสชันเพื่อวัตถุประสงค์ในการเรียกเก็บเงินได้ คุณส่งโทเค็นเซสชันได้เมื่อสร้าง Intent สำหรับวิดเจ็ตโดยเรียกใช้ setAutocompleteSessionToken() หากไม่ได้ระบุโทเค็นเซสชัน วิดเจ็ตจะสร้างโทเค็นให้คุณ ซึ่งคุณจะเข้าถึงได้โดยการเรียกใช้ getSessionTokenFromIntent() ดูข้อมูลเพิ่มเติมเกี่ยวกับการใช้โทเค็นเซสชันได้ที่ เกี่ยวกับโทเค็น เซสชัน

วิธีเพิ่มวิดเจ็ตการเติมข้อความอัตโนมัติของสถานที่ลงในแอป

1. (ไม่บังคับ) กำหนดโทเค็นเซสชัน หากคุณไม่ได้ระบุโทเค็นเซสชัน วิดเจ็ตจะสร้างโทเค็นให้คุณ

2. กำหนด autocompleteIntent ด้วยพารามิเตอร์ที่ต้องการและโทเค็นเซสชัน

3. กำหนด ActivityResultLauncher สำหรับ StartActivityForResult ตัวเรียกใช้งานนี้จะจัดการผลลัพธ์ที่ได้จากกิจกรรมการเติมข้อความอัตโนมัติ

4. จัดการผลลัพธ์ในการเรียกกลับของ ActivityResultLauncher ซึ่งเกี่ยวข้องกับการ ดึงข้อมูล AutocompletePrediction และ AutocompleteSessionToken (หากคุณไม่ได้ระบุเอง) การจัดการข้อผิดพลาด และการส่งคำขอ fetchPlace() (ไม่บังคับ) เพื่อดูรายละเอียดเพิ่มเติมเกี่ยวกับสถานที่

5. เปิดใช้ Intent โดยใช้ placeAutocompleteActivityResultLauncher

ตัวอย่างต่อไปนี้แสดงวิธีเพิ่มวิดเจ็ตการเติมข้อความอัตโนมัติของสถานที่โดยใช้ทั้ง Kotlin และ Java

// Provide the API key that has enabled "Places API (New)" in the Google Cloud Console.
Places.initializeWithNewPlacesApiEnabled(/* Context= */ context, /* API Key= */ key)

// Optional, create a session token for Autocomplete request and the followup FetchPlace request.
val sessionToken: AutocompleteSessionToken = AutocompleteSessionToken.newInstance()

val autocompleteIntent: Intent =
    PlaceAutocomplete.createIntent(this) {
        // ... provide input params for origin, countries, types filter ...
        setAutocompleteSessionToken(sessionToken)
    }

val placeAutocompleteActivityResultLauncher: ActivityResultLauncher<Intent> =
    registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult ->
        val intent = result.data
        if (intent != null && result.resultCode == PlaceAutocompleteActivity.RESULT_OK) {
            // get prediction object
            val prediction: AutocompletePrediction? =
                PlaceAutocomplete.getPredictionFromIntent(intent!!)

            // get session token
            val sessionToken: AutocompleteSessionToken? =
                PlaceAutocomplete.getSessionTokenFromIntent(intent!!)

            // create PlacesClient to make FetchPlace request (optional)
            val placesClient: PlacesClient = Places.createClient(this)
            val response =
                placesClient.awaitFetchPlace(prediction.placeId, Field.DISPLAY_NAME)
                {
                    sessionToken = sessionToken // optional
                }
        }
    }

// Launch Activity
placeAutocompleteActivityResultLauncher.launch(autocompleteIntent)

// Provide the API key that has enabled "Places API (New)" in the Google Cloud Console.
Places.initializeWithNewPlacesApiEnabled(/* Context= */ context, /* API Key= */ key);

// Optional, create a session token for Autocomplete request and the followup FetchPlace request
AutocompleteSessionToken sessionToken = AutocompleteSessionToken.newInstance();

Intent autocompleteIntent =
    new PlaceAutocomplete.IntentBuilder()
        // ... set input params for origin, countries, types filter ...
        .setSessionToken(sessionToken) // optional
        .build(this);

ActivityResultLauncher<Intent> placeAutocompleteActivityResultLauncher =
    registerForActivityResult(
        new ActivityResultContracts.StartActivityForResult(),
        new ActivityResultCallback<ActivityResult>() {
            @Override
            public void onActivityResult(ActivityResult result) {
                Intent intent = result.getData();
                if (result.getResultCode() == PlaceAutocompleteActivity.RESULT_OK) {
                    // get prediction object
                    AutocompletePrediction prediction =
                        PlaceAutocomplete.getPredictionFromIntent(
                            Preconditions.checkNotNull(intent));

                    // get session token
                    AutocompleteSessionToken sessionToken =
                        PlaceAutocomplete.getSessionTokenFromIntent(
                            Preconditions.checkNotNull(intent));

                    // create PlacesClient to make FetchPlace request (optional)
                    PlacesClient placesClient = Places.createClient(this);
                    FetchPlaceRequest request =
                        FetchPlaceRequest.builder(prediction.getPlaceId(),
                            Arrays.asList(Field.DISPLAY_NAME))
                            .setSessionToken(sessionToken).build();
                    Task<FetchPlaceResponse> task = placesClient.fetchPlace(request);
                }
            }
        }
    );

// Launch Activity
placeAutocompleteActivityResultLauncher.launch(autocompleteIntent);

ปรับแต่งธีม

เมื่อสร้างอินสแตนซ์ของประสบการณ์การใช้งานการเติมข้อความอัตโนมัติ คุณจะระบุธีมที่ลบล้างแอตทริบิวต์สไตล์เริ่มต้นได้ คุณปรับแต่งสี การจัดตัวอักษร ระยะห่าง เส้นขอบ และมุมของคอมโพเนนต์การเติมข้อความอัตโนมัติของสถานที่ได้ ค่าเริ่มต้นคือ PlacesMaterialTheme แอตทริบิวต์ธีมที่ไม่ได้ลบล้างจะใช้ รูปแบบเริ่มต้น

คุณกำหนดการลบล้างธีมได้ใน …/res/values/themes.xml เช่น

<?xml version="1.0" encoding="utf-8"?>
<resources>
  <style name="BrandedTheme" parent="PlacesMaterialTheme">
    <!-- Color tokens. -->
    <item name="placesColorOnNeutralContainer">#5300e8</item>
    <item name="placesColorOnNeutralContainerVariant">#ee6002</item>
    ...

    <!-- Typography tokens. -->
    <item name="placesTextAppearanceTitleLarge">@style/PlacesTextAppearance</item>
    <item name="placesTextAppearanceBodyMedium">@style/PlacesTextAppearance</item>
    ...

    <!-- Spacing tokens. -->
    <item name="placesSpacingSmall">6dp</item>
    <item name="placesSpacingMedium">12dp</item>
    ...

    <!-- Attribution tokens. -->
    <item name="placesColorAttributionLightTheme">white</item>
    <item name="placesColorAttributionDarkTheme">black</item>
  </style>
</resources>

จากนั้นคุณสามารถอ้างอิงรูปแบบการลบล้างได้โดยการเรียกใช้ setAutocompleteUiCustomization

ActivityResultLauncher<Intent> placeAutocompleteActivityResultLauncher =
  registerForActivityResult(
    new ActivityResultContracts.StartActivityForResult(),
    new ActivityResultCallback<ActivityResult>() {
      @Override
      public void onActivityResult(ActivityResult result) {
        Intent intent = result.getData();
        if (intent != null) {
          AutocompletePrediction prediction =
            PlaceAutocomplete.getPredictionFromIntent(intent);
          AutocompleteSessionToken sessionToken =
            PlaceAutocomplete.getSessionTokenFromIntent(intent);
          Status status = PlaceAutocomplete.getResultStatusFromIntent(intent);
          ...
        }
      }
    }
  );

Intent placeAutocompleteIntent =
  new PlaceAutocomplete.IntentBuilder()
    .setInitialQuery("INSERT_QUERY_TEXT")
    .setOrigin(new LatLng(10.0, 10.0))
    ...

    .setAutocompleteUiCustomization(
      AutocompleteUiCustomization.builder()
        .listItemIcon(AutocompleteUiIcon.noIcon())
        .listDensity(AutocompleteListDensity.MULTI_LINE)
        .theme(R.style.BrandedTheme)
        .build())
  .build(this);

placeAutocompleteActivityResultLauncher.launch(placeAutocompleteIntent);

รับการคาดคะเนสถานที่แบบเป็นโปรแกรม

แอปของคุณจะรับรายการชื่อสถานที่และ/หรือที่อยู่ที่คาดการณ์ได้จาก Autocomplete API โดยการเรียก PlacesClient.findAutocompletePredictions() และส่งออบเจ็กต์ FindAutocompletePredictionsRequest ตัวอย่างด้านล่างแสดงการเรียกที่สมบูรณ์ไปยัง PlacesClient.findAutocompletePredictions()

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();
LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);
final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Sicilian piz")
            .setRegionCode("ES")
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

ตอบกลับโดยใช้การเติมข้อความอัตโนมัติ (ใหม่)

API จะแสดง FindAutocompletePredictionsResponse ใน Task FindAutocompletePredictionsResponse มีรายการออบเจ็กต์ AutocompletePrediction สูงสุด 5 รายการที่แสดงถึงสถานที่ที่คาดการณ์ รายการอาจว่างเปล่าหากไม่มีสถานที่ที่รู้จักซึ่งสอดคล้องกับคำค้นหาและเกณฑ์ตัวกรอง

สำหรับสถานที่ที่คาดการณ์แต่ละแห่ง คุณสามารถเรียกใช้เมธอดต่อไปนี้เพื่อดึงรายละเอียดสถานที่

• getFullText(CharacterStyle) แสดงข้อความทั้งหมดของคำอธิบายสถานที่ นี่คือข้อความหลักและข้อความรองรวมกัน ตัวอย่าง: "Eiffel Tower, Avenue Anatole France, Paris, France" นอกจากนี้ เมธอดนี้ยังช่วยให้คุณไฮไลต์ส่วนของ คำอธิบายที่ตรงกับการค้นหาด้วยสไตล์ที่คุณเลือกได้โดยใช้ CharacterStyle พารามิเตอร์ CharacterStyle จะใส่หรือไม่ใส่ก็ได้ ตั้งค่าเป็น null หากไม่ต้องการ ไฮไลต์
• getPrimaryText(CharacterStyle) แสดงผลข้อความหลักที่อธิบายสถานที่ โดยปกติจะเป็นชื่อของ สถานที่ ตัวอย่าง: "หอไอเฟล" และ "123 Pitt Street"
• getSecondaryText(CharacterStyle) แสดงผลข้อความเสริมของคำอธิบายสถานที่ ซึ่งจะมีประโยชน์ เช่น เป็นบรรทัดที่ 2 เมื่อแสดงการคาดคะเนการเติมข้อความอัตโนมัติ ตัวอย่างเช่น "Avenue Anatole France, Paris, France" และ "Sydney, New South Wales"
• getPlaceId() แสดงผลรหัสสถานที่ของสถานที่ที่คาดการณ์ รหัสสถานที่คือตัวระบุที่เป็นข้อความ ซึ่งระบุสถานที่แบบไม่ซ้ำกัน และคุณสามารถใช้เพื่อดึงข้อมูล ออบเจ็กต์ Place อีกครั้งในภายหลังได้ ดูข้อมูลเพิ่มเติมเกี่ยวกับรหัสสถานที่ใน การเติมข้อความอัตโนมัติได้ที่รายละเอียดสถานที่ (ใหม่) ดูข้อมูลทั่วไปเกี่ยวกับรหัสสถานที่ได้ที่ภาพรวมรหัสสถานที่
• getTypes() จะแสดงรายการประเภทสถานที่ที่เชื่อมโยงกับสถานที่นี้
• getDistanceMeters() แสดงระยะทางเป็นเส้นตรงในหน่วยเมตรระหว่างสถานที่นี้กับ ต้นทางที่ระบุในคำขอ

พารามิเตอร์ที่จำเป็น

• การค้นหา

  สตริงข้อความที่จะค้นหา ระบุคำและสตริงย่อยแบบเต็ม ชื่อสถานที่ ที่อยู่ และPlus Codes บริการเติมข้อความอัตโนมัติ (ใหม่) จะแสดงรายการที่ตรงกันตามสตริงนี้และจัดลำดับผลลัพธ์ตาม ความเกี่ยวข้องที่รับรู้

  หากต้องการตั้งค่าพารามิเตอร์การค้นหา ให้เรียกใช้เมธอด setQuery() เมื่อสร้างออบเจ็กต์ FindAutocompletePredictionsRequest

พารามิเตอร์ที่ไม่บังคับ

• ประเภทหลัก

  รายการค่าประเภทได้สูงสุด 5 ค่าจากประเภท ตาราง A หรือตาราง B ที่ใช้กรองสถานที่ที่แสดงในคำตอบ สถานที่ต้องตรงกับค่าประเภทหลักที่ระบุค่าใดค่าหนึ่งจึงจะรวมอยู่ในคำตอบได้

  สถานที่หนึ่งๆ จะมีประเภทหลักได้เพียงประเภทเดียวจากประเภทใน ตาราง A หรือตาราง B ที่เชื่อมโยง กับสถานที่นั้น เช่น ประเภทหลักอาจเป็น "mexican_restaurant" หรือ "steak_house"

  คำขอจะถูกปฏิเสธพร้อมข้อผิดพลาด INVALID_REQUEST ในกรณีต่อไปนี้

  • ระบุประเภทมากกว่า 5 ประเภท
  • ระบุประเภทที่ไม่รู้จัก

  หากต้องการตั้งค่าพารามิเตอร์ประเภทหลัก ให้เรียกใช้เมธอด setTypesFilter() เมื่อสร้างออบเจ็กต์ FindAutocompletePredictionsRequest

• ประเทศ

  รวมเฉพาะผลลัพธ์จากรายชื่อประเทศที่ระบุ ซึ่งระบุเป็นรายการที่มีค่า ccTLD ("โดเมนระดับบนสุด") แบบ 2 อักขระได้สูงสุด 15 รายการ หากไม่ระบุ ระบบจะไม่ใช้ข้อจำกัดใดๆ กับการตอบกลับ เช่น หากต้องการจำกัดภูมิภาคเป็นเยอรมนีและฝรั่งเศส ให้ทำดังนี้

  หากคุณระบุทั้ง locationRestriction และ includedRegionCodes ผลลัพธ์จะอยู่ในพื้นที่ที่การตั้งค่าทั้ง 2 รายการตัดกัน

  หากต้องการตั้งค่าพารามิเตอร์ประเทศ ให้เรียกใช้เมธอด setCountries() เมื่อสร้างออบเจ็กต์ FindAutocompletePredictionsRequest

• ออฟเซ็ตอินพุต

  ออฟเซ็ตอักขระ Unicode ที่เริ่มจาก 0 ซึ่งระบุตำแหน่งเคอร์เซอร์ในคำค้นหา ตำแหน่งเคอร์เซอร์อาจส่งผลต่อการคาดคะเนที่แสดง หากเว้นว่างไว้ ระบบจะใช้ความยาวของคำค้นหาเป็นค่าเริ่มต้น

  หากต้องการตั้งค่าพารามิเตอร์ออฟเซ็ตอินพุต ให้เรียกใช้เมธอด setInputOffset() เมื่อสร้างออบเจ็กต์ FindAutocompletePredictionsRequest

• อคติหรือข้อจำกัดด้านสถานที่

  คุณระบุการเอนเอียงตามสถานที่หรือการจำกัดสถานที่ได้ แต่จะระบุทั้ง 2 อย่างพร้อมกันไม่ได้เพื่อกำหนดพื้นที่ค้นหา การจำกัดตำแหน่งคือการระบุ ภูมิภาคที่ผลการค้นหาต้องอยู่ภายใน ส่วนการเอนเอียงตามตำแหน่งคือการระบุ ภูมิภาคที่ผลการค้นหาต้องอยู่ใกล้ ความแตกต่างที่สำคัญคือ เมื่อใช้การเอนเอียงตามสถานที่ตั้ง ระบบอาจยังแสดงผลลัพธ์ที่อยู่นอกภูมิภาคที่ระบุ

  • อคติทางภูมิศาสตร์

    ระบุพื้นที่ที่จะค้นหา ตำแหน่งนี้ใช้เป็นอคติ ไม่ใช่ข้อจำกัด ดังนั้นระบบอาจยังแสดงผลลัพธ์ นอกพื้นที่ที่ระบุ

    หากต้องการตั้งค่าพารามิเตอร์การเอนเอียงตามสถานที่ ให้เรียกใช้เมธอด setLocationBias() เมื่อสร้างออบเจ็กต์ FindAutocompletePredictionsRequest

  • การจำกัดสถานที่

    ระบุพื้นที่ที่จะค้นหา ระบบจะไม่แสดงผลลัพธ์ที่อยู่นอกพื้นที่ที่ระบุ

    หากต้องการตั้งค่าพารามิเตอร์การจํากัดสถานที่ตั้ง ให้เรียกใช้เมธอด setLocationRestriction() เมื่อสร้างออบเจ็กต์ FindAutocompletePredictionsRequest

  ระบุภูมิภาคที่มีอคติเกี่ยวกับสถานที่ตั้งหรือข้อจำกัดด้านสถานที่ตั้งเป็น วิวพอร์ตสี่เหลี่ยมผืนผ้าหรือเป็นวงกลม

  • วงกลมกำหนดโดยจุดศูนย์กลางและรัศมีเป็นเมตร รัศมีต้องอยู่ระหว่าง 0.0 ถึง 50000.0 (รวม) ค่าเริ่มต้นคือ 0.0 สำหรับข้อจำกัดด้านสถานที่ตั้ง คุณต้องตั้งค่ารัศมีเป็นค่าที่มากกว่า 0.0 ไม่เช่นนั้น คำขอจะไม่แสดงผลลัพธ์ใดๆ

  • สี่เหลี่ยมผืนผ้าคือวิวพอร์ตละติจูด-ลองจิจูด ซึ่งแสดงเป็นจุด 2 จุดที่อยู่ตรงข้ามกันตามแนวทแยง low และ high ระบบจะถือว่าวิวพอร์ตเป็น พื้นที่ปิด ซึ่งหมายความว่ารวมถึงขอบเขตของวิวพอร์ตด้วย ขอบเขตละติจูด ต้องอยู่ระหว่าง -90 ถึง 90 องศา และขอบเขตลองจิจูด ต้องอยู่ระหว่าง -180 ถึง 180 องศา

    • หาก low = high วิวพอร์ตจะประกอบด้วยจุดเดียว
    • หาก low.longitude > high.longitude ช่วงลองจิจูดจะกลับด้าน (วิวพอร์ตข้ามเส้นลองจิจูด 180 องศา)
    • หาก low.longitude = -180 องศา และ high.longitude = 180 องศา วิวพอร์ตจะรวมลองจิจูดทั้งหมด
    • หาก low.longitude = 180 องศาและ high.longitude = -180 องศา ช่วงลองจิจูดจะว่างเปล่า

    คุณต้องระบุทั้ง low และ high และช่องที่แสดงต้องไม่ว่าง โดยวิวพอร์ตที่ว่างเปล่าจะทำให้เกิดข้อผิดพลาด

• Origin

  จุดต้นทางที่จะใช้คำนวณระยะทางเป็นเส้นตรงไปยัง ปลายทาง (เข้าถึงได้โดยใช้ getDistanceMeters()) หากละเว้นค่านี้ ระบบจะไม่แสดงระยะทางเป็นเส้นตรง ต้องระบุเป็น พิกัดละติจูดและลองจิจูด:

  หากต้องการตั้งค่าพารามิเตอร์ต้นทาง ให้เรียกใช้เมธอด setOrigin() เมื่อสร้างออบเจ็กต์ FindAutocompletePredictionsRequest

• รหัสภูมิภาค

  รหัสภูมิภาคที่ใช้ในการจัดรูปแบบการตอบกลับ รวมถึงการจัดรูปแบบที่อยู่ ซึ่งระบุเป็นค่า 2 อักขระของ ccTLD ("โดเมนระดับบนสุด") รหัส ccTLD ส่วนใหญ่จะเหมือนกับรหัส ISO 3166-1 โดยมีข้อยกเว้นที่สำคัญบางประการ ตัวอย่างเช่น ccTLD ของสหราชอาณาจักรคือ "uk" (.co.uk) ขณะที่รหัส ISO 3166-1 คือ "gb" (ในทางเทคนิคสำหรับ นิติบุคคลของ "สหราชอาณาจักรบริเตนใหญ่และไอร์แลนด์เหนือ")

  หากคุณระบุรหัสภูมิภาคที่ไม่ถูกต้อง API จะแสดงข้อผิดพลาด INVALID_ARGUMENT พารามิเตอร์นี้อาจส่งผลต่อผลลัพธ์ตามกฎหมายที่เกี่ยวข้อง

  หากต้องการตั้งค่าพารามิเตอร์รหัสภูมิภาค ให้เรียกใช้เมธอด setRegionCode() เมื่อสร้างออบเจ็กต์ FindAutocompletePredictionsRequest

• โทเค็นของเซสชัน

  โทเค็นเซสชันคือสตริงที่ผู้ใช้สร้างขึ้นซึ่งติดตามการเรียกใช้การเติมข้อความอัตโนมัติ (ใหม่) ทั้งการเรียกใช้ผ่านวิดเจ็ตและการเรียกใช้แบบเป็นโปรแกรมเป็น "เซสชัน" การเติมข้อความอัตโนมัติใช้โทเค็นเซสชันเพื่อ จัดกลุ่มระยะการค้นหาและการเลือกของการค้นหาการเติมข้อความอัตโนมัติของผู้ใช้เป็นเซสชันที่ไม่ต่อเนื่องเพื่อ วัตถุประสงค์ในการเรียกเก็บเงิน เซสชันจะเริ่มต้นเมื่อ ผู้ใช้เริ่มพิมพ์คำค้นหา และสิ้นสุดเมื่อผู้ใช้เลือกสถานที่ แต่ละเซสชัน สามารถมีการค้นหาหลายครั้ง ตามด้วยการเลือกสถานที่ 1 แห่ง เมื่อเซสชันสิ้นสุดลง โทเค็นจะใช้ไม่ได้อีกต่อไป แอปของคุณต้องสร้างโทเค็นใหม่ สำหรับแต่ละเซสชัน เราขอแนะนำให้ใช้โทเค็นเซสชันสำหรับเซสชันการเติมข้อความอัตโนมัติแบบเป็นโปรแกรมทั้งหมด (เมื่อฝังส่วนย่อยหรือเปิดใช้การเติมข้อความอัตโนมัติโดยใช้ Intent API จะจัดการเรื่องนี้ให้โดยอัตโนมัติ)

  การเติมข้อความอัตโนมัติใช้ AutocompleteSessionToken เพื่อระบุแต่ละเซสชัน แอปควรส่งโทเค็นเซสชันใหม่เมื่อ เริ่มเซสชันใหม่แต่ละครั้ง จากนั้นส่งโทเค็นเดียวกันพร้อมกับรหัสสถานที่ใน การเรียกใช้ fetchPlace() ครั้งต่อๆ ไป เพื่อดึงรายละเอียดสถานที่สำหรับสถานที่ที่ผู้ใช้เลือก

  หากต้องการตั้งค่าพารามิเตอร์โทเค็นเซสชัน ให้เรียกใช้เมธอด setSessionToken() เมื่อสร้างออบเจ็กต์ FindAutocompletePredictionsRequest

  ดูข้อมูลเพิ่มเติมได้ที่ โทเค็นเซสชัน

ตัวอย่างการเติมข้อความอัตโนมัติ (ใหม่)

ใช้การจำกัดสถานที่และอคติทางภูมิศาสตร์

การเติมข้อความอัตโนมัติ (ใหม่) จะใช้การกำหนดค่า IP โดยค่าเริ่มต้นเพื่อ ควบคุมพื้นที่การค้นหา เมื่อใช้การปรับ IP API จะใช้ที่อยู่ IP ของ อุปกรณ์เพื่อปรับผลลัพธ์ คุณเลือกใช้ข้อจำกัดด้านสถานที่ตั้งหรือการเอนเอียงตามสถานที่ตั้งได้ แต่ใช้ทั้ง 2 อย่างพร้อมกันไม่ได้ เพื่อระบุพื้นที่ที่จะค้นหา

การจำกัดสถานที่ตั้งจะระบุพื้นที่ที่จะค้นหา ระบบจะไม่แสดงผลลัพธ์ที่อยู่นอกพื้นที่ที่ระบุ ตัวอย่างต่อไปนี้ใช้การจำกัดตำแหน่งเพื่อจำกัดคำขอให้เป็นการจำกัดตำแหน่งแบบวงกลมที่มีรัศมี 5,000 เมตรซึ่งอยู่ตรงกลางของซานฟรานซิสโก

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Amoeba")
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

เมื่อใช้การเอนเอียงตามสถานที่ตั้ง สถานที่ตั้งจะทำหน้าที่เป็นการเอนเอียง ซึ่งหมายความว่าระบบจะแสดงผลลัพธ์รอบๆ สถานที่ตั้งที่ระบุ รวมถึงผลลัพธ์นอกพื้นที่ที่ระบุ ตัวอย่างถัดไปจะเปลี่ยนคำขอก่อนหน้าให้ใช้การเอนเอียงตามตำแหน่ง

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Amoeba")
            .setLocationBias(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

ใช้ประเภทหลัก

ใช้พารามิเตอร์ประเภทหลักเพื่อจำกัดผลลัพธ์จากคำขอให้เป็นประเภทใดประเภทหนึ่งตามที่ระบุไว้ในตาราง กและตาราง ข คุณระบุอาร์เรย์ได้สูงสุด 5 ค่า หากไม่ระบุ ระบบจะแสดงผลทุกประเภท

ตัวอย่างต่อไปนี้ระบุสตริงการค้นหาเป็น "ฟุตบอล" และใช้พารามิเตอร์ประเภทหลัก เพื่อจำกัดผลลัพธ์ให้แสดงเฉพาะสถานประกอบการประเภท "sporting_goods_store"

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

final List<Place.Field> primaryTypes = Arrays.asList("sporting_goods_store");

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Soccer")
            .setIncludedPrimaryTypes(primaryTypes)
            .setLocationBias(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

หากคุณละเว้นพารามิเตอร์ประเภทหลัก ผลลัพธ์อาจรวมสถานประกอบการ ประเภทที่คุณอาจไม่ต้องการ เช่น "athletic_field"

ใช้ต้นทาง

เมื่อใส่พารามิเตอร์ต้นทางในคำขอ โดยระบุเป็น พิกัดละติจูดและลองจิจูด API จะรวมระยะทางเป็นเส้นตรง จากต้นทางไปยังปลายทางในการตอบกลับ (เข้าถึงได้โดยใช้ getDistanceMeters()) ตัวอย่างนี้ตั้งค่าต้นทางเป็นใจกลางซานฟรานซิสโก

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Amoeba")
            .setOrigin(center)
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

การเพิ่มประสิทธิภาพการเติมข้อความอัตโนมัติ (ใหม่)

ส่วนนี้อธิบายแนวทางปฏิบัติแนะนำที่จะช่วยให้คุณใช้ประโยชน์จากบริการ การเติมข้อความอัตโนมัติ (ใหม่) ได้อย่างเต็มที่

หลักเกณฑ์ทั่วไปมีดังนี้

• วิธีที่เร็วที่สุดในการพัฒนาอินเทอร์เฟซผู้ใช้ที่ใช้งานได้คือการใช้ วิดเจ็ต Autocomplete (ใหม่) ของ Maps JavaScript API วิดเจ็ต Autocomplete (ใหม่) ของ Places SDK สำหรับ Android หรือวิดเจ็ต Autocomplete (ใหม่) ของ Places SDK สำหรับ iOS
• ทำความเข้าใจฟิลด์ข้อมูลที่จำเป็น การเติมข้อความอัตโนมัติ (ใหม่) ตั้งแต่เริ่มต้น
• ฟิลด์การเอนเอียงตามสถานที่ตั้งและข้อจำกัดด้านสถานที่ตั้งเป็นฟิลด์ที่ไม่บังคับ แต่ก็อาจ ส่งผลต่อประสิทธิภาพการเติมข้อความอัตโนมัติอย่างมาก
• ใช้การจัดการข้อผิดพลาดเพื่อให้แน่ใจว่าแอปของคุณจะลดประสิทธิภาพลงอย่างราบรื่น หาก API แสดงข้อผิดพลาด
• ตรวจสอบว่าแอปของคุณจัดการเมื่อไม่มีการเลือกและเสนอวิธีให้ผู้ใช้ ดำเนินการต่อ

แนวทางปฏิบัติแนะนำในการเพิ่มประสิทธิภาพต้นทุน

การเพิ่มประสิทธิภาพต้นทุนขั้นพื้นฐาน

หากต้องการเพิ่มประสิทธิภาพค่าใช้จ่ายในการใช้บริการการเติมข้อความอัตโนมัติ (ใหม่) ให้ใช้มาสก์ฟิลด์ในรายละเอียดสถานที่ (ใหม่) และวิดเจ็ตการเติมข้อความอัตโนมัติ (ใหม่) เพื่อแสดงเฉพาะ ฟิลด์ข้อมูลการเติมข้อความอัตโนมัติ (ใหม่) ที่คุณต้องการ

การเพิ่มประสิทธิภาพต้นทุนขั้นสูง

โปรดพิจารณาการติดตั้งใช้งาน Autocomplete (ใหม่) แบบเป็นโปรแกรมเพื่อเข้าถึง SKU: ราคาคำขอ Autocomplete และขอผลลัพธ์ Geocoding API เกี่ยวกับสถานที่ที่เลือกแทนรายละเอียดสถานที่ (ใหม่) การกำหนดราคาต่อคำขอที่ใช้ร่วมกับ Geocoding API จะคุ้มค่ากว่าการกำหนดราคาต่อเซสชัน (อิงตามเซสชัน) หากเป็นไปตามเงื่อนไขต่อไปนี้ทั้ง 2 ข้อ

• หากต้องการเพียงละติจูด/ลองจิจูดหรือที่อยู่ของสถานที่ที่ผู้ใช้เลือก Geocoding API จะให้ข้อมูลนี้โดยใช้การเรียก Place Details (ใหม่) น้อยกว่า
• หากผู้ใช้เลือกการคาดคะเนการเติมข้อความอัตโนมัติภายในคำขอการคาดคะเนการเติมข้อความอัตโนมัติ (ใหม่) โดยเฉลี่ย 4 รายการหรือน้อยกว่านั้น การกำหนดราคาต่อคำขออาจคุ้มค่ากว่าการกำหนดราคาต่อเซสชัน

แอปพลิเคชันของคุณต้องใช้ข้อมูลอื่นนอกเหนือจากที่อยู่และละติจูด/ลองจิจูดของการคาดคะเนที่เลือกไหม

แนวทางปฏิบัติแนะนำด้านประสิทธิภาพ

หลักเกณฑ์ต่อไปนี้อธิบายวิธีเพิ่มประสิทธิภาพการเติมข้อความอัตโนมัติ (ใหม่)

• เพิ่มข้อจำกัดด้านประเทศ การกำหนดตำแหน่ง และ (สำหรับการติดตั้งใช้งานแบบเป็นโปรแกรม) ค่ากำหนดภาษาลงในการติดตั้งใช้งานการเติมข้อความอัตโนมัติ (ใหม่) ไม่จำเป็นต้องระบุค่ากำหนดภาษา ในวิดเจ็ต เนื่องจากวิดเจ็ตจะเลือกค่ากำหนดภาษาจากเบราว์เซอร์หรืออุปกรณ์เคลื่อนที่ของผู้ใช้
• หากการเติมข้อความอัตโนมัติ (ใหม่) มาพร้อมกับแผนที่ คุณสามารถกำหนดตำแหน่งตามวิวพอร์ตของแผนที่ได้
• ในกรณีที่ผู้ใช้ไม่ได้เลือกการคาดคะเนจากฟีเจอร์เติมข้อความอัตโนมัติ (ใหม่) โดยทั่วไป เนื่องจากไม่มีการคาดคะเนใดๆ ที่เป็นผลลัพธ์ที่ต้องการ คุณสามารถนำข้อมูลที่ผู้ใช้ป้อนไว้เดิมมาใช้ซ้ำเพื่อพยายามรับผลลัพธ์ที่เกี่ยวข้องมากขึ้นได้โดยทำดังนี้
  • หากคาดว่าผู้ใช้จะป้อนเฉพาะข้อมูลที่อยู่ ให้ใช้ข้อมูลที่ผู้ใช้ป้อนเดิมซ้ำ ในการเรียก Geocoding API
  • หากคาดว่าผู้ใช้จะป้อนคำค้นหาสำหรับสถานที่ที่เฉพาะเจาะจงตามชื่อหรือที่อยู่ ให้ใช้คำขอรายละเอียดสถานที่ (ใหม่) หากคาดหวังผลลัพธ์ในภูมิภาคที่เฉพาะเจาะจงเท่านั้น ให้ใช้การเอนเอียงตามตำแหน่ง
  สถานการณ์อื่นๆ ที่ควรใช้ Geocoding API เป็นข้อมูลสำรอง ได้แก่
  • ผู้ใช้ที่ป้อนที่อยู่ของสถานที่ย่อย เช่น ที่อยู่ของยูนิตหรืออพาร์ตเมนต์ที่เฉพาะเจาะจง ภายในอาคาร เช่น ที่อยู่ "Stroupežnického 3191/17, Praha" ในเช็ก จะให้การคาดคะเนบางส่วนในการเติมข้อความอัตโนมัติ (ใหม่)
  • ผู้ใช้ที่ป้อนที่อยู่ที่มีคำนำหน้าส่วนของถนน เช่น "23-30 29th St, Queens" ใน นิวยอร์กซิตี้ หรือ "47-380 Kamehameha Hwy, Kaneohe" บนเกาะคาไวในฮาวาย

การปรับตำแหน่ง

เอนเอียงผลลัพธ์ไปยังพื้นที่ที่ระบุโดยส่งพารามิเตอร์ location และพารามิเตอร์ radius ซึ่งจะสั่งให้การเติมข้อความอัตโนมัติ (ใหม่) เลือกแสดงผลการค้นหา ภายในพื้นที่ที่กำหนด ระบบอาจยังแสดงผลลัพธ์ที่อยู่นอกพื้นที่ที่กำหนด คุณใช้พารามิเตอร์ components เพื่อกรองผลลัพธ์ ให้แสดงเฉพาะสถานที่ภายในประเทศที่ระบุได้

การจำกัดตำแหน่ง

จำกัดผลลัพธ์ให้อยู่ในพื้นที่ที่ระบุโดยส่งพารามิเตอร์ locationRestriction

นอกจากนี้ คุณยังจำกัดผลลัพธ์ให้แสดงเฉพาะภูมิภาคที่กำหนดโดย location และพารามิเตอร์ radius ได้ด้วยโดยการเพิ่มพารามิเตอร์ locationRestriction ซึ่งจะสั่งให้การเติมข้อความอัตโนมัติ (ใหม่) แสดงผลลัพธ์เฉพาะ ภายในภูมิภาคนั้น