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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

פתרון בעיות

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

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