تکمیل خودکار جا (قدیمی)

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

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

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

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

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

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

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

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

برای افزودن AutocompleteSupportFragment به برنامه‌تان، مراحل زیر را دنبال کنید:

1. تکه‌ای به طرح‌بندی XML فعالیتتان اضافه کنید.
2. شنونده‌ای به فعالیت یا قطعه‌تان اضافه کنید.

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

برای افزودن AutocompleteSupportFragment به فعالیت، قطعه جدیدی به چیدمان XML اضافه کنید. برای مثال:

<fragment android:id="@+id/autocomplete_fragment"
  android:layout_width="match_parent"
  android:layout_height="wrap_content"
  android:name="com.google.android.libraries.places.widget.AutocompleteSupportFragment"
  />

• به‌طور پیش‌فرض، این تکه‌کد حاشیه یا پس‌زمینه‌ای ندارد. برای ارائه ظاهر دیداری یکسان، قطعه را در عنصر چیدمان دیگری مثل CardView لانه کنید.
• اگر از تکه‌کد «تکمیل خودکار» استفاده می‌کنید و باید onActivityResult را ملغی کنید، باید super.onActivityResult را فراخوانی کنید، درغیراین‌صورت تکه‌کد به‌درستی کار نخواهد کرد.

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

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

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

      

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

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

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

1. از Autocomplete.IntentBuilder برای ایجاد قصد استفاده کنید و حالت Autocomplete موردنظر را ارسال کنید.
2. راه‌انداز نتیجه فعالیت را تعریف کنید registerForActivityResult که می‌تواند برای راه‌اندازی هدف و مدیریت پیش‌بینی مکان انتخاب‌شده کاربر در نتیجه استفاده شود.

ایجاد قصد تکمیل خودکار

مثال زیر از 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.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);

      

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

ثبت کردن پاسخ تماس برای نتیجه هدف

برای دریافت اعلان وقتی کاربر مکانی را انتخاب کرده است، registerForActivityResult() راه‌اندازی را تعریف کنید که فعالیت را راه‌اندازی می‌کند و همچنین نتیجه را همان‌طور که در مثال زیر نشان داده شده است مدیریت می‌کند. اگر کاربر پیش‌بینی‌ای را انتخاب کرده باشد، در هدف موجود در شیء نتیجه ارائه خواهد شد. ازآنجایی‌که هدف توسط 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 را با پارامترهای زیر ارسال کند:

• الزامی: رشته 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 در آینده استفاده کنید. برای کسب اطلاعات بیشتر درباره شناسه‌های مکان در «کیت توسعه نرم‌افزار مکان‌ها، ویژه Android»، به جزئیات مکان مراجعه کنید. برای اطلاعات کلی درباره شناسه‌های مکان، به نمای کلی شناسه مکان مراجعه کنید.
• getPlaceTypes() فهرست انواع مکان‌های مرتبط با این مکان را برمی‌گرداند.
• getDistanceMeters() فاصله مستقیم را به متر بین این مکان و مبدأ مشخص‌شده در درخواست برمی‌گرداند.

کدهای جلسه

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

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

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

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

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

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

• برای ترجیح دادن نتایج در منطقه تعریف‌شده، با 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() تماس بگیرید و حداکثر پنج مقدار نوع را از جدول ۱ و جدول ۲ نشان‌داده‌شده در انواع مکان مشخص کنید. مقادیر نوع توسط ثابت‌ها در PlaceTypes تعریف می‌شوند.

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

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

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

      

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

      

حدود استفاده

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

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

نمایش ارجاع‌ها در برنامه

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

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

بهینه‌سازی «تکمیل خودکار جا (قدیمی)»

این بخش روال‌های مطلوبی را شرح می‌دهد که به شما کمک می‌کند بیشترین بهره را از سرویس «تکمیل خودکار جا (قدیمی)» ببرید.

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

• سریع‌ترین راه برای توسعه میانای کاربر فعال استفاده از ابزاره «تکمیل خودکار جا» (قدیمی) در Maps JavaScript API، ابزاره «تکمیل خودکار جا» (قدیمی) در Places SDK for Android، یا کنترل میانای کاربر «تکمیل خودکار جا» (قدیمی) در Places SDK for iOS است.
• از همان ابتدا، فیلدهای داده «تکمیل خودکار جا» (قدیمی) را درک کنید.
• فیلدهای سوگیری مکان و محدودیت مکان اختیاری هستند اما می‌توانند تأثیر قابل‌توجهی بر عملکرد تکمیل خودکار داشته باشند.
• از مدیریت خطا استفاده کنید تا مطمئن شوید اگر میانای برنامه‌سازی کاربردی خطا برگرداند، برنامه شما به‌خوبی تنزل می‌یابد.
• مطمئن شوید که برنامه‌تان درصورت عدم انتخاب، عملکرد مناسبی داشته باشد و به کاربران امکان ادامه دادن بدهد.

روال‌های مطلوب بهینه‌سازی هزینه

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

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

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

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

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

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

روال‌های مطلوب عملکرد

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

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

سوگیری مکانی

با ارسال پارامتر location و پارامتر radius، نتایج را به منطقه مشخصی متمایل کنید. این کار به «تکمیل خودکار جا» (قدیمی) دستور می‌دهد که نمایش نتایج را در منطقه تعریف‌شده ترجیح دهد. نتایج خارج از منطقه تعریف‌شده ممکن است همچنان نمایش داده شود. می‌توانید از پارامتر includedRegionCodes برای فیلتر کردن نتایج استفاده کنید تا فقط مکان‌های داخل کشور مشخص‌شده نشان داده شود.

مکان محدودکننده

با ارسال پارامتر locationRestriction، نتایج را به منطقه مشخصی محدود کنید.

همچنین می‌توانید با افزودن پارامتر strictbounds نتایج را به منطقه‌ای که با location و پارامتر radius تعریف شده است محدود کنید. این به «تکمیل خودکار جا» (قدیمی) دستور می‌دهد فقط نتایج درون آن منطقه را برگرداند.

عیب‌یابی

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

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