این محصول یا ویژگی در وضعیت Legacy است. برای اطلاعات بیشتر درباره وضعیت Legacy به محصولات و ویژگی های Legacy مراجعه کنید. برای انتقال به Places API (جدید)، به راهنمای مهاجرت مراجعه کنید.

این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

محل تکمیل خودکار

توسعه‌دهندگان منطقه اقتصادی اروپا (EEA)

سرویس تکمیل خودکار در Places SDK برای اندروید، پیش‌بینی‌های مکانی را در پاسخ به جستجوهای کاربر برمی‌گرداند. همزمان با تایپ کاربر، سرویس تکمیل خودکار پیشنهادهایی برای مکان‌هایی مانند مشاغل، آدرس‌ها، کدهای پلاس و نقاط مورد علاقه ارائه می‌دهد.

شما می‌توانید به روش‌های زیر قابلیت تکمیل خودکار را به برنامه خود اضافه کنید:

برای صرفه‌جویی در زمان توسعه و تضمین یک تجربه کاربری پایدار ، یک ویجت تکمیل خودکار اضافه کنید .
پیش‌بینی‌های مکان را به صورت برنامه‌نویسی شده دریافت کنید تا یک تجربه کاربری سفارشی ایجاد کنید.

یک ابزارک تکمیل خودکار اضافه کنید

ویجت تکمیل خودکار، یک کادر محاوره‌ای جستجو با قابلیت تکمیل خودکار داخلی است. هنگامی که کاربر عبارات جستجو را وارد می‌کند، ویجت لیستی از مکان‌های پیش‌بینی‌شده برای انتخاب را ارائه می‌دهد. هنگامی که کاربر انتخابی انجام می‌دهد، یک نمونه Place بازگردانده می‌شود که برنامه شما می‌تواند از آن برای دریافت جزئیات مربوط به مکان انتخاب‌شده استفاده کند.

دو گزینه برای اضافه کردن ویجت تکمیل خودکار به برنامه شما وجود دارد:

گزینه ۱: جاسازی یک AutocompleteSupportFragment .
گزینه ۲: از یک intent برای اجرای اکتیویتی تکمیل خودکار استفاده کنید .

گزینه ۱: جاسازی یک AutocompleteSupportFragment

برای افزودن AutocompleteSupportFragment به برنامه خود، مراحل زیر را انجام دهید:

یک فرگمنت به طرح‌بندی XML اکتیویتی خود اضافه کنید.
یک شنونده (listener) به اکتیویتی یا فرگمنت خود اضافه کنید.

افزودن AutocompleteSupportFragment به یک فعالیت

برای افزودن AutocompleteSupportFragment به یک اکتیویتی، یک fragment جدید به طرح 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 قرار دهید.
اگر از قطعه کد Autocomplete استفاده می‌کنید و نیاز به override کردن onActivityResult دارید، باید super.onActivityResult فراخوانی کنید، در غیر این صورت قطعه کد به درستی کار نخواهد کرد.

اضافه کردن یک PlaceSelectionListener به یک اکتیویتی

PlaceSelectionListener در پاسخ به انتخاب کاربر، یک مکان را برمی‌گرداند. کد زیر ایجاد یک ارجاع به fragment و اضافه کردن یک شنونده به AutocompleteSupportFragment شما را نشان می‌دهد:

te_support_fragment-code-sample" class="ds-selector-tabs" data-scope="maps_places_autocomplete_support_fragment" style=";text-align:right;direction:rtl">

کاتلین

    // 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); } });

گزینه ۲: استفاده از یک اینتنت برای اجرای اکتیویتی تکمیل خودکار

اگر می‌خواهید برنامه شما از یک جریان ناوبری متفاوت استفاده کند (برای مثال، برای فعال کردن قابلیت تکمیل خودکار از یک آیکون به جای یک فیلد جستجو)، برنامه شما می‌تواند با استفاده از یک intent، تکمیل خودکار را اجرا کند.

برای اجرای ویجت تکمیل خودکار با استفاده از یک intent، مراحل زیر را دنبال کنید:

