השלמה אוטומטית למקומות

שירות ההשלמה האוטומטית ב-Places SDK ל-Android מחזיר תחזיות של מקומות בתגובה לשאילתות החיפוש של המשתמשים. כשהמשתמש מקלידים, שירות ההשלמה האוטומטית מחזיר הצעות למקומות כמו עסקים, כתובות, קודי Plus ונקודות עניין.

אפשר להוסיף לאפליקציה השלמה אוטומטית בדרכים הבאות:

• מוסיפים ווידג'ט להשלמה אוטומטית כדי לחסוך זמן פיתוח ולהבטיח חוויית משתמש עקבית.
• קבלת תחזיות למקומות באופן פרוגרמטי כדי ליצור חוויית משתמש מותאמת אישית.

הוספת ווידג'ט להשלמה אוטומטית

הווידג'ט של ההשלמה האוטומטית הוא תיבת דו-שיח לחיפוש עם פונקציונליות של השלמה אוטומטית מובנית. כשהמשתמש מזין מונחי חיפוש, הווידג'ט מציג רשימה של מקומות צפויים לבחירה. כשהמשתמש מבצע בחירה, מוחזרת מופע של Place, שבעזרתו האפליקציה יכולה לקבל פרטים על המקום שנבחר.

יש שתי דרכים להוסיף את הווידג'ט של ההשלמה האוטומטית לאפליקציה:

• אפשרות 1: הטמעת AutocompleteSupportFragment.
• אפשרות 2: שימוש בכוונה (intent) כדי להפעיל את הפעילות של השלמה אוטומטית.

אפשרות 1: הטמעת AutocompleteSupportFragment

כדי להוסיף AutocompleteSupportFragment לאפליקציה:

1. מוסיפים קטע לפריסה של ה-XML בפעילות.
2. מוסיפים מאזין לפעילות או לקטע.

הוספת 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 מטפלת בהחזרת מקום בתגובה לבחירה של המשתמש. הקוד הבא מראה איך יוצרים הפניה לקטע הקוד ומוסיפים מאזין ל-AutocompleteSupportFragment:

    // 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")
        }
    })

      

    // 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) כדי להפעיל את הפעילות של ההשלמה האוטומטית

אם אתם רוצים שהאפליקציה תשתמש בתהליך ניווט אחר (לדוגמה, כדי להפעיל את חוויית ההשלמה האוטומטית מסמל ולא משדה חיפוש), האפליקציה יכולה להפעיל את ההשלמה האוטומטית באמצעות כוונה (intent).

כדי להפעיל את הווידג'ט של ההשלמה האוטומטית באמצעות כוונת שימוש (intent):

1. משתמשים ב-Autocomplete.IntentBuilder כדי ליצור כוונה, ומעבירים את המצב הרצוי של Autocomplete.
2. מגדירים מרכז הפעלה של תוצאת הפעילות registerForActivityResult שאפשר להשתמש בו כדי להפעיל את הכוונה ולטפל בתחזית המקום שנבחר על ידי המשתמש בתוצאה.

יצירת כוונת השלמה אוטומטית

בדוגמה הבאה נעשה שימוש ב-Autocomplete.IntentBuilder כדי ליצור כוונה להפעלת הווידג'ט של ההשלמה האוטומטית ככוונה:

    // 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)

      

    // 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);

      

כשמשתמשים בכוונה (intent) כדי להפעיל את הווידג'ט של ההשלמה האוטומטית, אפשר לבחור מבין מצבי התצוגה: שכבת-על או מסך מלא. צילומי המסך הבאים מציגים כל אחד ממצבי התצוגה בהתאמה:

רישום קריאה חוזרת לתוצאת הכוונה

כדי לקבל התראה כשהמשתמש בוחר מקום, מגדירים מרכז הפעלה registerForActivityResult() שמפעיל את הפעילות וגם מטפל בתוצאה, כפי שמתואר בדוגמה הבאה. אם המשתמש בחר תחזית, היא תישלח בכוונה שמכיל אובייקט התוצאה. מכיוון שהכוונה נוצרה על ידי Autocomplete.IntentBuilder, השיטה Autocomplete.getPlaceFromIntent() יכולה לחלץ ממנה את אובייקט המקום.

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")
        }
    }

      

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");
            }
        });

      

אחזור של תחזיות למיקומים באופן פרוגרמטי

