השלמה אוטומטית למקומות (דור קודם)

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

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

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

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

ווידג'ט ההשלמה האוטומטית הוא תיבת דו-שיח של חיפוש עם פונקציונליות מובנית של השלמה אוטומטית. כשהמשתמש מזין מונחי חיפוש, הווידג'ט מציג רשימה של מקומות חזויים לבחירה. כשהמשתמש בוחר מקום, מוחזר מופע של 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"
  />

• כברירת מחדל, למקטע אין גבול או רקע. כדי ליצור מראה חזותי עקבי, צריך להוסיף את ה-fragment בתוך רכיב פריסה אחר, כמו CardView.
• אם אתם משתמשים ב-Autocomplete fragment וצריכים לשנות את onActivityResult, אתם צריכים להפעיל את super.onActivityResult, אחרת ה-fragment לא יפעל כמו שצריך.

הוספת PlaceSelectionListener לפעילות

ה-PlaceSelectionListener מטפל בהחזרת מקום בתגובה לבחירת המשתמש. הקוד הבא מראה איך ליצור הפניה לקטע ולהוסיף מאזין ל-AutocompleteSupportFragment:

    // Build a BasicPlaceAutocomplete intent to allow the user to select a place.
    val basicAutocompleteIntent = BasicPlaceAutocomplete.createIntent(this) {
        setCountries(listOf("AU", "NZ"))
    }

      

    // 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, פועלים לפי השלבים הבאים:

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

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

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

    val intent = PlaceAutocomplete.createIntent(this) {
        setTypesFilter(listOf(PlaceTypes.ESTABLISHMENT))
    }

    startAutocomplete.launch(intent)

      

    // Start the autocomplete intent.
    Intent intent =
            new PlaceAutocomplete.IntentBuilder()
                    .setTypesFilter(List.of(PlaceTypes.ESTABLISHMENT))
                    .build(this);
    startAutocomplete.launch(intent);

      

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

רושמים קריאה חוזרת (callback) לתוצאת ה-intent.

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

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

      

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


      

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

אתם יכולים ליצור ממשק משתמש מותאם אישית לחיפוש, במקום להשתמש בממשק המשתמש של הווידג'ט להשלמה אוטומטית. כדי לעשות את זה, האפליקציה צריכה לקבל תחזיות לגבי מקומות באופן פרוגרמטי. כדי לקבל רשימה של שמות מקומות או כתובות חזויים מ-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.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)
            }
        }

      

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

טוקנים לסשנים

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

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

מידע נוסף על טוקנים לסשנים

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

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

כדי להגביל את התוצאות:

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

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

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

        intentBuilder.setLocationBias(bounds)

      

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

      

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

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

        intentBuilder.setLocationRestriction(bounds)

      

        intentBuilder.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 ומצוינים כמה ערכי סוגים.

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

      

    intentBuilder.setTypesFilter(List.of("landmark", "restaurant", "store"));

      

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

    intentBuilder.setTypesFilter(listOf(PlaceTypes.ADDRESS))

      

    intentBuilder.setTypesFilter(List.of(PlaceTypes.ESTABLISHMENT));

      

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

    val intent = PlaceAutocomplete.createIntent(this) {
        setTypesFilter(listOf(PlaceTypes.ESTABLISHMENT))
    }

      

    Intent intent =
            new PlaceAutocomplete.IntentBuilder()
                    .setTypesFilter(List.of(PlaceTypes.ESTABLISHMENT))
                    .build(this);

      

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

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

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

    intentBuilder.setCountries(listOf("AU", "NZ"))

      

    intentBuilder.setCountries(List.of("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 לגבי המקום שנבחר במקום Place Details (מדור קודם). תמחור לכל בקשה בשילוב עם Geocoding API משתלם יותר מתמחור לכל סשן (מבוסס-סשן) אם שני התנאים הבאים מתקיימים:

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

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

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

בהנחיות הבאות מוסבר איך לשפר את הביצועים של השלמה אוטומטית למקומות (דור קודם):

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

הטיית מיקום

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

הגבלת מיקום

כדי להגביל את התוצאות לאזור מסוים, צריך להעביר פרמטר locationRestriction.

אפשר גם להגביל את התוצאות לאזור שמוגדר על ידי location ופרמטר radius, על ידי הוספת הפרמטר strictbounds. ההגדרה הזו מנחה את ההשלמה האוטומטית למקומות (מדור קודם) להחזיר רק תוצאות באזור הזה.

פתרון בעיות

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

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