از Autocomplete.IntentBuilder برای ایجاد یک intent استفاده کنید و حالت Autocomplete مورد نظر را به آن ارسال کنید.
یک registerForActivityResult اجراکننده‌ی نتیجه‌ی فعالیت تعریف کنید که بتواند برای اجرای intent و مدیریت پیش‌بینی مکان انتخاب شده توسط کاربر در نتیجه استفاده شود.

یک هدف تکمیل خودکار ایجاد کنید

مثال زیر از Autocomplete.IntentBuilder برای ایجاد یک intent جهت اجرای ویجت autocomplete به عنوان یک 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);

هنگام استفاده از یک اینتنت برای اجرای ویجت تکمیل خودکار، می‌توانید از حالت‌های نمایش روکش یا تمام صفحه یکی را انتخاب کنید. تصاویر زیر به ترتیب هر حالت نمایش را نشان می‌دهند:

وقتی در حالت پوششی نمایش داده می‌شود، ویجت تکمیل خودکار روی رابط کاربری فراخوانی‌کننده قرار می‌گیرد. — **شکل ۱** : ویجت تکمیل خودکار در حالت OVERLY

وقتی در حالت تمام صفحه نمایش داده می‌شود، ویجت تکمیل خودکار کل صفحه را پر می‌کند. — **شکل 2** : ویجت تکمیل خودکار در حالت تمام صفحه

ثبت یک فراخوانی برای نتیجه intent

برای دریافت اعلان هنگامی که کاربر مکانی را انتخاب کرده است، یک لانچر registerForActivityResult() تعریف کنید که activity را اجرا کرده و همچنین نتیجه را همانطور که در مثال زیر نشان داده شده است، مدیریت می‌کند. اگر کاربر یک پیش‌بینی را انتخاب کرده باشد، آن پیش‌بینی در intent موجود در شیء result ارائه خواهد شد. از آنجایی که intent توسط Autocomplete.IntentBuilder ساخته شده است، متد Autocomplete.getPlaceFromIntent() می‌تواند شیء Place را از آن استخراج کند.

کاتلین

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");
            }
        });

دریافت پیش‌بینی‌های مکانی به صورت برنامه‌نویسی‌شده

شما می‌توانید یک رابط کاربری جستجوی سفارشی به عنوان جایگزینی برای رابط کاربری ارائه شده توسط ویجت تکمیل خودکار ایجاد کنید. برای انجام این کار، برنامه شما باید پیش‌بینی‌های مکان را به صورت برنامه‌نویسی دریافت کند. برنامه شما می‌تواند با فراخوانی PlacesClient.findAutocompletePredictions() و ارسال یک شیء FindAutocompletePredictionsRequest با پارامترهای زیر، لیستی از نام مکان‌ها و/یا آدرس‌های پیش‌بینی شده را از API تکمیل خودکار دریافت کند:

الزامی: یک رشته 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) متن کامل توضیحات یک مکان را برمی‌گرداند. این ترکیبی از متن اصلی و فرعی است. مثال: " برج ایفل، خیابان آناتول فرانس، پاریس، فرانسه ". علاوه بر این، این متد به شما امکان می‌دهد بخش‌هایی از توضیحات را که با جستجو مطابقت دارند، با استفاده CharacterStyle و با سبک دلخواه خود، هایلایت کنید. پارامتر CharacterStyle اختیاری است. اگر نیازی به هایلایت کردن ندارید، آن را روی null تنظیم کنید.
getPrimaryText(CharacterStyle) متن اصلی توصیف کننده یک مکان را برمی‌گرداند. این متن معمولاً نام مکان است. مثال‌ها: « برج ایفل » و « خیابان پیت ۱۲۳ ».
getSecondaryText(CharacterStyle) متن فرعی توصیف یک مکان را برمی‌گرداند. این متن، برای مثال، به عنوان خط دوم هنگام نمایش پیش‌بینی‌های تکمیل خودکار مفید است. مثال‌ها: « خیابان آناتول فرانس، پاریس، فرانسه » و « سیدنی، نیو ساوت ولز ».
getPlaceId() شناسه مکان مکان پیش‌بینی‌شده را برمی‌گرداند. شناسه مکان یک شناسه متنی است که به‌طور منحصربه‌فرد یک مکان را شناسایی می‌کند و می‌توانید بعداً برای بازیابی شیء Place از آن استفاده کنید. برای اطلاعات بیشتر در مورد شناسه‌های مکان در Places SDK برای اندروید، به Place Details مراجعه کنید. برای اطلاعات کلی در مورد شناسه‌های مکان، به Place ID overview مراجعه کنید.
getPlaceTypes() لیستی از انواع مکان‌های مرتبط با این مکان را برمی‌گرداند.
getDistanceMeters() فاصله‌ی مستقیم بین این مکان و مبدا مشخص شده در درخواست را بر حسب متر برمی‌گرداند.

