«تکمیل خودکار جا» (قدیمی) پیش‌بینی‌های جا را در پاسخ به پرسمان‌های جستجوی کاربر برمی‌گرداند. همان‌طور که کاربر تایپ می‌کند، سرویس تکمیل خودکار پیشنهادهایی برای مکان‌هایی مانند کسب‌وکارها، نشانی‌ها، plus codes، و نقاط دیدنی برمی‌گرداند.
می‌توانید تکمیل خودکار را به روش‌های زیر به برنامه‌تان اضافه کنید:
- افزودن ابزاره تکمیل خودکار برای صرفه‌جویی در زمان توسعه و اطمینان از تجربه کاربری یکپارچه.
- پیش‌بینی‌های مکان را به‌صورت برنامه‌نویسی‌شده دریافت کنید تا تجربه کاربری سفارشی‌سازی‌شده‌ای ایجاد کنید.
افزودن ابزاره تکمیل خودکار
ابزاره تکمیل خودکار یک کادر گفتگوی جستجو با عملکرد تکمیل خودکار داخلی است. وقتی کاربر عبارت‌های جستجو را وارد می‌کند، ابزاره فهرستی از
مکان‌های پیش‌بینی‌شده را برای انتخاب ارائه می‌دهد. وقتی کاربر انتخابی انجام می‌دهد، یک نمونه
Place
برگردانده می‌شود که برنامه‌تان می‌تواند از آن برای دریافت جزئیات درباره مکان انتخاب‌شده استفاده کند.
دو گزینه برای افزودن ابزاره تکمیل خودکار به برنامه‌تان وجود دارد:
- گزینه ۱: جاسازی کردن
AutocompleteSupportFragment. - گزینه ۲: استفاده از هدف برای راه‌اندازی فعالیت تکمیل خودکار.
گزینه ۱: جاسازی AutocompleteSupportFragment
برای افزودن AutocompleteSupportFragment به برنامه‌تان، مراحل زیر را دنبال کنید:
- تکه‌ای به طرح‌بندی XML فعالیتتان اضافه کنید.
- شنونده‌ای به فعالیت یا قطعه‌تان اضافه کنید.
افزودن 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"
/>
- به‌طور پیش‌فرض، قطعه حاشیه یا پس‌زمینه ندارد. برای ارائه ظاهر دیداری یکسان، قطعه را در عنصر چیدمان دیگری مثل CardView لانه کنید.
- اگر از قطعه «تکمیل خودکار» استفاده می‌کنید و لازم است
onActivityResultرا لغو کنید، بایدsuper.onActivityResultرا فراخوانی کنید، درغیراین‌صورت قطعه به‌درستی عمل نخواهد کرد.
افزودن PlaceSelectionListener به فعالیت
PlaceSelectionListener برگرداندن مکان را در پاسخ به انتخاب کاربر مدیریت می‌کند. کد زیر ایجاد ارجاع به قطعه و
افزودن شنونده به AutocompleteSupportFragment را نشان می‌دهد:
Kotlin
// Build a BasicPlaceAutocomplete intent to allow the user to select a place. val basicAutocompleteIntent = BasicPlaceAutocomplete.createIntent(this) { setCountries(listOf("AU", "NZ")) }
جاوا
// Build a BasicPlaceAutocomplete intent to allow the user to select a place. Intent basicAutocompleteIntent = new BasicPlaceAutocomplete.IntentBuilder() .setCountries(List.of("AU", "NZ")) .build(this);
گزینه ۲: استفاده از هدف برای راه‌اندازی فعالیت تکمیل خودکار
اگر می‌خواهید برنامه‌تان از جریان ناوبری متفاوتی استفاده کند (برای مثال، برای راه‌اندازی تجربه تکمیل خودکار از نماد به‌جای فیلد جستجو)، برنامه‌تان می‌تواند تکمیل خودکار را بااستفاده از هدف راه‌اندازی کند.
برای راه‌اندازی ابزاره تکمیل خودکار بااستفاده از قصد، این مراحل را دنبال کنید:
- از
Autocomplete.IntentBuilderبرای ایجاد قصد استفاده کنید و حالتAutocompleteموردنظر را ارسال کنید. - راه‌انداز نتیجه فعالیتی را تعریف کنید
registerForActivityResultکه بتوان از آن برای راه‌اندازی هدف و مدیریت پیش‌بینی مکان انتخاب‌شده کاربر در نتیجه استفاده کرد.
ایجاد قصد تکمیل خودکار
مثال زیر از
Autocomplete.IntentBuilder
برای ایجاد یک هدف برای راه‌اندازی ابزاره تکمیل خودکار به‌عنوان یک هدف استفاده می‌کند:
Kotlin
val intent = PlaceAutocomplete.createIntent(this) { setTypesFilter(listOf(PlaceTypes.ESTABLISHMENT)) } startAutocomplete.launch(intent)
جاوا
// Start the autocomplete intent. Intent intent = new PlaceAutocomplete.IntentBuilder() .setTypesFilter(List.of(PlaceTypes.ESTABLISHMENT)) .build(this); startAutocomplete.launch(intent);
هنگام استفاده از هدف برای راه‌اندازی ابزاره تکمیل خودکار، می‌توانید از بین حالت‌های نمایش هم‌پوشانی یا تمام‌صفحه انتخاب کنید. نماگرفت‌های زیر هریک از حالت‌های نمایش را به‌ترتیب نشان می‌دهد:
ثبت کردن پاسخ تماس برای نتیجه هدف
برای دریافت اعلان هنگام انتخاب مکان توسط کاربر، یک
راه‌انداز registerForActivityResult() تعریف کنید که فعالیت را راه‌اندازی می‌کند و همچنین
نتیجه را همان‌طور که در مثال زیر نشان داده شده است مدیریت می‌کند. اگر کاربر پیش‌بینی‌ای را انتخاب کرده باشد،
در هدف موجود در شیء نتیجه ارائه خواهد شد. ازآنجایی‌که هدف
توسط Autocomplete.IntentBuilder ساخته شده است، روش
Autocomplete.getPlaceFromIntent() می‌تواند شیء Place را از آن استخراج کند.
Kotlin
private val startAutocomplete = registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult -> if (result.resultCode == RESULT_OK) { val intent = result.data if (intent != null) { val prediction = PlaceAutocomplete.getPredictionFromIntent(intent) if (prediction != null) { binding.autocompleteResult.text = getString( R.string.place_selection, prediction.getPrimaryText(null), prediction.placeId, prediction.getSecondaryText(null), ) Log.i( TAG, "Place: ${prediction.getPrimaryText(null)}, ${prediction.placeId}", ) } } } else if (result.resultCode == RESULT_CANCELED) { // The user canceled the operation. binding.autocompleteResult.setText(R.string.user_canceled_autocomplete) Log.i(TAG, "User canceled autocomplete") } else if (result.resultCode == PlacesSdkAutocompleteActivity.RESULT_ERROR) { val intent = result.data if (intent != null) { val status = PlaceAutocomplete.getResultStatusFromIntent(intent) Log.e(TAG, "An error occurred: ${status?.statusMessage}") } } }
جاوا
private final ActivityResultLauncher<Intent> startAutocomplete = registerForActivityResult( new ActivityResultContracts.StartActivityForResult(), result -> { if (result.getResultCode() == Activity.RESULT_OK) { Intent intent = result.getData(); if (intent != null) { AutocompletePrediction prediction = PlaceAutocomplete.getPredictionFromIntent(intent); if (prediction != null) { binding.autocompleteResult.setText( getString( R.string.place_selection, prediction.getPrimaryText(null), prediction.getPlaceId(), prediction.getSecondaryText(null))); Log.i( TAG, "Place: " + prediction.getPrimaryText(null) + ", " + prediction.getPlaceId()); } } } else if (result.getResultCode() == Activity.RESULT_CANCELED) { // The user canceled the operation. binding.autocompleteResult.setText(R.string.user_canceled_autocomplete); Log.i(TAG, "User canceled autocomplete"); } else if (result.getResultCode() == com.google.android.libraries.places.widget .PlaceAutocompleteActivity.RESULT_ERROR) { Intent intent = result.getData(); if (intent != null) { Status status = PlaceAutocomplete.getResultStatusFromIntent(intent); if (status != null) { Log.e(TAG, "An error occurred: " + status.getStatusMessage()); } } } });
دریافت پیش‌بینی‌های مکان به‌صورت برنامه‌نویسی‌شده
می‌توانید واسط کاربر جستجوی سفارشی را به‌عنوان جایگزینی برای واسط کاربر ارائه‌شده توسط
ابزاره تکمیل خودکار ایجاد کنید. برای انجام این کار، برنامه‌تان باید پیش‌بینی‌های مکان را به‌صورت برنامه‌نویسی‌شده دریافت کند. برنامه شما می‌تواند با فراخوانی
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_2TypeFilter.CITIES– فقط نتایج منطبق باLOCALITYیاADMINISTRATIVE_AREA_LEVEL_3را برمی‌گرداند.
اختیاری:
LatLngکه مکان مبدأ درخواست را مشخص می‌کند. وقتیsetOrigin()را فرامی‌خوانید، سرویس فاصله را به متر (distanceMeters) از مبدأ مشخص‌شده برای هر پیش‌بینی تکمیل خودکار در پاسخ برمی‌گرداند.
برای اطلاعات درباره انواع مکان، به راهنمای انواع مکان مراجعه کنید.
مثال زیر تماس کامل با
PlacesClient.findAutocompletePredictions() را نشان می‌دهد.
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(PlaceTypes.ESTABLISHMENT)) .setSessionToken(token) .setQuery(query) .build() placesClient.findAutocompletePredictions(request) .addOnSuccessListener { response: FindAutocompletePredictionsResponse -> val builder = StringBuilder() for (prediction in response.autocompletePredictions) { builder.append(prediction.getPrimaryText(null).toString()).append("\n") Log.i(TAG, prediction.placeId) Log.i(TAG, prediction.getPrimaryText(null).toString()) } binding.autocompleteResult.text = builder.toString() }.addOnFailureListener { exception: Exception? -> if (exception is ApiException) { Log.e(TAG, "Place not found: ${exception.statusCode}") binding.autocompleteResult.text = getString(R.string.place_not_found, exception.message) } }
جاوا
// Create a new token for the autocomplete session. Pass this to // FindAutocompletePredictionsRequest, // and once again when the user makes a selection (for example when calling fetchPlace()). AutocompleteSessionToken token = AutocompleteSessionToken.newInstance(); // Create a RectangularBounds object. RectangularBounds bounds = RectangularBounds.newInstance( new LatLng(-33.880490, 151.184363), new LatLng(-33.858754, 151.229596)); // Use the builder to create a FindAutocompletePredictionsRequest. FindAutocompletePredictionsRequest request = FindAutocompletePredictionsRequest.builder() // Call either setLocationBias() OR setLocationRestriction(). .setLocationBias(bounds) // .setLocationRestriction(bounds) .setOrigin(new LatLng(-33.8749937, 151.2041382)) .setCountries("AU", "NZ") .setTypesFilter(List.of(PlaceTypes.ESTABLISHMENT)) .setSessionToken(token) .setQuery(query) .build(); placesClient .findAutocompletePredictions(request) .addOnSuccessListener( (response) -> { StringBuilder builder = new StringBuilder(); for (AutocompletePrediction prediction : response.getAutocompletePredictions()) { builder.append(prediction.getPrimaryText(null).toString()) .append("\n"); Log.i(TAG, prediction.getPlaceId()); Log.i(TAG, prediction.getPrimaryText(null).toString()); } binding.autocompleteResult.setText(builder.toString()); }) .addOnFailureListener( (exception) -> { if (exception instanceof ApiException apiException) { Log.e(TAG, "Place not found: " + apiException.getStatusCode()); binding.autocompleteResult.setText( getString( R.string.place_not_found, apiException.getMessage())); } });
این API یک
FindAutocompletePredictionsResponse
در یک
Task برمی‌گرداند. FindAutocompletePredictionsResponse
حاوی فهرستی از
AutocompletePrediction
شیء است که مکان‌های پیش‌بینی‌شده را نشان می‌دهد. اگر مکان شناخته‌شده‌ای مطابق با پُرسمان و معیارهای فیلتر وجود نداشته باشد، ممکن است فهرست خالی باشد.
برای هر مکان پیش‌بینی‌شده، می‌توانید روش‌های زیر را برای بازیابی جزئیات مکان فراخوانی کنید:
getFullText(CharacterStyle)متن کامل شرح مکان را برمی‌گرداند. این ترکیبی از نوشتار اصلی و فرعی است. مثال: «برج ایفل، خیابان آناتول فرانس، پاریس، فرانسه». علاوه‌براین، این روش به شما امکان می‌دهد بخش‌هایی از شرح را که با جستجو مطابقت دارد با سبک انتخابی‌تان و بااستفاده ازCharacterStyleبرجسته کنید. پارامترCharacterStyleاختیاری است. اگر به برجسته‌سازی نیاز ندارید، آن را روی null تنظیم کنید.getPrimaryText(CharacterStyle)نوشتار اصلی توصیف‌کننده مکان را برمی‌گرداند. این معمولاً نام مکان است. مثال: «برج ایفل» و «خیابان پیت ۱۲۳».getSecondaryText(CharacterStyle)نوشتار فرعی شرح مکان را برمی‌گرداند. این ویژگی برای مثال به‌عنوان خط دوم هنگام نمایش پیش‌بینی‌های تکمیل خودکار مفید است. مثال: «خیابان آناتول فرانس، پاریس، فرانسه» و «سیدنی، نیو ساوت ولز».getPlaceId()شناسه مکان پیش‌بینی‌شده را برمی‌گرداند. شناسه مکان یک شناسه متنی است که به‌طور منحصربه‌فرد یک مکان را شناسایی می‌کند و می‌توانید از آن برای بازیابی مجدد شیءPlaceدر آینده استفاده کنید. برای اطلاعات بیشتر درباره شناسه‌های مکان در «کیت توسعه نرم‌افزار مکان‌ها» ویژه Android، به جزئیات مکان مراجعه کنید. برای اطلاعات کلی درباره شناسه‌های مکان، به نمای کلی شناسه مکان مراجعه کنید.getPlaceTypes()فهرست انواع مکان‌های مرتبط با این مکان را برمی‌گرداند.getDistanceMeters()فاصله مستقیم را برحسب متر بین این مکان و مبدأ مشخص‌شده در درخواست برمی‌گرداند.
کدهای جلسه
کدهای جلسه، مراحل پُرسمان و انتخاب جستجوی تکمیل خودکار کاربر را برای اهداف صورت‌حساب در یک جلسه مجزا گروه‌بندی می‌کنند. جلسه زمانی شروع می‌شود که کاربر شروع به تایپ کردن پُرسمان می‌کند و زمانی پایان می‌یابد که مکانی را انتخاب می‌کند. هر جلسه می‌تواند چند پُرسمان داشته باشد و پس‌از آن یک مکان انتخاب شود. وقتی جلسه‌ای به‌پایان می‌رسد، آن کد دیگر معتبر نیست؛ برنامه‌تان باید برای هر جلسه کد جدیدی تولید کند. توصیه می‌کنیم از کد جلسه برای همه جلسه‌های تکمیل خودکار برنامه‌ای استفاده کنید (وقتی قطعه‌ای را جاسازی می‌کنید یا تکمیل خودکار را بااستفاده از هدف راه‌اندازی می‌کنید، API به‌طور خودکار این کار را انجام می‌دهد).
کیت توسعه نرم‌افزار Places برای Android از
AutocompleteSessionToken
برای شناسایی هر جلسه استفاده می‌کند. برنامه شما باید یک کد جلسه جدید را در ابتدای هر جلسه جدید ارسال کند، سپس همان کد را همراه با شناسه جا در فراخوانی بعدی به
fetchPlace()
ارسال کند تا جزئیات جا را برای مکانی که توسط کاربر انتخاب شده است بازیابی کند.
محدود کردن نتایج تکمیل خودکار
می‌توانید نتایج تکمیل خودکار را به منطقه جغرافیایی خاصی محدود کنید، و/یا
نتایج را به یک یا چند نوع مکان، یا حداکثر پنج کشور فیلتر کنید. می‌توانید
این محدودیت‌ها را بر فعالیت تکمیل خودکار،
AutocompleteSupportFragment، و میاناهای برنامه‌سازی کاربردی تکمیل خودکار برنامه‌ای اعمال کنید.
برای محدود کردن نتایج، کارهای زیر را انجام دهید:
- برای ترجیح دادن نتایج در منطقه تعریف‌شده،
setLocationBias()را فراخوانی کنید (ممکن است برخی‌از نتایج خارج از منطقه تعریف‌شده همچنان برگردانده شوند). - برای فقط نشان دادن نتایج در منطقه تعریف‌شده،
setLocationRestriction()را فراخوانی کنید (فقط نتایج در منطقه تعریف‌شده برگردانده خواهد شد). - برای برگرداندن فقط نتایجی که با نوع مکان خاصی مطابقت دارند،
setTypesFilter()را فراخوانی کنید (برای مثال، با مشخص کردنTypeFilter.ADDRESSفقط نتایج دارای نشانی دقیق برگردانده می‌شود). - برای برگرداندن نتایج فقط در حداکثر پنج کشور مشخص‌شده،
setCountries()را فراخوانی کنید. کشورها باید به‌صورت کد کشور دوحرفی سازگار با ISO 3166-1 Alpha-2 ارسال شوند.
نتایج را به منطقه خاصی متمایل کنید
برای سوگیری نتایج تکمیل خودکار به یک منطقه جغرافیایی خاص،
setLocationBias() را فراخوانی کنید و
RectangularBounds را ارسال کنید.
نمونه کد زیر فراخوانی setLocationBias() را در یک نمونه قطعه نشان می‌دهد تا پیشنهادهای تکمیل خودکار آن را به منطقه‌ای از سیدنی، استرالیا متمایل کند.
Kotlin
intentBuilder.setLocationBias(bounds)
جاوا
intentBuilder.setLocationBias( RectangularBounds.newInstance( new LatLng(-33.880490, 151.184363), new LatLng(-33.858754, 151.229596)));
محدود کردن نتایج به منطقه‌ای خاص
برای محدود کردن نتایج تکمیل خودکار به یک منطقه جغرافیایی خاص،
setLocationRestriction() را فراخوانی کنید و
RectangularBounds را ارسال کنید.
نمونه کد زیر فراخوانی setLocationRestriction() را در
نمونه قطعه نشان می‌دهد تا پیشنهادهای تکمیل خودکار آن را به منطقه‌ای از سیدنی،
استرالیا متمایل کند.
Kotlin
intentBuilder.setLocationRestriction(bounds)
جاوا
intentBuilder.setLocationRestriction( RectangularBounds.newInstance( new LatLng(-33.880490, 151.184363), new LatLng(-33.858754, 151.229596)));
توجه: این محدودیت فقط برای کل مسیرها اعمال می‌شود، نتایج مصنوعی واقع در خارج از مرزهای مستطیلی ممکن است براساس مسیری که با محدودیت مکان هم‌پوشانی دارد برگردانده شود.
فیلتر کردن نتایج براساس نوع مکان یا مجموعه نوع
می‌توانید نتایج درخواست تکمیل خودکار را محدود کنید تا فقط نوع مکان خاصی را برگردانند. فیلتری را بااستفاده از انواع مکان یا مجموعه نوع فهرست‌شده در جدول‌های ۱، ۲، و ۳ در انواع مکان مشخص کنید. اگر چیزی مشخص نشده باشد، همه انواع برگردانده می‌شوند.
برای فیلتر کردن نتایج تکمیل خودکار،
setTypesFilter()
را فراخوانی کنید تا فیلتر تنظیم شود.
برای مشخص کردن فیلتر نوع یا مجموعه نوع:
setTypesFilter()را فراخوانی کنید و حداکثر پنج مقدار نوع را از جدول ۱ و جدول ۲ نشان‌داده‌شده در انواع مکان مشخص کنید. مقادیر نوع توسط ثابت‌ها درPlaceTypesتعریف می‌شوند.setTypesFilter()را فراخوانی کنید و مجموعه نوع را از جدول ۳ نشان‌داده‌شده در انواع مکان مشخص کنید. مقادیر مجموعه توسط ثابت‌های موجود درPlaceTypesتعریف می‌شود.فقط یک نوع از جدول ۳ در درخواست مجاز است. اگر مقداری از جدول ۳ مشخص کنید، نمی‌توانید مقداری از جدول ۱ یا جدول ۲ مشخص کنید. اگر این کار را بکنید، خطایی رخ می‌دهد.
نمونه کد زیر setTypesFilter() را در
AutocompleteSupportFragment فراخوانی می‌کند و چندین مقدار نوع را مشخص می‌کند.
Kotlin
intentBuilder.setTypesFilter(listOf("landmark", "restaurant", "store"))
جاوا
intentBuilder.setTypesFilter(List.of("landmark", "restaurant", "store"));
نمونه کد زیر فراخوانی setTypesFilter() را در
AutocompleteSupportFragment نشان می‌دهد تا فیلتری تنظیم شود که فقط نتایج دارای
نشانی دقیق را با مشخص کردن مجموعه نوع برگرداند.
Kotlin
intentBuilder.setTypesFilter(listOf(PlaceTypes.ADDRESS))
جاوا
intentBuilder.setTypesFilter(List.of(PlaceTypes.ESTABLISHMENT));
نمونه کد زیر فراخوانی setTypesFilter() را در
IntentBuilder برای تنظیم فیلتری نشان می‌دهد که فقط نتایج دارای نشانی دقیق را با
مشخص کردن مجموعه نوع برمی‌گرداند.
Kotlin
val intent = PlaceAutocomplete.createIntent(this) { setTypesFilter(listOf(PlaceTypes.ESTABLISHMENT)) }
جاوا
Intent intent = new PlaceAutocomplete.IntentBuilder() .setTypesFilter(List.of(PlaceTypes.ESTABLISHMENT)) .build(this);
فیلتر کردن نتایج براساس کشور
برای فیلتر کردن نتایج تکمیل خودکار تا پنج کشور،
setCountries()
را فراخوانی کنید تا کد کشور را تنظیم کنید.
سپس فیلتر را به قطعه یا هدف منتقل کنید. کشورها باید به‌صورت کد کشور دوحرفی سازگار با ISO 3166-1 Alpha-2 ارسال شوند.
نمونه کد زیر فراخوانی setCountries() را در
AutocompleteSupportFragment نشان می‌دهد تا فیلتری تنظیم شود که فقط نتایج را در
کشورهای مشخص‌شده برگرداند.
Kotlin
intentBuilder.setCountries(listOf("AU", "NZ"))
جاوا
intentBuilder.setCountries(List.of("AU", "NZ"));
حدود استفاده
استفاده شما از Places API (قدیمی)، ازجمله Places SDK for Android (قدیمی)، دیگر به حداکثر تعداد درخواست در روز (QPD) محدود نیست. بااین‌حال، حدود استفاده زیر همچنان اعمال می‌شود:
- حد نرخ ۶۰۰۰ درخواست در دقیقه است. این مقدار به‌صورت مجموع درخواست‌های سمت کارخواه و سمت سرور برای همه برنامه‌هایی که از اطلاعات کاربری یک پروژه استفاده می‌کنند محاسبه می‌شود.
نمایش ارجاع‌ها در برنامه
- اگر برنامه‌تان به‌صورت برنامه‌نویسی‌شده از سرویس تکمیل خودکار استفاده می‌کند، واسط کاربری‌تان باید یا ذکر منبع «طراحی‌شده توسط Google» را نمایش دهد یا در نقشه‌ای با نمانام Google ظاهر شود.
- اگر برنامه‌تان از ابزاره تکمیل خودکار استفاده می‌کند، اقدام دیگری لازم نیست (ارجاع لازم به‌طور پیش‌فرض نمایش داده می‌شود).
- اگر پس‌از دریافت مکان با شناسه، اطلاعات مکان بیشتری را بازیابی و نمایش می‌دهید، باید ارجاع‌های طرف سوم را نیز نمایش دهید.
برای جزئیات بیشتر، به اسناد مربوط به ارجاع‌ها مراجعه کنید.
بهینه‌سازی «تکمیل خودکار جا (قدیمی)»
این بخش روال‌های مطلوبی را شرح می‌دهد که به شما کمک می‌کند بیشترین بهره را از سرویس «تکمیل خودکار جا» (قدیمی) ببرید.
در اینجا چند دستورالعمل کلی ارائه شده است:
- سریع‌ترین راه برای توسعه میانای کاربر فعال استفاده از ابزاره تکمیل خودکار جا (قدیمی) در Maps JavaScript API، ابزاره تکمیل خودکار جا (قدیمی) در Places SDK for Android، یا کنترل میانای کاربر تکمیل خودکار جا (قدیمی) در Places SDK for iOS است.
- از همان ابتدا، فیلدهای داده «تکمیل خودکار جا» (قدیمی) را درک کنید.
- فیلدهای سوگیری مکان و محدودیت مکان اختیاری هستند اما می‌توانند تأثیر قابل‌توجهی بر عملکرد تکمیل خودکار داشته باشند.
- از مدیریت خطا استفاده کنید تا مطمئن شوید که اگر میانای برنامه‌سازی کاربردی خطایی برگرداند، برنامه شما به‌خوبی تنزل پیدا می‌کند.
- مطمئن شوید که برنامه‌تان وقتی انتخابی وجود ندارد، این وضعیت را مدیریت می‌کند و راهی برای ادامه دادن به کاربران ارائه می‌دهد.
روال‌های مطلوب بهینه‌سازی هزینه
بهینه‌سازی هزینه پایه
برای بهینه‌سازی هزینه استفاده از سرویس «تکمیل خودکار جا» (قدیمی)، از ماسک‌های فیلد در ابزاره‌های «جزئیات جا» (قدیمی) و «تکمیل خودکار جا» (قدیمی) استفاده کنید تا فقط فیلدهای داده «تکمیل خودکار جا» (قدیمی) موردنیازتان برگردانده شود.
بهینه‌سازی پیشرفته هزینه
پیاده‌سازی برنامه‌نویسی‌شده «تکمیل خودکار جا (قدیمی)» را برای دسترسی به SKU: تکمیل خودکار - قیمت‌گذاری به‌ازای درخواست و درخواست نتایج Geocoding API درباره مکان انتخاب‌شده به‌جای «جزئیات جا (قدیمی)» درنظر بگیرید. اگر هر دو شرط زیر برقرار باشد، قیمت‌گذاری به‌ازای درخواست همراه با Geocoding API مقرون‌به‌صرفه‌تر از قیمت‌گذاری به‌ازای جلسه (جلسه‌محور) است:
- اگر فقط به طول و عرض جغرافیایی یا نشانی مکان انتخابی کاربر نیاز دارید، Geocoding API این اطلاعات را با هزینه کمتری نسبت‌به فراخوانی Place Details (Legacy) ارائه می‌دهد.
- اگر کاربران پیش‌بینی تکمیل خودکار را در میانگین چهار درخواست پیش‌بینی «تکمیل خودکار جا (قدیمی)» یا کمتر انتخاب کنند، قیمت‌گذاری براساس درخواست می‌تواند مقرون‌به‌صرفه‌تر از قیمت‌گذاری براساس جلسه باشد.
آیا برنامه شما به اطلاعاتی غیراز نشانی و طول/عرض جغرافیایی پیش‌بینی انتخاب‌شده نیاز دارد؟
بله، به جزئیات بیشتری نیاز است
از «تکمیل خودکار جا» (قدیمی) مبتنی بر جلسه با «جزئیات جا» (قدیمی) استفاده کنید.
ازآنجایی‌که برنامه شما به «جزئیات جا (قدیمی)» نیاز دارد، مثل نام مکان، وضعیت کسب‌وکار،
یا ساعت کاری، پیاده‌سازی شما از «تکمیل خودکار جا (قدیمی)» باید از کد جلسه استفاده کند
(به‌صورت برنامه‌نویسی‌شده یا تعبیه‌شده در
ابزاره‌های JavaScript،
Android،
یا iOS)
به‌ازای هر جلسه
به‌علاوه شناسه‌های محصول داده‌های Places قابل‌اعمال،
بسته به اینکه کدام فیلدهای داده مکان را درخواست می‌کنید.۱
پیاده‌سازی ابزاره
مدیریت جلسه به‌طور خودکار در ابزاره‌های
JavaScript،
Android،
یا iOS
ساخته می‌شود. این شامل درخواست‌های «تکمیل خودکار جا» (قدیمی) و درخواست «جزئیات جا» (قدیمی)
در پیش‌بینی انتخاب‌شده می‌شود. حتماً پارامتر fields را مشخص کنید تا مطمئن شوید فقط
فیلدهای داده «تکمیل خودکار جا (قدیمی)»
موردنیازتان را درخواست می‌کنید.
پیاده‌سازی برنامه‌ای
از
کد جلسه
با درخواست‌های «تکمیل خودکار جا» (قدیمی) استفاده کنید. هنگام درخواست «جزئیات مکان (قدیمی)» درباره پیش‌بینی انتخاب‌شده، پارامترهای زیر را اضافه کنید:
- شناسه جا از پاسخ «تکمیل خودکار جا» (قدیمی)
- کد جلسه استفاده‌شده در درخواست «تکمیل خودکار جا» (قدیمی)
- پارامتر
fieldsکه فیلدهای داده «تکمیل خودکار جا» (قدیمی) موردنیازتان را مشخص می‌کند
نه، فقط به نشانی و مکان نیاز دارد
Geocoding API می‌تواند گزینه مقرون‌به‌صرفه‌تری نسبت‌به Place Details (Legacy) برای برنامه شما باشد، بسته به عملکرد استفاده شما از Place Autocomplete (Legacy). کارایی «تکمیل خودکار جا» (قدیمی) هر برنامه بسته به آنچه کاربران وارد می‌کنند، جایی که برنامه استفاده می‌شود، و اینکه آیا روال‌های مطلوب بهینه‌سازی عملکرد اجرا شده‌اند یا نه متفاوت است.
برای پاسخ دادن به سؤال زیر، تحلیل کنید که کاربر به‌طور میانگین چند نویسه تایپ می‌کند تا پیش‌بینی «تکمیل خودکار جا» (قدیمی) را در برنامه‌تان انتخاب کند.
آیا کاربران شما به‌طور میانگین با چهار درخواست یا کمتر، پیش‌بینی «تکمیل خودکار جا (قدیمی)» را انتخاب می‌کنند؟
بله
«تکمیل خودکار جا» (قدیمی) را به‌صورت برنامه‌نویسی‌شده بدون کد جلسه پیاده‌سازی کنید و Geocoding API را در پیش‌بینی مکان انتخاب‌شده فراخوانی کنید.
Geocoding API نشانی‌ها و مختصات طول/عرض جغرافیایی را ارائه می‌دهد.
ایجاد چهار درخواست
تکمیل خودکار - به‌ازای هر درخواست
به‌علاوه یک فراخوانی Geocoding API
درباره پیش‌بینی مکان انتخاب‌شده کمتر از هزینه «تکمیل خودکار جا (قدیمی)» به‌ازای هر جلسه است.۱
برای کمک به کاربران در دریافت پیش‌بینی موردنظرشان با نویسه‌های کمتر، روال‌های مطلوب عملکرد را به‌کار بگیرید.
نه
از «تکمیل خودکار جا» (قدیمی) مبتنی بر جلسه با «جزئیات جا» (قدیمی) استفاده کنید.
ازآنجایی‌که میانگین تعداد درخواست‌هایی که انتظار دارید قبل‌از انتخاب پیش‌بینی «تکمیل خودکار جا» (قدیمی) توسط کاربر انجام شود، از هزینه قیمت‌گذاری هر جلسه فراتر می‌رود، پیاده‌سازی شما از «تکمیل خودکار جا» (قدیمی) باید از یک کد جلسه برای هر دو درخواست «تکمیل خودکار جا» (قدیمی) و درخواست «جزئیات جا» (قدیمی) مرتبط استفاده کند
در هر جلسه.
۱
پیاده‌سازی ابزاره
مدیریت جلسه به‌طور خودکار در ابزاره‌های
JavaScript،
Android،
یا iOS
ساخته می‌شود. این شامل درخواست‌های «تکمیل خودکار جا» (قدیمی) و درخواست «جزئیات جا» (قدیمی) در پیش‌بینی انتخاب‌شده می‌شود. حتماً پارامتر fields را مشخص کنید
تا مطمئن شوید فقط فیلدهای موردنیازتان را درخواست می‌کنید.
پیاده‌سازی برنامه‌ای
از
کد جلسه
با درخواست‌های «تکمیل خودکار جا» (قدیمی) استفاده کنید.
هنگام درخواست «جزئیات مکان (قدیمی)» درباره پیش‌بینی انتخاب‌شده،
پارامترهای زیر را اضافه کنید:
- شناسه جا از پاسخ «تکمیل خودکار جا» (قدیمی)
- کد جلسه استفاده‌شده در درخواست «تکمیل خودکار جا» (قدیمی)
- پارامتر
fieldsکه فیلدهای داده‌های پایه مثل نشانی و هندسه را مشخص می‌کند
به‌تأخیر انداختن درخواست‌های «تکمیل خودکار جا» (قدیمی) را مدنظر قرار دهید
می‌توانید از استراتژی‌هایی مثل به‌تأخیر انداختن درخواست «تکمیل خودکار جا» (قدیمی) تا زمانی که کاربر سه یا چهار نویسه اول را تایپ کند استفاده کنید تا برنامه‌تان درخواست‌های کمتری ارسال کند. برای مثال، ارسال درخواست‌های «تکمیل خودکار جا (قدیمی)» برای هر نویسه پس‌از اینکه کاربر نویسه سوم را تایپ کرد به این معنی است که اگر کاربر هفت نویسه تایپ کند و سپس پیش‌بینی‌ای را انتخاب کند که برای آن یک درخواست Geocoding API ارسال می‌کنید، هزینه کل برای ۴ «تکمیل خودکار جا (قدیمی)» به‌ازای هر درخواست + Geocoding خواهد بود.۱
اگر با به‌تأخیر انداختن درخواست‌ها می‌توانید میانگین درخواست‌های برنامه‌ای را به کمتر از چهار برسانید، می‌توانید از راهنمای پیاده‌سازی «تکمیل خودکار جا» (قدیمی) با Geocoding API پیروی کنید. توجه داشته باشید که تأخیر در درخواست‌ها می‌تواند از دید کاربری که ممکن است انتظار داشته باشد با هر کلید جدید پیش‌بینی‌ها را ببیند، به‌عنوان تأخیر درک شود.
روال‌های مطلوب عملکرد را به‌کار بگیرید تا به کاربران کمک کنید پیش‌بینی موردنظرشان را با نویسه‌های کمتری دریافت کنند.
-
برای اطلاع از هزینه‌ها، فهرست‌های قیمت‌گذاری «پلاتفرم Google Maps» را ببینید.
روال‌های مطلوب عملکرد
دستورالعمل‌های زیر روش‌های بهینه‌سازی عملکرد «تکمیل خودکار جا» (قدیمی) را شرح می‌دهد:
- محدودیت‌های کشور، سوگیری مکان، و (برای پیاده‌سازی‌های برنامه‌ای) اولویت زبان را به پیاده‌سازی «تکمیل خودکار جا» (قدیمی) اضافه کنید. برای ابزاره‌ها به اولویت زبان نیازی نیست چون آن‌ها اولویت‌های زبان را از مرورگر یا دستگاه همراه کاربر انتخاب می‌کنند.
- اگر «تکمیل خودکار جا» (قدیمی) با نقشه همراه باشد، می‌توانید مکان را براساس نمای نقشه سوگیری کنید.
- در شرایطی که کاربر یکی از پیش‌بینی‌های «تکمیل خودکار جا (قدیمی)» را انتخاب نمی‌کند، معمولاً به این دلیل که هیچ‌کدام از آن پیش‌بینی‌ها نشانی نتیجه موردنظر نیست، می‌توانید از ورودی اصلی کاربر دوباره استفاده کنید تا نتایج مرتبط‌تری دریافت کنید:
- اگر انتظار دارید کاربر فقط اطلاعات نشانی را وارد کند، از ورودی اصلی کاربر در فراخوانی به Geocoding API مجدداً استفاده کنید.
- اگر انتظار دارید کاربر پُرسمان‌ها را برای مکان خاصی براساس نام یا نشانی وارد کند، از درخواست «جزئیات جا (قدیمی)» استفاده کنید. اگر نتایج فقط در منطقه خاصی موردانتظار است، از سوگیری مکان استفاده کنید.
- کاربرانی که نشانی‌های فرعی را وارد می‌کنند، مانند نشانی‌های مربوط به واحدها یا آپارتمان‌های خاص در یک ساختمان. برای مثال، نشانی چکی «Stroupežnického 3191/17, Praha» پیش‌بینی جزئی در «تکمیل خودکار جا» (قدیمی) ارائه می‌دهد.
- کاربرانی که نشانی‌ها را با پیشوندهای بخش جاده وارد می‌کنند، مانند «23-30 29th St, Queens» در شهر نیویورک یا «47-380 Kamehameha Hwy, Kaneohe» در جزیره کائوآئی در هاوایی.
سوگیری مکانی
با ارسال پارامتر location و پارامتر radius، نتایج را به منطقه مشخصی متمایل کنید. این کار به «تکمیل خودکار جا» (قدیمی) دستور می‌دهد که نمایش نتایج را در منطقه تعریف‌شده ترجیح دهد. ممکن است نتایج خارج از منطقه تعریف‌شده همچنان نمایش داده شود. می‌توانید از پارامتر includedRegionCodes برای فیلتر کردن نتایج استفاده کنید
تا فقط مکان‌های داخل کشور مشخص‌شده نشان داده شود.
محدود کردن مکان
با ارسال پارامتر locationRestriction، نتایج را به منطقه مشخصی محدود کنید.
همچنین می‌توانید با افزودن پارامتر
strictbounds
، نتایج را به منطقه‌ای که با location
و پارامتر radius تعریف شده است محدود کنید. این کار به «تکمیل خودکار جا» (قدیمی) دستور می‌دهد فقط
نتایج درون آن منطقه را برگرداند.
عیب‌یابی
اگرچه ممکن است خطاهای بسیار متنوعی رخ دهد، اکثر خطاهایی که احتمالاً برنامه‌تان تجربه می‌کند معمولاً به‌دلیل خطاهای پیکربندی (برای مثال، استفاده از کلید میانای برنامه‌سازی کاربردی اشتباه یا پیکربندی نادرست کلید میانای برنامه‌سازی کاربردی) یا خطاهای سهمیه (برنامه‌تان از سهمیه خود فراتر رفته است) ایجاد می‌شوند. برای اطلاعات بیشتر درباره سهمیه‌ها، حدود استفاده را ببینید.
خطاهایی که در استفاده از کنترل‌های تکمیل خودکار رخ می‌دهد در
onActivityResult() callback برگردانده می‌شود. برای دریافت پیام وضعیت نتیجه،
با Autocomplete.getStatus() تماس بگیرید.