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

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

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

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

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

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

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

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

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

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

1. צריך להוסיף מקטע לפריסת ה-XML של הפעילות.
2. הוספת האזנה לפעילות או למקטע.

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

כדי להוסיף את 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, צריך לבצע את השלבים הבאים:

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

יצירת Intent בהשלמה אוטומטית

בדוגמה הבאה נעשה שימוש ב-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);

      

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

הרשמה לקריאה חוזרת (callback) לתוצאת הכוונה

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

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

למידע נוסף, אפשר לקרוא את מאמרי העזרה בנושא שיוכים.

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

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

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

• הדרך המהירה ביותר לפתח ממשק משתמש פעיל היא להשתמש בווידג'ט להשלמה אוטומטית של 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" מניב חיזוי חלקי ב-Place השלמה אוטומטית.
  • משתמשים שמזינים כתובות עם קידומות של קטעי כביש כמו " 23-30 29th St, Queens" באזור New York City או "47-380 Kamehameha Hwy, Kaneohe" באי קאואי בהוואי.

פתרון בעיות

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

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