نکته: برای اطلاعات بیشتر در مورد مقداردهی اولیه PlacesClient ، به بخش مقداردهی اولیه کلاینت API Places مراجعه کنید.

توکن‌های جلسه

توکن‌های جلسه، مراحل پرس‌وجو و انتخاب جستجوی تکمیل خودکار کاربر را برای اهداف حسابداری در یک جلسه مجزا گروه‌بندی می‌کنند. جلسه زمانی شروع می‌شود که کاربر شروع به تایپ یک پرس‌وجو می‌کند و زمانی که یک مکان را انتخاب می‌کند، پایان می‌یابد. هر جلسه می‌تواند چندین پرس‌وجو داشته باشد و به دنبال آن یک مکان انتخاب شود. پس از پایان یک جلسه، توکن دیگر معتبر نیست؛ برنامه شما باید برای هر جلسه یک توکن جدید تولید کند. ما توصیه می‌کنیم از توکن‌های جلسه برای همه جلسات تکمیل خودکار برنامه‌ریزی‌شده استفاده کنید (وقتی یک قطعه را جاسازی می‌کنید یا تکمیل خودکار را با استفاده از یک هدف راه‌اندازی می‌کنید، API به طور خودکار این کار را انجام می‌دهد).

کیت توسعه نرم‌افزار Places برای اندروید از یک AutocompleteSessionToken برای شناسایی هر جلسه استفاده می‌کند. برنامه شما باید با شروع هر جلسه جدید، یک توکن جلسه جدید ارسال کند، سپس همان توکن را به همراه یک شناسه مکان، در فراخوانی بعدی تابع fetchPlace() ارسال کند تا جزئیات مکان را برای مکانی که توسط کاربر انتخاب شده است، بازیابی کند.

درباره توکن‌های جلسه بیشتر بدانید .

محدود کردن نتایج تکمیل خودکار

شما می‌توانید نتایج تکمیل خودکار را به یک منطقه جغرافیایی خاص محدود کنید، و/یا نتایج را به یک یا چند نوع مکان، یا حداکثر به پنج کشور فیلتر کنید. می‌توانید این محدودیت‌ها را به فعالیت تکمیل خودکار، AutocompleteSupportFragment و APIهای تکمیل خودکار برنامه‌نویسی‌شده اعمال کنید.

برای محدود کردن نتایج، موارد زیر را انجام دهید:

برای ترجیح دادن نتایج درون ناحیه تعریف‌شده، تابع setLocationBias() را فراخوانی کنید (ممکن است برخی از نتایج خارج از ناحیه تعریف‌شده همچنان بازگردانده شوند).
برای نمایش نتایج فقط در محدوده تعریف شده، تابع setLocationRestriction() را فراخوانی کنید (فقط نتایج داخل محدوده تعریف شده بازگردانده می‌شوند).
برای برگرداندن فقط نتایجی که با نوع مکان خاصی مطابقت دارند، setTypesFilter() را فراخوانی کنید (برای مثال، مشخص کردن TypeFilter.ADDRESS فقط نتایجی را با آدرس دقیق برمی‌گرداند).
برای بازگرداندن نتایج فقط در محدوده حداکثر پنج کشور مشخص، تابع setCountries() را فراخوانی کنید. کشورها باید به صورت یک کد کشور دو کاراکتری و سازگار با استاندارد ISO 3166-1 Alpha-2 ارسال شوند.