אתם יכולים ליצור ממשק משתמש מותאם אישית לחיפוש, כחלופה לממשק המשתמש שסופק על ידי הווידג'ט של ההשלמה האוטומטית. כדי לעשות זאת, האפליקציה צריכה לקבל תחזיות של מיקומים באופן פרוגרמטי. כדי לקבל מה-API של המילוי האוטומטי רשימה של שמות מקומות או כתובות חזויות, אפשר לבצע קריאה ל-PlacesClient.findAutocompletePredictions() ולהעביר אובייקט FindAutocompletePredictionsRequest עם הפרמטרים הבאים:

• חובה: מחרוזת query שמכילה את הטקסט שהמשתמש הקליד.
• מומלץ: AutocompleteSessionToken, שמקבץ את שלבי השאילתה והבחירה בחיפוש של משתמש לסשן נפרד למטרות חיוב. הסשן מתחיל כשהמשתמש מתחיל להקליד שאילתה, ומסתיים כשהוא בוחר מקום.
• מומלץ: אובייקט RectangularBounds שמציין גבולות קו הרוחב ואורך הגלובוס כדי להגביל את התוצאות לאזור שצוין.
• אופציונלי: קוד מדינה אחד או יותר בן שתי אותיות (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().

    // 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}")
            }
        }

      

    // 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) מחזירה את הטקסט המלא של תיאור מקום. זהו שילוב של הטקסט הראשי והטקסט המשני. דוגמה: מגדל אייפל, שדרת Anatole France, Paris, France. בנוסף, השיטה הזו מאפשרת להדגיש את החלקים בתיאור שתואמים לחיפוש בסגנון שבוחרים, באמצעות CharacterStyle. הפרמטר CharacterStyle הוא אופציונלי. מגדירים אותו כ-null אם לא צריך הדגשה.
• הפונקציה getPrimaryText(CharacterStyle) מחזירה את הטקסט הראשי שמתאר מקום. בדרך כלל זהו שם המקום. דוגמאות: 'מגדל אייפל' ו'רחוב Pitt‏ 123'.
• הפונקציה getSecondaryText(CharacterStyle) מחזירה את הטקסט המשני של תיאור מקום. למשל, אפשר להשתמש בה כשורה שנייה כשמציגים תחזיות להשלמה אוטומטית. דוגמאות: Avenue Anatole France, Paris, France ו-Sydney, New South Wales.
• getPlaceId() מחזירה את מזהה המקום של המקום החזוי. מזהה מקום הוא מזהה טקסטואלי שמזהה מקום באופן ייחודי, וניתן להשתמש בו כדי לאחזר את האובייקט Place מאוחר יותר. מידע נוסף על מזהי מקומות ב-Places SDK ל-Android זמין במאמר פרטי המקום. למידע כללי על מזהי מקומות, ראו סקירה כללית על מזהי מקומות.
• הפונקציה getPlaceTypes() מחזירה את רשימת סוגי המקומות שמשויכים למקום הזה.
• getDistanceMeters() מחזירה את המרחק בקו ישר, במטרים, בין המקום הזה לבין המקור שצוין בבקשה.

אסימוני סשן

אסימוני סשן מקובצים לשלבים של השאילתה והבחירה בחיפוש של המשתמש להשלמה אוטומטית, ויוצרים סשן נפרד למטרות חיוב. הסשן מתחיל כשהמשתמש מתחיל להקליד שאילתה, ומסתיים כשהמשתמש בוחר מקום. כל סשן יכול לכלול כמה שאילתות, ולאחר מכן בחירת מקום אחת. בסיום הסשן, האסימון כבר לא תקף. האפליקציה צריכה ליצור אסימון חדש לכל סשן. מומלץ להשתמש באסימוני סשן לכל סשן של השלמה אוטומטית פרוגרמטית (כשמטמיעים קטע קוד או מפעילים השלמה אוטומטית באמצעות כוונה, ה-API מטפל בזה באופן אוטומטי).

ב-Places SDK ל-Android נעשה שימוש ב-AutocompleteSessionToken כדי לזהות כל סשן. האפליקציה צריכה להעביר אסימון סשן חדש בתחילת כל סשן חדש, ואז להעביר את אותו אסימון, יחד עם מזהה מקום, בקריאה הבאה ל-fetchPlace() כדי לאחזר את פרטי המקום של המקום שבחר המשתמש.

