שירות ההשלמה האוטומטית ב-SDK של מקומות Google ל-Android מחזיר חיזויים של מקומות בתגובה לשאילתות חיפוש של משתמשים. תוך כדי הקלדה, שירות ההשלמה האוטומטית מציג הצעות למקומות כמו עסקים, כתובות, קודי OLC ונקודות עניין.
אפשר להוסיף לאפליקציה השלמה אוטומטית בדרכים הבאות:
- הוספת ווידג'ט של השלמה אוטומטית מאפשרת לחסוך זמן פיתוח ולהבטיח חוויית משתמש עקבית.
- קבלת חיזויים של מקומות באופן פרוגרמטי כדי ליצור חוויית משתמש בהתאמה אישית.
הוספת ווידג'ט של השלמה אוטומטית
ווידג'ט ההשלמה האוטומטית הוא תיבת דו-שיח של חיפוש עם פונקציונליות מובנית של השלמה אוטומטית. כשהמשתמש מזין מונחי חיפוש, הווידג'ט מציג רשימה של מקומות חזויים לבחירה. כשהמשתמש בוחר משהו, מוחזר פקודה Place שבה האפליקציה שלכם יכולה להשתמש כדי לקבל פרטים על המקום שנבחר.
יש שתי אפשרויות להוספת הווידג'ט של השלמה אוטומטית לאפליקציה:
- אפשרות 1: הטמעת
AutocompleteSupportFragment. - אפשרות 2: משתמשים ב-Intent כדי להפעיל את פעילות ההשלמה האוטומטית.
אפשרות 1: הטמעה של השלמה SupportFragment
כדי להוסיף AutocompleteSupportFragment לאפליקציה, יש לפעול לפי השלבים הבאים:
- הוספת מקטע לפריסת ה-XML של הפעילות שלך.
- מוסיפים מאזינים לפעילות או למקטע שלכם.
הוספת 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 שלכם:
Java
// 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);
}
});
Kotlin
// 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")
}
})
אפשרות 2: שימוש ב-Intent כדי להפעיל את פעילות ההשלמה האוטומטית
אם אתם רוצים שהאפליקציה תשתמש בתהליך ניווט אחר (לדוגמה, כדי להפעיל את חוויית ההשלמה האוטומטית מסמל במקום משדה חיפוש), האפליקציה יכולה להפעיל את ההשלמה האוטומטית על ידי שימוש בכוונה.
כדי להפעיל את הווידג'ט של השלמה אוטומטית באמצעות כוונת רכישה, פועלים לפי השלבים הבאים:
- משתמשים ב-
Autocomplete.IntentBuilderכדי ליצור כוונה ולעבור למצבAutocompleteהרצוי. הכוונה היא לקרוא לפונקציהstartActivityForResultולהעביר קוד בקשה לזיהוי הכוונה. - יש לבטל את הקריאה החוזרת (callback) של
onActivityResultכדי לקבל את המקום שנבחר.
יצירת כוונה להשלמה אוטומטית
הדוגמה הבאה ממחישה באמצעות Autocomplete.IntentBuilder כדי ליצור כוונה להפעלת ווידג'ט ההשלמה האוטומטית:
Java
private static int AUTOCOMPLETE_REQUEST_CODE = 1;
// 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);
startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE);
Kotlin
private val AUTOCOMPLETE_REQUEST_CODE = 1
// 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)
startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE)
אם אתם מתכוונים להפעיל את הווידג'ט של ההשלמה האוטומטית, תוכלו לבחור מבין מצבי הצגה במסך מלא או במצב מסך מלא. צילומי המסך הבאים מציגים כל מצב תצוגה, בהתאמה:
ביטול הקריאה החוזרת (callback) של onActivityResult
כדי לקבל התראה כשהמשתמש בוחר מקום, האפליקציה צריכה לבטל את onActivityResult() של הפעילות ולחפש את קוד הבקשה שהעברתם בהתאם לכוונה, כפי שמתואר בדוגמה הבאה.
Java
@Override
protected void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) {
if (requestCode == AUTOCOMPLETE_REQUEST_CODE) {
if (resultCode == RESULT_OK) {
Place place = Autocomplete.getPlaceFromIntent(data);
Log.i(TAG, "Place: " + place.getName() + ", " + place.getId());
} else if (resultCode == AutocompleteActivity.RESULT_ERROR) {
// TODO: Handle the error.
Status status = Autocomplete.getStatusFromIntent(data);
Log.i(TAG, status.getStatusMessage());
} else if (resultCode == RESULT_CANCELED) {
// The user canceled the operation.
}
return;
}
super.onActivityResult(requestCode, resultCode, data);
}
Kotlin
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
if (requestCode == AUTOCOMPLETE_REQUEST_CODE) {
when (resultCode) {
Activity.RESULT_OK -> {
data?.let {
val place = Autocomplete.getPlaceFromIntent(data)
Log.i(TAG, "Place: ${place.name}, ${place.id}")
}
}
AutocompleteActivity.RESULT_ERROR -> {
// TODO: Handle the error.
data?.let {
val status = Autocomplete.getStatusFromIntent(data)
Log.i(TAG, status.statusMessage ?: "")
}
}
Activity.RESULT_CANCELED -> {
// The user canceled the operation.
}
}
return
}
super.onActivityResult(requestCode, resultCode, data)
}
קבלת תחזיות לגבי מקומות באופן פרוגרמטי
תוכלו ליצור ממשק משתמש לחיפוש מותאם אישית במקום בממשק המשתמש שווידג'ט ההשלמה האוטומטית מספק. לשם כך, האפליקציה שלכם חייבת לקבל תחזיות מקומות באופן פרוגרמטי. האפליקציה שלכם יכולה לקבל רשימה של שמות מקומות חזויים ו/או כתובות מ-API להשלמה אוטומטית. לשם כך, יש להתקשר למספר PlacesClient.findAutocompletePredictions() ולעבור על אובייקט FindAutocompletePredictionsRequest עם הפרמטרים הבאים:
- חובה: מחרוזת
queryשמכילה את הטקסט שהמשתמש מקליד. - מומלץ:
AutocompleteSessionToken, שמקבץ את שלבי השאילתה והבחירה של חיפוש המשתמש בסשן נפרד, למטרות חיוב. הסשן מתחיל כשהמשתמש מתחיל להקליד שאילתה, ומסתיים כשהוא בוחר מקום. - מומלץ: אובייקט
RectangularBoundsשמציין את גבולות קווי האורך והרוחב כדי להגביל את התוצאות לאזור שצוין. - אופציונלי: קוד מדינה אחד או יותר (ISO 3166-1 Alpha-2), שמציין את המדינה או המדינות שבהן יש להגביל את התוצאות.
אופציונלי:
TypeFilter, שבאמצעותו ניתן להגביל את התוצאות לסוג המקום שצוין. הסוגים הבאים של מקומות נתמכים:TypeFilter.GEOCODE– מחזיר רק תוצאות של קידוד גיאוגרפי, ולא תוצאות של עסקים. השתמשו בבקשה הזו כדי להבהיר תוצאות שבהן המיקום שצוין לא קבוע.TypeFilter.ADDRESS– הפונקציה מחזירה רק תוצאות של השלמה אוטומטית עם כתובת מדויקת. השתמשו בסוג הזה כשאתם יודעים שהמשתמש מחפש כתובת שצוינה באופן מלא.TypeFilter.ESTABLISHMENT– מחזיר רק מקומות שהם עסקים.TypeFilter.REGIONS– מחזיר רק מקומות שתואמים לאחד מהסוגים הבאים:LOCALITYSUBLOCALITYPOSTAL_CODECOUNTRYADMINISTRATIVE_AREA_LEVEL_1ADMINISTRATIVE_AREA_LEVEL_2
TypeFilter.CITIES– מחזירה רק תוצאות שתואמות ל-LOCALITYאוADMINISTRATIVE_AREA_LEVEL_3.
אופציונלי:
LatLngשמציין את מיקום המקור של הבקשה. כשמתקשרים ל-setOrigin(), השירות מחזיר את המרחק במטרים (distanceMeters) מהמקור שצוין עבור כל חיזוי להשלמה אוטומטית בתגובה.
למידע על סוגי מקומות, אפשר לעיין במדריך לסוגי מקומות.
בדוגמה הבאה מוצגת שיחה מלאה אל PlacesClient.findAutocompletePredictions().
Java
// 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(TypeFilter.ADDRESS.toString()))
.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());
}
});
Kotlin
// 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(TypeFilter.ADDRESS.toString()))
.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)
}
}
ה-API מחזיר FindAutocompletePredictionsResponse ב-
Task. רשימת ה-FindAutocompletePredictionsResponse כוללת רשימה של אובייקטים AutocompletePrediction שמייצגים מקומות חזויים. יכול להיות שהרשימה ריקה, אם אין מקום ידוע שתואם לשאילתה ולקריטריונים לסינון.
בכל מקום חזוי, תוכלו לקרוא לשיטות הבאות כדי לאחזר את פרטי המקום:
getFullText(CharacterStyle)מחזיר את הטקסט המלא של תיאור המקום. זה שילוב של הטקסט הראשי והמשני. דוגמה: 'מגדל אייפל, שדרות אנטול צרפת, פריז, צרפת'. בנוסף, השיטה הזו מאפשרת לכם להבליט את קטעי התיאור שתואמים לחיפוש עם סגנון שבחרתם, באמצעותCharacterStyle. הפרמטרCharacterStyleהוא אופציונלי. אפשר להגדיר אותו לערך null אם לא צריך להוסיף הדגשה.getPrimaryText(CharacterStyle)מחזיר את הטקסט הראשי שמתאר מקום כלשהו. בדרך כלל זהו שם המקום. דוגמאות: 'מגדל אייפל' ו'רחוב פיט 123'.getSecondaryText(CharacterStyle)מחזיר את הטקסט של החברה הבת של תיאור מקום. פעולה זו שימושית, לדוגמה, בתור שורה שנייה להצגת חיזויים של השלמה אוטומטית. לדוגמה: "Avenue Anatole France, פריז, צרפת" ו-"Sydney, New South Wales".getPlaceId()המערכת מחזירה את מזהה המקום של המקום החזוי. מזהה מקום הוא מזהה טקסט שמזהה מקום באופן ייחודי, ואפשר להשתמש בו כדי לאחזר את האובייקטPlaceשוב מאוחר יותר. למידע נוסף על מזהי מקומות ב-SDK של מקומות ל-Android, ראו פרטי מקום. למידע כללי על מזהי מקומות, קראו את הסקירה הכללית על מזהי מקומות.getPlaceTypes()מחזירה את רשימת סוגי המקומות שמשויכים למקום הזה.getDistanceMeters()הצגת המרחק בקו ישר במטרים בין המקום הזה למקור שצוין בבקשה.
אסימוני סשנים
אסימוני סשנים מקבצים את השלבים של השאילתות והבחירה של השלמה אוטומטית של משתמשים בסשן נפרד למטרות חיוב. הסשן מתחיל כשהמשתמש מתחיל להקליד שאילתה, ומסתיים כשהוא בוחר מקום. כל סשן יכול לכלול כמה שאילתות, ואחריהן מקום אחד לבחירה. אחרי סיום הסשן, האסימון כבר לא תקף. האפליקציה צריכה ליצור אסימון חדש לכל סשן. מומלץ להשתמש באסימוני סשנים בכל הסשנים הפרוגרמטיים של ההשלמה האוטומטית (כשמטמיעים קטע, או מפעילים השלמה אוטומטית באמצעות Intent, ה-API מטפל בזה באופן אוטומטי).
ה-SDK של מקומות ל-Android משתמש ב-AutocompleteSessionToken כדי לזהות כל הפעלה. האפליקציה שלכם צריכה להעביר אסימון הפעלה חדש בתחילת כל סשן חדש, ואז להעביר את אותו אסימון ביחד עם מזהה מקום, בקריאה הבאה ל-fetchPlace(), כדי לאחזר את פרטי המקום שנבחר על ידי המשתמש.
הגבלת תוצאות ההשלמה האוטומטית
ניתן להגביל את התוצאות של ההשלמה האוטומטית לאזור גיאוגרפי ספציפי, ו/או לסנן את התוצאות לסוג אחד או יותר של מקומות, או לחמש מדינות לכל היותר.
ניתן להחיל את האילוצים האלה על פעילות ההשלמה האוטומטית, על AutocompleteSupportFragment ועל ממשקי API של השלמה אוטומטית פרוגרמטית.
כדי להגביל את התוצאות, יש לבצע את הפעולות הבאות:
- כדי להעדיף תוצאות בתוך האזור המוגדר, מתקשרים אל
setLocationBias()(יכול להיות שחלק מהתוצאות לא יהיו כלולות באזור שהוגדר). - כדי להציג רק תוצאות בתוך האזור המוגדר, מתקשרים אל
setLocationRestriction()(יוחזרו רק תוצאות בתוך האזור המוגדר). - כדי להחזיר רק תוצאות שתואמות לסוג מקום ספציפי, צריך לקרוא לפונקציה
setTypesFilter()(למשל, ציון המאפייןTypeFilter.ADDRESSיחזיר רק תוצאות עם כתובת מדויקת). - כדי להחזיר תוצאות רק בחמש מדינות לכל היותר, יש להתקשר למספר
setCountries(). יש להעביר את המדינות כקוד מדינה תואם בתקן ISO 3166-1 Alpha-2.
הטיית התוצאות לאזור מסוים
כדי להטות את ההשלמה האוטומטית של תוצאות באזור גיאוגרפי ספציפי, צריך להתקשר אל setLocationBias() ולעבור את השאילתה RectangularBounds.
בדוגמה הבאה של הקוד מוצגת קריאה ל-setLocationBias() במכונה עם מקטעים, כדי להטות את ההצעות של ההשלמה האוטומטית באזור של סידני שבאוסטרליה.
Java
autocompleteFragment.setLocationBias(RectangularBounds.newInstance(
new LatLng(-33.880490, 151.184363),
new LatLng(-33.858754, 151.229596)));
Kotlin
autocompleteFragment.setLocationBias(
RectangularBounds.newInstance(
LatLng(-33.880490, 151.184363),
LatLng(-33.858754, 151.229596)
)
)
הגבלת התוצאות לאזור מסוים
כדי להגביל את ההשלמה האוטומטית של תוצאות באזור גיאוגרפי מסוים, יש להתקשר למספר setLocationRestriction() ולעבור את השאילתה RectangularBounds.
בדוגמה הבאה של הקוד מוצגת קריאה ל-setLocationRestriction() במופע של קטע, כדי להטות את ההצעות של ההשלמה האוטומטית באזור של סידני באוסטרליה.
Java
autocompleteFragment.setLocationRestriction(RectangularBounds.newInstance(
new LatLng(-33.880490, 151.184363),
new LatLng(-33.858754, 151.229596)));
Kotlin
autocompleteFragment.setLocationRestriction(
RectangularBounds.newInstance(
LatLng(-33.880490, 151.184363),
LatLng(-33.858754, 151.229596)
)
)
הערה: ההגבלה הזו חלה רק על מסלולים שלמים. אם בוחרים להציג תוצאות סינתטיות שנמצאות מחוץ לגבולות המלבניים, המסלול חופף להגבלת המיקום.
סינון התוצאות לפי סוגי מקומות או איסוף סוגים
ניתן להגביל את התוצאות מבקשה להשלמה אוטומטית, כך שהן יחזירו רק סוג מסוים של מקום. אפשר לציין מסנן באמצעות סוגי מקומות או אוסף סוגים שמופיעים בטבלאות 1, 2 ו-3 בסוגי מקומות. אם לא מציינים שום דבר, מחזירים את כל הסוגים.
כדי לסנן את תוצאות ההשלמה האוטומטית, צריך להתקשר אל setTypesFilter() כדי להגדיר את המסנן.
כדי לציין מסנן סוג או סוג אוסף:
אפשר להתקשר אל
setTypesFilter()ולציין עד חמישה ערכי type מטבלה 1 וטבלה 2 שמוצגים בסוגי מקומות. ערכי הסוגים מוגדרים על ידי הקבועים ב-PlaceTypes.אפשר להתקשר אל
setTypesFilter()ולציין סוג אוסף בטבלה 3 שמוצג בסוגי מקומות. ערכי האוסף מוגדרים על ידי הקבועים ב-PlaceTypes.הבקשה יכולה לכלול רק סוג אחד מטבלה 3. אם מציינים ערך מטבלה 3, אי אפשר לציין ערך מטבלה 1 או מטבלה 2. אם תעשו זאת, תופיע שגיאה.
הדוגמה הבאה של הקוד מתקשרת אל setTypesFilter() ב-AutocompleteSupportFragment ומציינת ערכים לסוגים שונים.
Java
autocompleteFragment.setTypesFilter(Arrays.asList("landmark", "restaurant", "store"));
Kotlin
autocompleteFragment.setTypesFilter(listOf("landmark", "restaurant", "store"))
בדוגמה הבאה של הקוד מוצגת קריאה לפונקציה setTypesFilter() ב-AutocompleteSupportFragment כדי להגדיר מסנן שיחזיר תוצאות עם כתובת מדויקת בלבד, על ידי ציון אוסף סוגים.
Java
autocompleteFragment.setTypesFilter(Arrays.asList(TypeFilter.ADDRESS.toString()));
Kotlin
autocompleteFragment.setTypesFilter(listOf(TypeFilter.ADDRESS.toString()))
בדוגמה הבאה של הקוד מוצג חיוג אל setTypesFilter() ב-IntentBuilder כדי להגדיר מסנן שיחזיר תוצאות עם כתובת מדויקת בלבד, על ידי ציון אוסף סוגים.
Java
Intent intent = new Autocomplete.IntentBuilder(
AutocompleteActivityMode.FULLSCREEN, fields)
.setTypesFilter(Arrays.asList(TypeFilter.ADDRESS.toString()))
.build(this);
startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE);
Kotlin
val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
.setTypesFilter(listOf(TypeFilter.ADDRESS.toString()))
.build(this)
startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE)
סינון התוצאות לפי מדינה
כדי לסנן את תוצאות ההשלמה האוטומטית לעד חמש מדינות, צריך להתקשר למספר setCountries() כדי להגדיר את קוד המדינה.
לאחר מכן, מעבירים את המסנן למקטע או לכוונה. צריך להעביר את המדינות כקוד מדינה תואם בתקן ISO 3166-1 Alpha-2.
בדוגמה הבאה של הקוד מוצג חיוג אל setCountries() ב-AutocompleteSupportFragment, כדי להגדיר מסנן עם תוצאות רק במדינות שצוינו.
Java
autocompleteFragment.setCountries("AU", "NZ");
Kotlin
autocompleteFragment.setCountries("AU", "NZ")
מגבלות שימוש
השימוש שלכם ב-API של 'מקומות', כולל ה-SDK של מקומות ל-Android, כבר לא מוגבל למספר מקסימלי של בקשות ליום (QPD). עם זאת, מגבלות השימוש הבאות עדיין חלות:
- מגבלת הקצב היא 100 בקשות לשנייה (QPS). הוא מחושב בתור הסכום של בקשות בצד הלקוח ובצד השרת עבור כל היישומים באמצעות פרטי הכניסה של אותו פרויקט.
הצגת שיוכים באפליקציה
- אם באפליקציה שלכם נעשה שימוש פרוגרמטי בהשלמה האוטומטית באופן פרוגרמטי, ממשק המשתמש שלכם צריך להציג את השיוך 'מופעל על ידי Google' או להופיע במפה עם מיתוג של Google.
- אם באפליקציה שלכם נעשה שימוש בווידג'ט ההשלמה האוטומטית, לא נדרשת כל פעולה נוספת (השיוך הנדרש מוצג כברירת מחדל).
- אם מאחזרים ומציגים מידע נוסף על מקומות אחרי שקבלתם אותו לפי מזהה, צריך להציג גם את השיוך של צד שלישי.
לפרטים נוספים, עיינו במסמכי התיעוד בנושא שיוך (Attribution).
אופטימיזציה של השלמה אוטומטית למקומות
בקטע הזה מתוארות שיטות מומלצות שיעזרו לך להפיק את המרב משירות ההשלמה האוטומטית של מקומות.
הנה כמה הנחיות כלליות:
- הדרך המהירה ביותר לפתח ממשק משתמש פעיל היא להשתמש בווידג'ט ההשלמה האוטומטית של ממשק ה-API של מפות Google JavaScript, בווידג'ט של ההשלמה האוטומטית של מקומות ב-Android או בבקרה על ממשק המשתמש של השלמה אוטומטית ב-SDK של מקומות ל-iOS.
- מפתחים הבנה טובה של שדות הנתונים בהשלמה האוטומטית של מקומות.
- השדות 'תעדוף לפי מיקום' ו'הגבלת מיקום' הם אופציונליים, אבל יכולים להשפיע באופן משמעותי על הביצועים של ההשלמה האוטומטית.
- יש להשתמש בטיפול בשגיאות כדי לוודא שהאפליקציה יורדת בחינניות אם ה-API מחזיר שגיאה.
- חשוב לוודא שהאפליקציה מטפלת בזמן שאין בחירה, ולהציע למשתמשים אפשרות להמשיך.
שיטות מומלצות לאופטימיזציה של עלויות
אופטימיזציית עלות בסיסית
כדי לבצע אופטימיזציה של עלות השימוש בשירות 'השלמה אוטומטית של מקומות', יש להשתמש במסיכות שדה בווידג'טים של פרטי מקום ובהשלמה אוטומטית של מקומות כדי להחזיר רק את השדות של נתוני המקומות שנחוצים לך.
אופטימיזציית עלות מתקדמת
כדאי לשקול שימוש בהטמעה פרוגרמטית של השלמה אוטומטית למקומות כדי לגשת לתמחור לפי בקשה, ולבקש תוצאות קידוד גיאוגרפי של מיקום במקום שנבחר, במקום פרטי המקום. תמחור לפי בקשה התואם ל-API לקידוד גיאוגרפי חסכוני יותר מהתמחור לכל פעילות באתר (מבוסס על פעילות באתר) אם שני התנאים הבאים מתקיימים:
- אם אתם זקוקים רק לקווי הרוחב/אורך או לכתובת של המקום שנבחר על ידי המשתמש, ה-API של קידוד גיאוגרפי מספק את המידע הזה עבור פחות מקריאה לפרטי מקום.
- אם משתמשים בוחרים חיזוי להשלמה אוטומטית בתוך בממוצע ארבע בקשות לחיזוי של ההשלמה האוטומטית, ייתכן שהתמחור לכל בקשה יהיה משתלם יותר מהתמחור לכל פעילות באתר.
האם הבקשה שלך דורשת מידע נוסף מלבד הכתובת וקו הרוחב/קו האורך של החיזוי שנבחר?
כן, נדרשים פרטים נוספים
שימוש בהשלמה אוטומטית לפי מקום על בסיס סשן עם פרטי מקום.
מאחר שבאפליקציה שלכם נדרשים פרטי מקום כמו שם המקום, סטטוס העסק או שעות הפתיחה, ההטמעה של ההשלמה האוטומטית של מקומות צריכה להשתמש באסימון בסשן (באופן פרוגרמטי, או בווידג'טים של JavaScript , Android או iOS) בעלות כוללת של $0.017 לכל סשן בתוספת מק"טים של נתוני מקומות בהתאם לשדות1 של בקשת המקומות{/11.
הטמעת ווידג'טים
ניהול סשנים מובנה באופן אוטומטי בווידג'טים של JavaScript, Android או iOS. מספר זה כולל את הבקשות להשלמה אוטומטית של מקומות ואת הבקשה 'פרטי מקום' בחיזוי שנבחר. עליך לציין את הפרמטר fields כדי לוודא שביקשת רק את השדות של נתוני המקום הדרושים.
הטמעה פרוגרמטית
יש להשתמש באסימון ביקור עם הבקשות להשלמה אוטומטית של מקומות. כשמבקשים את פרטי המקום לגבי החיזוי שנבחר, צריך לכלול את הפרמטרים הבאים:
- מזהה המקום מתוך התשובה להשלמה אוטומטית של מקומות
- אסימון הסשן שנעשה בו שימוש בבקשת ההשלמה האוטומטית של מקומות
- הפרמטר
fieldsשמציין את שדות נתוני המקום שנחוצים לך
לא, יש צורך רק בכתובת ובמיקום
ממשק API לקידוד גיאוגרפי עשוי להיות אפשרות משתלמת יותר מפרטי מקום עבור האפליקציה שלך, בהתאם לביצוע השימוש בהשלמה אוטומטית של מקומות. היעילות של כל אפליקציה בהשלמה אוטומטית משתנה בהתאם למה שהמשתמשים מזינים, היכן נעשה בה שימוש ואם השיטות המומלצות לאופטימיזציה של ביצועים יושמו.
כדי לענות על השאלה הבאה, לנתח כמה תווים משתמש מקליד בממוצע לפני שבוחרים חיזוי של השלמה אוטומטית באפליקציה שלך.
האם המשתמשים בוחרים חיזוי להשלמה אוטומטית של מקום ב-4 בקשות או פחות, בממוצע?
כן
מטמיעים את ההשלמה האוטומטית של מקומות באופן פרוגרמטי ללא אסימוני סשנים, ומפעילים את Geocoding API בחיזוי של המקום שנבחר.
ה-API של קידוד גיאוגרפי מספק כתובות וקואורדינטות של קווי אורך ורוחב תמורת 0.005 $לבקשה. שליחת 4 בקשות להשלמה אוטומטית של מקומות - לפי בקשה עולה 0.01,132 $, כך שהעלות הכוללת של 4 בקשות בתוספת קריאה ל-קידוד API גיאוגרפי לגבי חיזוי המקום שנבחר תהיה 0.01632$ - פחות מהמחיר של ההשלמה האוטומטית בסך 0.017 $לכל פעילות באתר.1
כדאי לשקול את השימוש בשיטות מומלצות לשיפור הביצועים שיעזרו למשתמשים לקבל את החיזוי שהם מחפשים בפחות תווים.
לא
שימוש בהשלמה אוטומטית לפי מקום על בסיס סשן עם פרטי מקום.
מאחר שהמספר הממוצע של בקשות שאתם מצפים לקבל לפני שמשתמש בוחר חיזוי של השלמה אוטומטית למקומות חורג מהעלות של תמחור לכל סשן, ההטמעה של ההשלמה האוטומטית למקומות צריכה להשתמש באסימון של הסשן עבור הבקשות להשלמה אוטומטית של מקומות וגם עבור הבקשה המשויכת לפרטי המקום עבור עלות כוללת של $0.017 לכל סשן.1
הטמעת ווידג'טים
ניהול סשנים מובנה באופן אוטומטי בווידג'טים של JavaScript, Android או iOS. מספר זה כולל את הבקשות להשלמה אוטומטית של מקומות ואת הבקשה 'פרטי מקום' בחיזוי שנבחר. עליך לציין את הפרמטר fields כדי לוודא שביקשת רק שדות נתונים בסיסיים.
הטמעה פרוגרמטית
יש להשתמש באסימון ביקור עם הבקשות להשלמה אוטומטית של מקומות. כשמבקשים את פרטי המקום לגבי החיזוי שנבחר, צריך לכלול את הפרמטרים הבאים:
- מזהה המקום מתוך התשובה להשלמה אוטומטית של מקומות
- אסימון הסשן שנעשה בו שימוש בבקשת ההשלמה האוטומטית של מקומות
- הפרמטר
fieldsשמציין שדות נתונים בסיסיים כגון כתובת וגיאומטריה
כדאי לשקול לעכב בקשות למילוי אוטומטי של מקומות
אפשר להשתמש בשיטות כמו השהיה של בקשה להשלמה אוטומטית של מקום עד שהמשתמש יזין את שלושת או ארבעת התווים הראשונים כדי שהאפליקציה תשלח פחות בקשות. לדוגמה, אם שולחים בקשות להשלמה אוטומטית של מקום עבור כל תו אחרי שהמשתמש מקליד את התו השלישי, המשמעות היא שאם המשתמש מקליד שבעה תווים ולאחר מכן בוחר חיזוי שעבורו אתם מבקשים בקשה אחת ל-API של קידוד גיאוגרפי, העלות הכוללת תהיה 0.01632$ (4 * 0.00283 השלמה אוטומטית לכל בקשה + קידוד גיאוגרפי בסך 0.005$).1
אם עיכובים בבקשות יכולים לגרום לשליחת הבקשה הפרוגרמטית הממוצעת עד ארבע פעמים, אפשר לפעול לפי ההנחיות להטמעה של השלמה אוטומטית של מיקום באמצעות קידוד API ב-גיאוגרפי. לתשומת ליבכם: עיכובים בבקשות עשויים להיחשב כזמן אחזור על ידי המשתמש שצפוי לצפות לחיזויים עם כל הקשה חדשה.
כדאי לשקול את השימוש בשיטות מומלצות לשיפור הביצועים שיעזרו למשתמשים לקבל את החיזוי שהם מחפשים, בפחות תווים.
-
העלויות המפורטות כאן הן דולר ארה"ב. מידע מלא על התמחור זמין בדף חיוב בפלטפורמה של מפות Google.
שיטות מומלצות לשיפור הביצועים
ההנחיות הבאות מתארות דרכים לביצוע אופטימיזציה של ביצועי ההשלמה האוטומטית של מקומות:
- ניתן להוסיף הגבלות לפי מדינה, תעדוף לפי מיקום והעדפת שפה (בהטמעות פרוגרמטיות) להטמעה של השלמה אוטומטית למקומות. אין צורך בהעדפות שפה עם ווידג'טים, כי הם בוחרים העדפות שפה מהדפדפן או מהנייד של המשתמש.
- אם ההשלמה האוטומטית של מקומות מלווה במפה, ניתן להטות את המיקום לפי אזור התצוגה במפה.
- במצבים שבהם משתמש אינו בוחר אחת מהחיזויים של ההשלמה האוטומטית, בדרך כלל מכיוון שאף אחת מהחיזויים האלה אינה כתובת התוצאה הרצויה, אפשר להשתמש שוב בקלט המקורי של המשתמש כדי לקבל תוצאות רלוונטיות יותר:
- אם צפוי שהמשתמש יזין את פרטי הכתובת בלבד, צריך להשתמש שוב בקלט המקורי של השיחה ב-API לקידוד גיאוגרפי.
- אם אתם מצפים שהמשתמש יזין את השאילתות של מקום ספציפי לפי שם או כתובת, צריך להשתמש בבקשה לחיפוש מקום. אם התוצאות צפויות רק באזור מסוים, השתמש בהטיית מיקום.
- משתמשים שמזינים כתובות משנה במדינות שבהן אין תמיכה בהשלמה אוטומטית של כתובות משנה, למשל צ'כיה, אסטוניה וליטא. לדוגמה, הכתובת הצ'כית "Stroupezhnického 3191/17, Parha" מניבה חיזוי חלקי בהשלמה אוטומטית של מקומות.
- משתמשים שמזינים כתובות עם תחיליות של קטע דרך, כמו "23-30 29th St 29, Queens" בעיר ניו יורק או "47-380 Kamehameha Hwy, Kaneohe" באי קאוואי באי הוואי.
פתרון בעיות
על אף שקיים מגוון רחב של שגיאות, סביר להניח שרוב השגיאות באפליקציה נגרמות משגיאות בהגדרה (לדוגמה, שנעשה שימוש במפתח API שגוי או שמפתח ה-API הוגדר בצורה שגויה), או שגיאות הקשורות למכסה (האפליקציה שלך חרגה מהמכסה שלה). במגבלות השימוש תוכלו לקרוא מידע נוסף על המכסות.
שגיאות שמתרחשות כשמשתמשים בפקדי ההשלמה האוטומטית מוחזרות בקריאה החוזרת (callback) של onActivityResult(). התקשרו אל Autocomplete.getStatus() כדי לקבל את הודעת הסטטוס של התוצאה.