نتایج سوگیری به یک منطقه خاص

برای اینکه نتایج تکمیل خودکار به یک منطقه جغرافیایی خاص نسبت داده شود، تابع setLocationBias() را فراخوانی کنید و یک RectangularBounds به آن ارسال کنید. مثال کد زیر فراخوانی تابع setLocationBias() را روی یک نمونه فرگمنت نشان می‌دهد تا پیشنهادات تکمیل خودکار آن به منطقه‌ای از سیدنی، استرالیا نسبت داده شود.

کاتلین

        autocompleteFragment.setLocationBias(bounds)

جاوا

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

محدود کردن نتایج به یک منطقه خاص

برای محدود کردن نتایج تکمیل خودکار به یک منطقه جغرافیایی خاص، تابع setLocationRestriction() را فراخوانی کنید و یک RectangularBounds به آن ارسال کنید. مثال کد زیر فراخوانی تابع setLocationRestriction() را روی یک نمونه از فرگمنت نشان می‌دهد تا پیشنهادات تکمیل خودکار آن به منطقه‌ای از سیدنی، استرالیا محدود شود.

کاتلین

        autocompleteFragment.setLocationRestriction(bounds)

جاوا

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

توجه: این محدودیت فقط برای کل مسیرها اعمال می‌شود، نتایج مصنوعی واقع در خارج از مرزهای مستطیلی ممکن است بر اساس مسیری که با محدودیت مکان همپوشانی دارد، بازگردانده شوند.

فیلتر کردن نتایج بر اساس نوع مکان یا نوع مجموعه

شما می‌توانید نتایج حاصل از یک درخواست تکمیل خودکار را محدود کنید تا فقط نوع مکان خاصی را برگردانند. با استفاده از انواع مکان یا مجموعه‌ای از انواع ذکر شده در جداول ۱، ۲ و ۳ در مورد انواع مکان ، یک فیلتر مشخص کنید. اگر چیزی مشخص نشود، همه انواع برگردانده می‌شوند.

برای فیلتر کردن نتایج تکمیل خودکار، تابع setTypesFilter() را فراخوانی کنید تا فیلتر تنظیم شود.

برای مشخص کردن نوع یا فیلتر مجموعه نوع:

تابع setTypesFilter() را فراخوانی کنید و حداکثر پنج مقدار نوع را از جدول ۱ و جدول ۲ نشان داده شده در Place Types مشخص کنید. مقادیر نوع توسط ثابت‌های موجود در PlaceTypes تعریف می‌شوند.
تابع setTypesFilter() را فراخوانی کنید و یک مجموعه نوع از جدول 3 نشان داده شده در Place Types را مشخص کنید. مقادیر مجموعه توسط ثابت‌های PlaceTypes تعریف می‌شوند.
فقط یک نوع از جدول ۳ در درخواست مجاز است. اگر مقداری را از جدول ۳ مشخص کنید، نمی‌توانید مقداری را از جدول ۱ یا جدول ۲ مشخص کنید. در این صورت، خطایی رخ می‌دهد.

مثال کد زیر تابع 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");

محدودیت‌های استفاده

استفاده شما از API مکان‌ها، شامل Places SDK برای اندروید، دیگر محدود به حداکثر تعداد درخواست در روز (QPD) نیست. با این حال، محدودیت‌های استفاده زیر همچنان اعمال می‌شود:

محدودیت سرعت ۶۰۰۰ QPM (درخواست در دقیقه) است. این مقدار به صورت مجموع درخواست‌های سمت کلاینت و سمت سرور برای همه برنامه‌هایی که از اعتبارنامه‌های همان پروژه استفاده می‌کنند، محاسبه می‌شود.

نمایش انتساب‌ها در برنامه شما

