نسل بعدی Places SDK برای Android اکنون با انتشار Places SDK برای Android (جدید) در دسترس است.

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

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

پلتفرم را انتخاب کنید: سرویس وب جاوا اسکریپت اندروید iOS

سرویس تکمیل خودکار در 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، Places SDK برای ویجت تکمیل خودکار Android، یا Places SDK برای کنترل رابط کاربری خودکار iOS است.
از همان ابتدا درک درستی از فیلدهای داده تکمیل خودکار مکان ضروری ایجاد کنید.
فیلدهای بایاس موقعیت و محدودیت مکان اختیاری هستند اما می توانند تأثیر قابل توجهی بر عملکرد تکمیل خودکار داشته باشند.
از مدیریت خطا استفاده کنید تا مطمئن شوید اگر API خطایی را برمی‌گرداند، برنامه شما به خوبی کاهش می‌یابد.
مطمئن شوید که برنامه شما وقتی انتخابی وجود ندارد کنترل می کند و راهی برای ادامه به کاربران ارائه می دهد.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

بله

Place Autocomplete را به صورت برنامه‌نویسی و بدون نشانه‌های جلسه اجرا کنید و API Geocoding را در پیش‌بینی مکان انتخاب‌شده فراخوانی کنید.
Geocoding API آدرس ها و مختصات طول و عرض جغرافیایی را برای هر درخواست 0.005 دلار ارائه می دهد. ایجاد چهار درخواست تکمیل خودکار مکان - به ازای هر درخواست 0.01132 دلار هزینه دارد، بنابراین هزینه کل چهار درخواست به اضافه یک تماس API جغرافیایی در مورد پیش بینی مکان انتخابی 0.01632 دلار خواهد بود که کمتر از قیمت تکمیل خودکار در هر جلسه 0.017 دلار در هر جلسه است. ¹

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

خیر

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

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

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

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

هزینه های ذکر شده در اینجا به USD هستند. لطفاً برای اطلاعات کامل قیمت به صفحه صورت‌حساب پلتفرم Google Maps مراجعه کنید.

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

دستورالعمل‌های زیر راه‌هایی را برای بهینه‌سازی عملکرد تکمیل خودکار مکان توضیح می‌دهند:

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

عیب یابی

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

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