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

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

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

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

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

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

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

• אפשרות 1: הטמעה של AutocompleteSupportFragment.
• אפשרות 2: שימוש ב-Intent להפעלת פעילות ההשלמה האוטומטית.

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

כדי להוסיף AutocompleteSupportFragment לאפליקציה, פועלים לפי השלבים הבאים:

1. מוסיפים רכיב Fragment לפריסת ה-XML של הפעילות.
2. מוסיפים 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"
  />

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

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

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

    // Set up a PlaceSelectionListener to handle the response.
    autocompleteFragment.setOnPlaceSelectedListener(object : PlaceSelectionListener {
        override fun onPlaceSelected(place: Place) {
            binding.autocompleteResult.text = getString(
                R.string.place_selection,
                place.displayName,
                place.id,
                place.formattedAddress
            )
            Log.i(TAG, "Place: ${place.displayName}, ${place.id}")
        }

        override fun onError(status: Status) {
            binding.autocompleteResult.text = getString(R.string.an_error_occurred, status)
            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.
    assert autocompleteFragment != null;
    autocompleteFragment.setPlaceFields(Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME, Place.Field.FORMATTED_ADDRESS));

    // Set up a PlaceSelectionListener to handle the response.
    autocompleteFragment.setOnPlaceSelectedListener(new PlaceSelectionListener() {
        @Override
        public void onPlaceSelected(@NonNull Place place) {
            binding.autocompleteResult.setText(
                    getString(
                            R.string.place_selection,
                            place.getDisplayName(),
                            place.getId(),
                            place.getFormattedAddress()
                    )
            );
            Log.i(TAG, "Place: " + place.getDisplayName() + ", " + place.getId());
        }


        @Override
        public void onError(@NonNull Status status) {
            binding.autocompleteResult.setText(getString(R.string.an_error_occurred, status));
            Log.e(TAG, "An error occurred: " + status);
        }
    });

      

אפשרות 2: שימוש ב-Intent להפעלת פעילות ההשלמה האוטומטית

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

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

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

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

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

    // 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.DISPLAY_NAME, Place.Field.FORMATTED_ADDRESS)

    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .setTypesFilter(listOf(PlaceTypes.ESTABLISHMENT))
        .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.DISPLAY_NAME, Place.Field.FORMATTED_ADDRESS);

    // Start the autocomplete intent.
    Intent intent = new Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
            .setTypesFilter(List.of(PlaceTypes.ESTABLISHMENT))
            .build(this);
    startAutocomplete.launch(intent);

      

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

רישום התקשרות חזרה לתוצאת ה-intent

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

private val startAutocomplete =
    registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult ->
        if (result.resultCode == RESULT_OK) {
            val intent = result.data
            if (intent != null) {
                val place = Autocomplete.getPlaceFromIntent(intent)
                binding.autocompleteResult.text = getString(
                    R.string.place_selection,
                    place.displayName,
                    place.id,
                    place.formattedAddress)
                Log.i(
                    TAG, "Place: ${place.displayName}, ${place.id}"
                )
            }
        } 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")
        }
    }

      

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);
                    binding.autocompleteResult.setText(
                            getString(
                                    R.string.place_selection,
                                    place.getDisplayName(),
                                    place.getId(),
                                    place.getFormattedAddress()
                            )
                    );
                    Log.i(TAG, "Place: " + place.getDisplayName() + ", " + place.getId());
                }
            } 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");
            }
        });

      

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

אתם יכולים ליצור ממשק משתמש מותאם אישית לחיפוש כחלופה לממשק המשתמש שמסופק על ידי הווידג'ט של ההשלמה האוטומטית. כדי לעשות את זה, האפליקציה צריכה לקבל תחזיות לגבי מקומות באופן פרוגרמטי. האפליקציה יכולה לקבל רשימה של שמות מקומות או כתובות חזויים מ-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) מחזירה את הטקסט המלא של תיאור המקום. זהו שילוב של הטקסט הראשי והמשני. דוגמה: "Eiffel Tower, Avenue Anatole France, Paris, France". בנוסף, השיטה הזו מאפשרת להדגיש את החלקים בתיאור שתואמים לחיפוש בסגנון שתבחרו, באמצעות CharacterStyle. הפרמטר CharacterStyle הוא אופציונלי. אם לא רוצים להדגיש שום דבר, מגדירים את הערך null.
• ‫getPrimaryText(CharacterStyle) מחזירה את הטקסט העיקרי שמתאר מקום. בדרך כלל זה השם של המקום. דוגמאות: ‎"Eiffel Tower"‎ ו-‎ "123 Pitt Street"‎.
• ‫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() במופע של fragment כדי להטות את ההצעות להשלמה אוטומטית לאזור בסידני, אוסטרליה.

        autocompleteFragment.setLocationBias(bounds)

      

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

      

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

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

        autocompleteFragment.setLocationRestriction(bounds)

      

        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(List.of("landmark", "restaurant", "store"));

      

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

    autocompleteFragment.setTypesFilter(listOf(PlaceTypes.ADDRESS))

      

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

      

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

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

      

    Intent intent = new Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
            .setTypesFilter(List.of(PlaceTypes.ESTABLISHMENT))
            .build(this);

      

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

כדי לסנן את התוצאות של ההשלמה האוטומטית כך שיוצגו עד חמש מדינות, מתקשרים אל setCountries() כדי להגדיר את קוד המדינה. לאחר מכן, מעבירים את המסנן אל fragment או אל intent. המדינות צריכות להיות מועברות כקוד מדינה בן שני תווים שתואם לתקן 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.
• אם האפליקציה שלך משתמשת בווידג'ט ההשלמה האוטומטית, לא נדרשת פעולה נוספת (השיוך הנדרש מוצג כברירת מחדל).
• אם מאחזרים ומציגים מידע נוסף על מקום אחרי קבלת מקום לפי מזהה, צריך להציג גם שיוכים לצד שלישי.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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