اگر برنامه شما از سرویس تکمیل خودکار به صورت برنامه‌نویسی‌شده استفاده می‌کند، رابط کاربری شما باید یا عبارت «Powered by Google» را نمایش دهد، یا در یک نقشه با برند گوگل ظاهر شود.
اگر برنامه شما از ویجت تکمیل خودکار استفاده می‌کند، هیچ اقدام اضافی لازم نیست (به طور پیش‌فرض، انتساب مورد نیاز نمایش داده می‌شود).
اگر پس از دریافت یک مکان بر اساس شناسه، اطلاعات اضافی مکان را بازیابی و نمایش دهید، باید نسبت‌های شخص ثالث را نیز نمایش دهید.

برای جزئیات بیشتر، به مستندات مربوط به انتساب‌ها مراجعه کنید.

بهینه‌سازی تکمیل خودکار مکان (Legacy)

این بخش بهترین شیوه‌ها را برای کمک به شما در استفاده‌ی حداکثری از سرویس تکمیل خودکار مکان (قدیمی) شرح می‌دهد.

در اینجا چند دستورالعمل کلی آورده شده است:

سریع‌ترین راه برای توسعه یک رابط کاربری کارآمد، استفاده از ویجت Maps JavaScript API Place Autocomplete (Legacy) ، ویجت Places SDK برای اندروید Place Autocomplete (Legacy) یا کنترل رابط کاربری Places SDK برای iOS Place Autocomplete (Legacy) است.
از همان ابتدا درک درستی از فیلدهای داده ضروری Place Autocomplete (Legacy) پیدا کنید.
فیلدهای Location biasing و location restriction اختیاری هستند اما می‌توانند تأثیر قابل توجهی بر عملکرد تکمیل خودکار داشته باشند.
از مدیریت خطا استفاده کنید تا مطمئن شوید که برنامه شما در صورت بروز خطا توسط API، به طور مناسب از رده خارج می‌شود.
مطمئن شوید که برنامه شما وقتی هیچ انتخابی وجود ندارد، کار می‌کند و به کاربران راهی برای ادامه ارائه می‌دهد.

بهترین شیوه‌های بهینه‌سازی هزینه

بهینه‌سازی هزینه پایه

برای بهینه‌سازی هزینه استفاده از سرویس تکمیل خودکار مکان (Legacy)، از ماسک‌های فیلد در ویجت‌های جزئیات مکان (Legacy) و تکمیل خودکار مکان (Legacy) استفاده کنید تا فقط فیلدهای داده مکان مورد نیاز خود را برگردانید.

بهینه‌سازی پیشرفته هزینه

پیاده‌سازی برنامه‌ریزی‌شده‌ی قابلیت تکمیل خودکار مکان (Legacy) را برای دسترسی به قیمت‌گذاری Per Request و درخواست نتایج Geocoding API در مورد مکان انتخاب‌شده به جای Place Details (Legacy) در نظر بگیرید. قیمت‌گذاری Per Request همراه با Geocoding API در صورت برآورده شدن هر دو شرط زیر، مقرون‌به‌صرفه‌تر از قیمت‌گذاری Per Session (مبتنی بر session) است:

اگر فقط به طول/عرض جغرافیایی یا آدرس مکان انتخاب شده کاربر نیاز دارید، API مربوط به Geocoding این اطلاعات را با هزینه‌ای کمتر از فراخوانی Place Details (Legacy) ارائه می‌دهد.
اگر کاربران یک پیش‌بینی تکمیل خودکار را در بین میانگین چهار درخواست پیش‌بینی تکمیل خودکار (قدیمی) یا کمتر انتخاب کنند، قیمت‌گذاری بر اساس درخواست ممکن است مقرون‌به‌صرفه‌تر از قیمت‌گذاری بر اساس جلسه باشد.

برای کمک به انتخاب پیاده‌سازی Place Autocomplete (Legacy) که متناسب با نیازهای شما باشد، برگه‌ای را که با پاسخ شما به سوال زیر مطابقت دارد، انتخاب کنید.

آیا درخواست شما به اطلاعات دیگری غیر از آدرس و طول و عرض جغرافیایی پیش‌بینی انتخاب شده نیاز دارد؟

بله، نیاز به توضیحات بیشتر دارد