מידע נוסף על אסימוני סשן

הגבלת תוצאות ההשלמה האוטומטית

אפשר להגביל את תוצאות ההשלמה האוטומטית לאזור גיאוגרפי ספציפי, ו/או לסנן את התוצאות לסוג מקום אחד או יותר, או לעד חמש מדינות. אפשר להחיל את האילוצים האלה על הפעילות של ההשלמה האוטומטית, על AutocompleteSupportFragment ועל ממשקי ה-API של ההשלמה האוטומטית הפרוגרמטית.

כדי להגביל את התוצאות, מבצעים את הפעולות הבאות:

• כדי להעדיף תוצאות בתוך האזור המוגדר, צריך להפעיל את setLocationBias() (יכול להיות שעדיין יוחזרו תוצאות מחוץ לאזור המוגדר).
• כדי להציג רק תוצאות בתוך האזור המוגדר, צריך להפעיל את הפונקציה setLocationRestriction() (רק תוצאות בתוך האזור המוגדר יוחזרו).
• כדי להציג רק תוצאות שתואמות לסוג מקום מסוים, צריך להפעיל את השיטה setTypesFilter() (לדוגמה, ציון הערך TypeFilter.ADDRESS יחזיר רק תוצאות עם כתובת מדויקת).
• כדי להציג רק תוצאות מתוך עד חמש מדינות ספציפיות, צריך להפעיל את הפונקציה setCountries(). יש להעביר את המדינות כקוד מדינה בן שני תווים שתואמים לתקן ISO 3166-1 Alpha-2.

הטיה של התוצאות לאזור ספציפי

כדי להטות את תוצאות ההשלמה האוטומטית לאזור גיאוגרפי ספציפי, צריך להפעיל את הפונקציה setLocationBias() ולהעביר את הערך RectangularBounds. בדוגמת הקוד הבאה מוצגת קריאה ל-setLocationBias() במופע של קטע כדי להטות את ההצעות להשלמה אוטומטית לאזור בסידני, אוסטרליה.

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

      

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

      

הגבלת התוצאות לאזור ספציפי

כדי להגביל את תוצאות ההשלמה האוטומטית לאזור גיאוגרפי ספציפי, צריך להפעיל את הפונקציה setLocationRestriction() ולהעביר לה את הערך RectangularBounds. בדוגמה הבאה מוצגת קריאה ל-setLocationRestriction() במופע של קטע כדי להטות את ההצעות להשלמה אוטומטית לאזור בסידני, אוסטרליה.

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

      

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

      

הערה: ההגבלה הזו חלה רק על מסלולים שלמים. יכול להיות שתתקבלו תוצאות סינתטיות שנמצאות מחוץ לגבולות המלבניים על סמך מסלול שמצטלב עם הגבלת המיקום.

סינון התוצאות לפי סוגי מקומות או אוסף של סוגי מקומות

אתם יכולים להגביל את התוצאות של בקשת השלמה אוטומטית כך שיחזירו רק סוג מסוים של מקום. מציינים מסנן באמצעות סוגי המקומות או אוסף של סוגים שמפורטים בטבלאות 1, 2 ו-3 בקטע סוגי מקומות. אם לא מציינים כלום, המערכת מחזירה את כל הסוגים.

כדי לסנן את תוצאות המילוי האוטומטי, צריך להפעיל את המסנן באמצעות הפונקציה setTypesFilter().

כדי לציין מסנן של סוג או אוסף סוגים:

• קוראים לפונקציה setTypesFilter() ומציינים עד חמישה ערכים של type מהטבלה 1 והטבלה 2 שמופיעות בקטע סוגי מקומות. ערכי הסוגים מוגדרים על ידי הקבועים ב-PlaceTypes.

• קוראים ל-setTypesFilter() ומציינים אוסף סוגים מהטבלה 3 שמופיעה בקטע סוגי מקומות. ערכי האוסף מוגדרים על ידי הקבועים ב-PlaceTypes.

  מותר להשתמש רק בסוג אחד מטבלה 3 בבקשה. אם מציינים ערך מטבלה 3, אי אפשר לציין ערך מטבלה 1 או מטבלה 2. אם עושים זאת, מתרחשת שגיאה.

