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

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

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

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

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

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

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

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

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

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

گزینه 1: یک 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 قرار دهید.
اگر از قطعه Autocomplete استفاده می کنید و باید روی onActivityResult لغو کنید، باید super.onActivityResult فراخوانی کنید، در غیر این صورت قطعه به درستی کار نخواهد کرد.

یک PlaceSelectionListener به یک فعالیت اضافه کنید

PlaceSelectionListener بازگرداندن مکان را در پاسخ به انتخاب کاربر کنترل می کند. کد زیر ایجاد یک مرجع به قطعه و افزودن یک شنونده به 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.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، تکمیل خودکار را راه‌اندازی کند.

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

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

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

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

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

برای نتیجه intent یک تماس برگشتی ثبت کنید

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

کاتلین

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

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

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

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

نشانه های جلسه

نشانه‌های جلسه، مراحل پرس و جو و انتخاب یک جستجوی تکمیل خودکار کاربر را در یک جلسه مجزا برای اهداف صورت‌حساب گروه‌بندی می‌کنند. جلسه زمانی شروع می شود که کاربر شروع به تایپ یک پرس و جو می کند، و با انتخاب مکان به پایان می رسد. هر جلسه می تواند چندین پرس و جو داشته باشد و به دنبال آن یک مکان انتخاب شود. پس از پایان جلسه، رمز دیگر معتبر نیست. برنامه شما باید برای هر جلسه یک توکن جدید تولید کند. ما استفاده از نشانه‌های جلسه را برای تمام جلسات تکمیل خودکار برنامه‌ریزی شده توصیه می‌کنیم (زمانی که قطعه‌ای را جاسازی می‌کنید، یا با استفاده از یک intent، تکمیل خودکار را راه‌اندازی می‌کنید، 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() را فراخوانی کنید و حداکثر پنج مقدار نوع از جدول 1 و جدول 2 که در Place Types نشان داده شده است را مشخص کنید. مقادیر نوع با ثابت های PlaceTypes تعریف می شوند.
setTypesFilter() را فراخوانی کنید و یک مجموعه نوع از جدول 3 نشان داده شده در Place Types را مشخص کنید. مقادیر مجموعه با ثابت های 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() تماس بگیرید تا کد کشور را تنظیم کنید. سپس، فیلتر را به قطعه یا intent منتقل کنید. کشورها باید به عنوان کد کشوری دو کاراکتری و سازگار با ISO 3166-1 Alpha-2 ارسال شوند.

مثال کد زیر فراخوانی setCountries() در AutocompleteSupportFragment را نشان می دهد تا فیلتری تنظیم شود که فقط نتایج را در کشورهای مشخص شده برمی گرداند.

کاتلین

    autocompleteFragment.setCountries("AU", "NZ")

جاوا

    autocompleteFragment.setCountries("AU", "NZ");

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

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

محدودیت نرخ 6000 QPM (درخواست در دقیقه) است. این به عنوان مجموع درخواست های سمت مشتری و سمت سرور برای همه برنامه ها با استفاده از اعتبار یک پروژه محاسبه می شود.

اسناد را در برنامه خود نمایش دهید

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

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

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

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

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

سریع‌ترین راه برای توسعه یک رابط کاربری کارآمد، استفاده از ابزارک Maps JavaScript API Place Autocomplete (Legacy) ، ابزارک Places SDK برای Android Place Autocomplete (Legacy) یا Places SDK برای iOS کنترل UI مکان تکمیل خودکار (Legacy) است.
از همان ابتدا درک درستی از فیلدهای داده تکمیل خودکار مکان (میراث) ایجاد کنید.
فیلدهای بایاس موقعیت و محدودیت مکان اختیاری هستند اما می توانند تأثیر قابل توجهی بر عملکرد تکمیل خودکار داشته باشند.
از مدیریت خطا استفاده کنید تا مطمئن شوید اگر API خطایی را برمی‌گرداند، برنامه شما به خوبی کاهش می‌یابد.
مطمئن شوید که برنامه شما وقتی انتخابی وجود ندارد کنترل می کند و راهی برای ادامه به کاربران ارائه می دهد.

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

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

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

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

به منظور دسترسی به قیمت هر درخواست و درخواست نتایج Geocoding API در مورد مکان انتخابی به جای جزئیات مکان (میراث) اجرای برنامه‌ای Place Autocomplete (Legacy) را در نظر بگیرید. قیمت گذاری هر درخواست جفت شده با Geocoding API مقرون به صرفه تر از قیمت گذاری در هر جلسه (مبتنی بر جلسه) است اگر هر دو شرایط زیر رعایت شود:

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

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

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

بله، به جزئیات بیشتری نیاز دارد

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

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

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

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

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

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

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

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

بله

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

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

خیر

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

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

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

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

برای هزینه‌ها، فهرست‌های قیمت پلتفرم نقشه‌های Google را ببینید.

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

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

محدودیت‌های کشور، سوگیری موقعیت و اولویت زبان (برای اجرای برنامه‌ای) را به پیاده‌سازی تکمیل خودکار مکان (میراث) خود اضافه کنید. اولویت زبان با ویجت ها مورد نیاز نیست زیرا آنها ترجیحات زبان را از مرورگر کاربر یا دستگاه تلفن همراه انتخاب می کنند.
اگر تکمیل خودکار مکان (میراث) با نقشه همراه باشد، می‌توانید مکان را با درگاه نمای نقشه سوگیری کنید.
در شرایطی که کاربر یکی از پیش‌بینی‌های تکمیل خودکار مکان (میراث) را انتخاب نمی‌کند، معمولاً به دلیل اینکه هیچ یک از آن پیش‌بینی‌ها آدرس نتیجه مورد نظر نیستند، می‌توانید از ورودی اصلی کاربر برای تلاش برای دریافت نتایج مرتبط‌تر دوباره استفاده کنید:
- اگر انتظار دارید کاربر فقط اطلاعات آدرس را وارد کند، از ورودی اصلی کاربر در تماس با API جغرافیایی استفاده مجدد کنید.
- اگر انتظار دارید کاربر برای یک مکان خاص با نام یا آدرس پرس و جوها را وارد کند، از درخواست Find Place (Legacy) استفاده کنید. اگر نتایج فقط در یک منطقه خاص مورد انتظار است، از بایاس مکان استفاده کنید.
سناریوهای دیگر زمانی که بهتر است به API Geocoding برگردید عبارتند از:
- کاربرانی که آدرس‌های فرعی را وارد می‌کنند، مانند آدرس‌های واحدها یا آپارتمان‌های خاص در یک ساختمان. به عنوان مثال، آدرس چک "Stroupežnického 3191/17, Praha" یک پیش بینی جزئی در تکمیل خودکار مکان (میراث) به دست می دهد.
- کاربرانی که آدرس‌هایی را با پیشوندهای بخش جاده مانند «23-30 29th, Queens» در شهر نیویورک یا «47-380 Kamehameha Hwy, Kaneohe» در جزیره Kauai در هاوایی وارد می‌کنند.

عیب یابی

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

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

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

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

گزینه 1: یک AutocompleteSupportFragment را جاسازی کنید

AutocompleteSupportFragment را به یک فعالیت اضافه کنید

یک PlaceSelectionListener به یک فعالیت اضافه کنید

کاتلین

جاوا

گزینه 2: از یک intent برای راه اندازی فعالیت تکمیل خودکار استفاده کنید

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

کاتلین

جاوا

برای نتیجه intent یک تماس برگشتی ثبت کنید

کاتلین

جاوا

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

کاتلین

جاوا

نشانه های جلسه

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

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

کاتلین

جاوا

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

کاتلین

جاوا

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

کاتلین

جاوا

کاتلین

جاوا

کاتلین

جاوا

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

کاتلین

جاوا

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

اسناد را در برنامه خود نمایش دهید

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

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

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

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

بله، به جزئیات بیشتری نیاز دارد

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

بله

خیر

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

عیب یابی

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