از تکمیل خودکار مکان مبتنی بر جلسه (Legacy) به همراه جزئیات مکان (Legacy) استفاده کنید.
از آنجایی که برنامه شما به جزئیات مکان (Legacy) مانند نام مکان، وضعیت کسب و کار یا ساعات کاری نیاز دارد، پیاده‌سازی شما از قابلیت تکمیل خودکار مکان (Legacy) باید از یک توکن جلسه ( به صورت برنامه‌نویسی یا ساخته شده در ویجت‌های جاوا اسکریپت ، اندروید یا iOS ) در هر جلسه به علاوه SKUهای داده مکان‌های قابل اجرا، بسته به فیلدهای داده مکانی که درخواست می‌کنید، استفاده کند. ¹

پیاده‌سازی ویجت
مدیریت جلسه به طور خودکار در ویجت‌های جاوا اسکریپت ، اندروید یا iOS تعبیه شده است. این شامل درخواست‌های تکمیل خودکار مکان (Legacy) و درخواست جزئیات مکان (Legacy) در پیش‌بینی انتخاب شده می‌شود. حتماً پارامتر fields را مشخص کنید تا مطمئن شوید که فقط فیلدهای داده مکانی مورد نیاز خود را درخواست می‌کنید.

پیاده‌سازی برنامه‌ریزی‌شده
از یک توکن جلسه با درخواست‌های تکمیل خودکار مکان (Legacy) خود استفاده کنید. هنگام درخواست جزئیات مکان (Legacy) در مورد پیش‌بینی انتخاب شده، پارامترهای زیر را وارد کنید:

شناسه مکان از پاسخ تکمیل خودکار مکان (قدیمی)
توکن جلسه مورد استفاده در درخواست تکمیل خودکار مکان (Legacy)
پارامتر fields که فیلدهای داده مکانی مورد نیاز شما را مشخص می‌کند

خیر، فقط به آدرس و موقعیت مکانی نیاز دارد

بسته به عملکرد استفاده از قابلیت تکمیل خودکار مکان (Legacy)، API مربوط به ژئوکدینگ می‌تواند گزینه مقرون‌به‌صرفه‌تری نسبت به جزئیات مکان (Legacy) برای برنامه شما باشد. کارایی تکمیل خودکار مکان (Legacy) هر برنامه بسته به اینکه کاربران چه اطلاعاتی را وارد می‌کنند، برنامه در کجا استفاده می‌شود و اینکه آیا بهترین شیوه‌های بهینه‌سازی عملکرد پیاده‌سازی شده‌اند یا خیر، متفاوت است.

برای پاسخ به سوال زیر، قبل از انتخاب پیش‌بینی Place Autocomplete (Legacy) در برنامه خود، تجزیه و تحلیل کنید که کاربر به طور متوسط چند کاراکتر تایپ می‌کند.

آیا کاربران شما به طور متوسط در چهار درخواست یا کمتر، پیش‌بینی تکمیل خودکار مکان (Legacy) را انتخاب می‌کنند؟

بله

تکمیل خودکار مکان (Legacy) را به صورت برنامه‌نویسی شده و بدون توکن‌های جلسه پیاده‌سازی کنید و API مربوط به Geocoding را روی پیش‌بینی مکان انتخاب شده فراخوانی کنید.
API ژئوکدینگ آدرس‌ها و مختصات طول و عرض جغرافیایی را ارائه می‌دهد. انجام چهار درخواست تکمیل خودکار مکان (Legacy) - به ازای هر درخواست به علاوه یک فراخوانی API ژئوکدینگ در مورد پیش‌بینی مکان انتخاب شده، کمتر از هزینه تکمیل خودکار مکان به ازای هر جلسه (Legacy) به ازای هر جلسه است. ¹

در نظر داشته باشید که از بهترین شیوه‌های عملکرد استفاده کنید تا به کاربران خود کمک کنید پیش‌بینی مورد نظر خود را با تعداد کاراکترهای کمتری دریافت کنند.

خیر