בדוגמה הבאה לקוד מוצגת קריאה ל-setTypesFilter() ב-AutocompleteSupportFragment, עם ציון של כמה ערכי טיפוס.

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

      

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

      

בדוגמת הקוד הבאה מוצגת קריאה ל-setTypesFilter() ב-AutocompleteSupportFragment כדי להגדיר מסנן שמחזיר רק תוצאות עם כתובת מדויקת, על ידי ציון אוסף סוגים.

    autocompleteFragment.setTypesFilter(listOf(PlaceTypes.ADDRESS))

      

    autocompleteFragment.setTypesFilter(Arrays.asList(PlaceTypes.ADDRESS, PlaceTypes.ESTABLISHMENT));

      

בדוגמת הקוד הבאה מוצגת קריאה ל-setTypesFilter() ב-IntentBuilder כדי להגדיר מסנן שמחזיר רק תוצאות עם כתובת מדויקת, על ידי ציון אוסף סוגים.

    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .setTypesFilter(listOf(PlaceTypes.ADDRESS))
        .build(this)

      

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

      

סינון התוצאות לפי מדינה

כדי לסנן את תוצאות המילוי האוטומטי לעד חמש מדינות, צריך להפעיל את הפונקציה setCountries() כדי להגדיר את קוד המדינה. לאחר מכן מעבירים את המסנן לקטע קוד או לכוונה. יש להעביר את המדינות כקוד מדינה בן שני תווים שתואמים לתקן ISO 3166-1 Alpha-2.

בדוגמת הקוד הבאה מוצגת קריאה ל-setCountries() ב-AutocompleteSupportFragment, כדי להגדיר מסנן שמחזיר רק תוצאות במדינות שצוינו.

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

      

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

      

מגבלות שימוש

השימוש שלכם ב-Places API, כולל Places SDK ל-Android, כבר לא מוגבל למספר מקסימלי של בקשות ליום (QPD). עם זאת, מגבלות השימוש הבאות עדיין רלוונטיות:

• מגבלת הקצב היא 6,000 בקשות לדקה (QPM). הוא מחושב כסכום של הבקשות בצד הלקוח ובצד השרת לכל האפליקציות שמשתמשות בפרטי הכניסה של אותו פרויקט.

הצגת שיוך באפליקציה

• אם האפליקציה שלכם משתמשת בשירות המילוי האוטומטי באופן פרוגרמטי, ממשק המשתמש צריך לכלול את השיוך 'מופעל על ידי Google' או להופיע במפה עם המותג של Google.
• אם האפליקציה שלכם משתמשת בווידג'ט של השלמה אוטומטית, אין צורך לבצע פעולה נוספת (שיוך הנתונים הנדרש מוצג כברירת מחדל).
• אם אתם מאחזרים ומציגים פרטים נוספים על מקום אחרי קבלת מקום לפי מזהה, עליכם להציג גם שיוך (Attribution) של צד שלישי.

פרטים נוספים זמינים במאמר בנושא שיוך.

אופטימיזציה של השלמה אוטומטית למקומות

בקטע הזה מתוארות שיטות מומלצות שיעזרו לכם להפיק את המקסימום מהשירות 'השלמה אוטומטית של מקומות'.

הנה כמה הנחיות כלליות:

• הדרך המהירה ביותר לפתח ממשק משתמש פעיל היא להשתמש בווידג'ט להשלמה אוטומטית של Maps JavaScript API, בווידג'ט להשלמה אוטומטית של Places SDK ל-Android או ברכיב הבקרה של ממשק המשתמש להשלמה אוטומטית של Places SDK ל-iOS.
• כבר מההתחלה, כדאי להבין את שדות הנתונים החיוניים של השלמה אוטומטית של מקומות.
• השדות של הטיית המיקום וההגבלה על המיקום הם אופציונליים, אבל הם יכולים להשפיע באופן משמעותי על הביצועים של ההשלמה האוטומטית.
• השתמשו בניהול שגיאות כדי לוודא שהאפליקציה תמשיך לפעול בצורה חלקה אם ה-API מחזיר שגיאה.
• חשוב לוודא שהאפליקציה מטפלת במקרים שבהם לא בוצעה בחירה ומציעה למשתמשים דרך להמשיך.

שיטות מומלצות לאופטימיזציה של עלויות

אופטימיזציה בסיסית של עלויות