از تکمیل خودکار مکان مبتنی بر جلسه (Legacy) به همراه جزئیات مکان (Legacy) استفاده کنید.
از آنجایی که میانگین تعداد درخواست‌هایی که انتظار دارید قبل از انتخاب پیش‌بینی تکمیل خودکار مکان (Legacy) توسط کاربر انجام شود، از هزینه قیمت‌گذاری Per Session بیشتر است، پیاده‌سازی شما از تکمیل خودکار مکان (Legacy) باید از یک توکن جلسه برای هر دو درخواست تکمیل خودکار مکان (Legacy) و درخواست جزئیات مکان (Legacy) مرتبط در هر Session استفاده کند. ¹

پیاده‌سازی ویجت
مدیریت جلسه به طور خودکار در ویجت‌های جاوا اسکریپت ، اندروید یا iOS تعبیه شده است. این شامل درخواست‌های تکمیل خودکار مکان (Legacy) و درخواست جزئیات مکان (Legacy) در پیش‌بینی انتخاب شده می‌شود. حتماً پارامتر fields را مشخص کنید تا مطمئن شوید که فقط فیلدهای داده‌های پایه را درخواست می‌کنید.

شناسه مکان از پاسخ تکمیل خودکار مکان (قدیمی)
توکن جلسه مورد استفاده در درخواست تکمیل خودکار مکان (Legacy)
پارامتر fields که فیلدهای داده پایه مانند آدرس و هندسه را مشخص می‌کند

درخواست‌های تکمیل خودکار (قدیمی) را به تعویق بیندازید
شما می‌توانید از استراتژی‌هایی مانند به تأخیر انداختن درخواست تکمیل خودکار مکان (Legacy) تا زمانی که کاربر سه یا چهار کاراکتر اول را تایپ کرده باشد، استفاده کنید تا برنامه شما درخواست‌های کمتری ارسال کند. به عنوان مثال، ایجاد درخواست‌های تکمیل خودکار مکان (Legacy) برای هر کاراکتر پس از تایپ کاراکتر سوم توسط کاربر به این معنی است که اگر کاربر هفت کاراکتر تایپ کند و سپس پیش‌بینی‌ای را انتخاب کند که شما برای آن یک درخواست API Geocoding ارسال می‌کنید، هزینه کل برای 4 تکمیل خودکار مکان (Legacy) به ازای هر درخواست + Geocoding خواهد بود. ¹

اگر تأخیر در درخواست‌ها می‌تواند میانگین درخواست‌های برنامه‌نویسی شما را به زیر چهار برساند، می‌توانید از راهنمایی‌های مربوط به تکمیل خودکار مکان (Legacy) با پیاده‌سازی API Geocoding پیروی کنید. توجه داشته باشید که تأخیر در درخواست‌ها می‌تواند توسط کاربری که انتظار دارد با هر ضربه کلید جدید، پیش‌بینی‌ها را ببیند، به عنوان تأخیر تلقی شود.

استفاده از بهترین شیوه‌های عملکرد را در نظر بگیرید تا به کاربران خود کمک کنید پیش‌بینی مورد نظر خود را با تعداد کاراکترهای کمتری دریافت کنند.

برای اطلاع از هزینه‌ها، به لیست قیمت‌های پلتفرم نقشه‌های گوگل مراجعه کنید.

بهترین شیوه‌های عملکرد

دستورالعمل‌های زیر روش‌های بهینه‌سازی عملکرد تکمیل خودکار مکان (Legacy) را شرح می‌دهند:

محدودیت‌های کشور، سوگیری موقعیت مکانی و (برای پیاده‌سازی‌های برنامه‌نویسی‌شده) ترجیح زبان را به پیاده‌سازی تکمیل خودکار مکان (Legacy) خود اضافه کنید. ترجیح زبان با ویجت‌ها لازم نیست زیرا آن‌ها ترجیحات زبان را از مرورگر یا دستگاه تلفن همراه کاربر انتخاب می‌کنند.
اگر قابلیت تکمیل خودکار مکان (Legacy) با نقشه همراه باشد، می‌توانید مکان را بر اساس نمای نقشه تنظیم کنید.
در شرایطی که کاربر یکی از پیش‌بینی‌های Place Autocomplete (Legacy) را انتخاب نمی‌کند، عموماً به این دلیل که هیچ‌کدام از این پیش‌بینی‌ها آدرس-نتیجه مورد نظر نیستند، می‌توانید از ورودی اصلی کاربر برای تلاش جهت دریافت نتایج مرتبط‌تر استفاده مجدد کنید:
- اگر انتظار دارید کاربر فقط اطلاعات آدرس را وارد کند، از ورودی اصلی کاربر در فراخوانی Geocoding API استفاده مجدد کنید.
- اگر انتظار دارید کاربر برای یک مکان خاص با نام یا آدرس جستجو کند، از درخواست Find Place (Legacy) استفاده کنید. اگر نتایج فقط در یک منطقه خاص مورد انتظار است، از location biasing استفاده کنید.
سناریوهای دیگری که در آنها بهتر است به API ژئوکدینگ برگردیم عبارتند از:
- کاربرانی که آدرس‌های فرعی، مانند آدرس‌های واحدها یا آپارتمان‌های خاص در یک ساختمان را وارد می‌کنند. برای مثال، آدرس چکی "Stroupežnického 3191/17, Praha" در تکمیل خودکار مکان (Legacy) پیش‌بینی جزئی ارائه می‌دهد.
- کاربرانی که آدرس‌هایی با پیشوندهای قطعه جاده‌ای مانند «خیابان بیست و نهم، شماره ۲۳-۳۰، کوئینز» در شهر نیویورک یا «بزرگراه کامهامها، شماره ۴۷-۳۸۰، کانئوهه» در جزیره کائوآئی در هاوایی وارد می‌کنند.

عیب‌یابی

اگرچه طیف گسترده‌ای از خطاها ممکن است رخ دهد، اما اکثر خطاهایی که احتمالاً برنامه شما با آنها مواجه می‌شود، معمولاً ناشی از خطاهای پیکربندی (به عنوان مثال، استفاده از کلید API اشتباه یا پیکربندی نادرست کلید API) یا خطاهای سهمیه‌بندی (برنامه شما از سهمیه خود فراتر رفته است) هستند. برای اطلاعات بیشتر در مورد سهمیه‌بندی، به محدودیت‌های استفاده مراجعه کنید.

خطاهایی که در استفاده از کنترل‌های تکمیل خودکار رخ می‌دهند، در تابع فراخوانی onActivityResult() برگردانده می‌شوند. برای دریافت پیام وضعیت نتیجه، Autocomplete.getStatus() را فراخوانی کنید.

محل تکمیل خودکار با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.

یک ابزارک تکمیل خودکار اضافه کنید

گزینه ۱: جاسازی یک AutocompleteSupportFragment

افزودن AutocompleteSupportFragment به یک فعالیت

اضافه کردن یک PlaceSelectionListener به یک اکتیویتی

کاتلین

جاوا

گزینه ۲: استفاده از یک اینتنت برای اجرای اکتیویتی تکمیل خودکار

یک هدف تکمیل خودکار ایجاد کنید

کاتلین

جاوا

ثبت یک فراخوانی برای نتیجه intent

کاتلین

جاوا

دریافت پیش‌بینی‌های مکانی به صورت برنامه‌نویسی‌شده

کاتلین

جاوا

توکن‌های جلسه

محدود کردن نتایج تکمیل خودکار

نتایج سوگیری به یک منطقه خاص

کاتلین

جاوا

محدود کردن نتایج به یک منطقه خاص

کاتلین

جاوا

فیلتر کردن نتایج بر اساس نوع مکان یا نوع مجموعه

کاتلین

جاوا

کاتلین

جاوا

کاتلین

جاوا

فیلتر کردن نتایج بر اساس کشور

کاتلین

جاوا

محدودیت‌های استفاده

نمایش انتساب‌ها در برنامه شما

بهینه‌سازی تکمیل خودکار مکان (Legacy)

بهترین شیوه‌های بهینه‌سازی هزینه

بهینه‌سازی هزینه پایه

بهینه‌سازی پیشرفته هزینه

بله، نیاز به توضیحات بیشتر دارد

خیر، فقط به آدرس و موقعیت مکانی نیاز دارد

بله

خیر

بهترین شیوه‌های عملکرد

عیب‌یابی

محل تکمیل خودکار