כדי לבצע אופטימיזציה של העלות של השימוש בשירות השלמה אוטומטית של מקומות, כדאי להשתמש במסכות שדות בווידג'טים של פרטי מקומות ובווידג'טים של השלמה אוטומטית של מקומות כדי להחזיר רק את שדות נתוני המקומות הנחוצים לכם.

אופטימיזציה מתקדמת של עלויות

מומלץ להטמיע באופן פרוגרמטי את התכונה 'השלמה אוטומטית של מקומות' כדי לגשת לתמחור לפי בקשה ולבקש תוצאות של Geocoding API לגבי המקום שנבחר במקום פרטי המקום. תמחור לפי בקשה בשילוב עם Geocoding API משתלם יותר מתמחור לפי סשן (מבוסס-סשן) אם מתקיימים שני התנאים הבאים:

• אם אתם צריכים רק את קו הרוחב/האורך או את הכתובת של המקום שבחר המשתמש, Geocoding API מספק את המידע הזה בזמן קצר יותר מקריאה ל-Place Details.
• אם המשתמשים בוחרים חיזוי של השלמה אוטומטית תוך ארבע בקשות חיזוי של השלמה אוטומטית בממוצע או פחות, התמחור לפי בקשה עשוי להיות חסכוני יותר מהתמחור לפי סשן.

האם האפליקציה שלך דורשת מידע נוסף מלבד הכתובת והמיקום (קו הרוחב/האורך) של התחזית שנבחרה?

שיטות מומלצות לשיפור הביצועים

בהנחיות הבאות מפורטות דרכים לבצע אופטימיזציה של הביצועים של השלמה אוטומטית של מקומות:

• מוסיפים הגבלות על מדינות, הטיה לפי מיקום והעדפת שפה (בהטמעות פרוגרמטיות) להטמעה של השלמה אוטומטית של מקומות. לא צריך להגדיר העדפת שפה בווידג'טים, כי הם בוחרים את העדפות השפה מהדפדפן או מהמכשיר הנייד של המשתמש.
• אם השלמה אוטומטית של מקום מלווה במפה, אפשר להטות את המיקום לפי חלון התצוגה של המפה.
• במצבים שבהם משתמש לא בוחר באחת מההצעות של ההשלמה האוטומטית, בדרך כלל כי אף אחת מההצעות האלה לא היא כתובת התוצאה הרצויה, אפשר לעשות שימוש חוזר בקלט המקורי של המשתמש כדי לנסות לקבל תוצאות רלוונטיות יותר:
  • אם אתם מצפים שהמשתמש יזין רק פרטי כתובת, תוכלו לעשות שימוש חוזר בקלט המקורי של המשתמש בקריאה ל-Geocoding API.
  • אם אתם מצפים שהמשתמש יבצע שאילתות לחיפוש מקום ספציפי לפי שם או כתובת, תוכלו להשתמש בבקשה לחיפוש מקום. אם התוצאות צפויות רק באזור ספציפי, השתמשו בהטיה לפי מיקום.
  תרחישי מעבר אחרים ל-Geocoding API כוללים:
  • משתמשים שמזינים כתובות של נכסים משניים, כמו כתובות של יחידות או דירות ספציפיות בתוך בניין. לדוגמה, הכתובת בצ'כיה 'Stroupežnického 3191/17, Praha' מובילה לחיזוי חלקי בהשלמה האוטומטית של מקומות.
  • משתמשים שמזינים כתובות עם תחילית של מקטע כביש, כמו '23-30 29th St, Queens' בעיר ניו יורק או '47-380 Kamehameha Hwy, Kaneohe' באי קאואי בהוואי.

פתרון בעיות

יש מגוון רחב של שגיאות שיכולות להתרחש, אבל רוב השגיאות שעשויות להתרחש באפליקציה נובעות בדרך כלל משגיאות בהגדרה (לדוגמה, שימוש במפתח API שגוי או הגדרה שגויה של מפתח ה-API) או משגיאות שקשורות למכסות (האפליקציה חרגה מהמכסה שלה). מידע נוסף על מכסות זמין במאמר מגבלות שימוש.

שגיאות שמתרחשות במהלך השימוש באמצעי הבקרה של ההשלמה האוטומטית מוחזרות בקריאה החוזרת (callback) של onActivityResult(). כדי לקבל את הודעת הסטטוס של התוצאה, צריך להתקשר למספר Autocomplete.getStatus().