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

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

برای مثال، شما با استفاده از رشته‌ای که شامل بخشی از ورودی کاربر، "Sicilian piz" است و ناحیه جستجو به سانفرانسیسکو، کالیفرنیا محدود شده است، تکمیل خودکار را فراخوانی می‌کنید. سپس پاسخ شامل فهرستی از پیش‌بینی‌های مکان است که با رشته جستجو و ناحیه جستجو مطابقت دارند، مانند رستورانی به نام "Sicilian Pizza Kitchen". پیش‌بینی‌های مکان برگردانده شده به گونه‌ای طراحی شده‌اند که به کاربر ارائه شوند تا در انتخاب مکان مورد نظر به او کمک کنند. می‌توانید برای دریافت اطلاعات بیشتر در مورد هر یک از پیش‌بینی‌های مکان برگردانده شده، درخواست جزئیات مکان (جدید) ارسال کنید.

شما می‌توانید قابلیت تکمیل خودکار (جدید) را به دو روش اصلی در برنامه خود ادغام کنید:

• ویجت Place Autocomplete را اضافه کنید : یک تجربه تکمیل خودکار جستجو را از طریق کلاس PlaceAutocomplete ارائه می‌دهد که پیش‌بینی‌ها را همزمان با تایپ کاربر نمایش می‌دهد.
• دریافت پیش‌بینی‌های مکان به صورت برنامه‌نویسی‌شده : مستقیماً API را فراخوانی کنید تا پیش‌بینی‌ها را بازیابی کرده و آن‌ها را در یک رابط کاربری سفارشی نمایش دهید.

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

برای ارائه راحت‌تر یک تجربه تکمیل خودکار مکان، می‌توانید ویجت تکمیل خودکار مکان را به برنامه خود اضافه کنید. این ویجت یک رابط کاربری اختصاصی و تمام صفحه ارائه می‌دهد که ورودی کاربر را مدیریت می‌کند و پیش‌بینی‌های مکان را به کاربر نمایش می‌دهد و در عین حال اشیاء AutocompletePrediction به برنامه برمی‌گرداند. سپس می‌توانید یک درخواست جزئیات مکان (جدید) ارسال کنید تا اطلاعات بیشتری در مورد هر یک از پیش‌بینی‌های مکان دریافت کنید.

همانند زمانی که پیش‌بینی‌های مکان را به صورت برنامه‌نویسی دریافت می‌کنید ، ویجت Place Autocomplete به شما امکان می‌دهد از توکن‌های جلسه برای گروه‌بندی درخواست‌های تکمیل خودکار در جلسه برای اهداف صدور صورتحساب استفاده کنید. می‌توانید هنگام ایجاد اینتنت برای ویجت، با فراخوانی setAutocompleteSessionToken() یک توکن جلسه ارسال کنید. اگر توکن جلسه‌ای ارائه ندهید، ویجت یکی برای شما ایجاد می‌کند که می‌توانید با فراخوانی getSessionTokenFromIntent() به آن دسترسی پیدا کنید. برای اطلاعات بیشتر در مورد استفاده از توکن‌های جلسه، به About Session Tokens مراجعه کنید.

برای افزودن ویجت Place Autocomplete به برنامه خود:

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

2. یک autocompleteIntent با پارامترهای دلخواه و توکن جلسه خود تعریف کنید.

3. یک ActivityResultLauncher برای StartActivityForResult تعریف کنید. این لانچر، نتیجه‌ی برگردانده شده از autocomplete activity را مدیریت خواهد کرد.

4. نتیجه را در فراخوانی ActivityResultLauncher مدیریت کنید. این شامل استخراج AutocompletePrediction و AutocompleteSessionToken (اگر خودتان آن را ارائه نکرده‌اید)، مدیریت خطاها و در صورت تمایل ایجاد یک درخواست fetchPlace() برای دریافت جزئیات بیشتر در مورد یک مکان است.

5. اینتنت را با استفاده از placeAutocompleteActivityResultLauncher اجرا کنید.

نمونه‌های زیر نحوه‌ی افزودن ویجت Place Autocomplete را با استفاده از کاتلین و جاوا نشان می‌دهند:

// Provide the API key that has enabled "Places API (New)" in the Google Cloud Console.
Places.initializeWithNewPlacesApiEnabled(/* Context= */ context, /* API Key= */ key)

// Optional, create a session token for Autocomplete request and the followup FetchPlace request.
val sessionToken: AutocompleteSessionToken = AutocompleteSessionToken.newInstance()

val autocompleteIntent: Intent =
    PlaceAutocomplete.createIntent(this) {
        // ... provide input params for origin, countries, types filter ...
        setAutocompleteSessionToken(sessionToken)
    }

val placeAutocompleteActivityResultLauncher: ActivityResultLauncher<Intent> =
    registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult ->
        val intent = result.data
        if (intent != null && result.resultCode == PlaceAutocompleteActivity.RESULT_OK) {
            // get prediction object
            val prediction: AutocompletePrediction? =
                PlaceAutocomplete.getPredictionFromIntent(intent!!)

            // get session token
            val sessionToken: AutocompleteSessionToken? =
                PlaceAutocomplete.getSessionTokenFromIntent(intent!!)

            // create PlacesClient to make FetchPlace request (optional)
            val placesClient: PlacesClient = Places.createClient(this)
            val response =
                placesClient.awaitFetchPlace(prediction.placeId, Field.DISPLAY_NAME)
                {
                    sessionToken = sessionToken // optional
                }
        }
    }

// Launch Activity
placeAutocompleteActivityResultLauncher.launch(autocompleteIntent)

// Provide the API key that has enabled "Places API (New)" in the Google Cloud Console.
Places.initializeWithNewPlacesApiEnabled(/* Context= */ context, /* API Key= */ key);

// Optional, create a session token for Autocomplete request and the followup FetchPlace request
AutocompleteSessionToken sessionToken = AutocompleteSessionToken.newInstance();

Intent autocompleteIntent =
    new PlaceAutocomplete.IntentBuilder()
        // ... set input params for origin, countries, types filter ...
        .setSessionToken(sessionToken) // optional
        .build(this);

ActivityResultLauncher<Intent> placeAutocompleteActivityResultLauncher =
    registerForActivityResult(
        new ActivityResultContracts.StartActivityForResult(),
        new ActivityResultCallback<ActivityResult>() {
            @Override
            public void onActivityResult(ActivityResult result) {
                Intent intent = result.getData();
                if (result.getResultCode() == PlaceAutocompleteActivity.RESULT_OK) {
                    // get prediction object
                    AutocompletePrediction prediction =
                        PlaceAutocomplete.getPredictionFromIntent(
                            Preconditions.checkNotNull(intent));

                    // get session token
                    AutocompleteSessionToken sessionToken =
                        PlaceAutocomplete.getSessionTokenFromIntent(
                            Preconditions.checkNotNull(intent));

                    // create PlacesClient to make FetchPlace request (optional)
                    PlacesClient placesClient = Places.createClient(this);
                    FetchPlaceRequest request =
                        FetchPlaceRequest.builder(prediction.getPlaceId(),
                            Arrays.asList(Field.DISPLAY_NAME))
                            .setSessionToken(sessionToken).build();
                    Task<FetchPlaceResponse> task = placesClient.fetchPlace(request);
                }
            }
        }
    );

// Launch Activity
placeAutocompleteActivityResultLauncher.launch(autocompleteIntent);

سفارشی کردن تم

هنگام نمونه‌سازی یک تجربه تکمیل خودکار، می‌توانید یک تم مشخص کنید که هر یک از ویژگی‌های سبک پیش‌فرض را لغو کند. می‌توانید رنگ‌ها، تایپوگرافی، فاصله‌گذاری، حاشیه‌ها و گوشه‌های کامپوننت تکمیل خودکار مکان خود را سفارشی کنید. پیش‌فرض PlacesMaterialTheme است. هر ویژگی تم که لغو نشود، از سبک‌های پیش‌فرض استفاده می‌کند.

شما می‌توانید لغو قالب را در …/res/values/themes.xml تعریف کنید. برای مثال:

<?xml version="1.0" encoding="utf-8"?>
<resources>
  <style name="BrandedTheme" parent="PlacesMaterialTheme">
    <!-- Color tokens. -->
    <item name="placesColorOnNeutralContainer">#5300e8</item>
    <item name="placesColorOnNeutralContainerVariant">#ee6002</item>
    ...

    <!-- Typography tokens. -->
    <item name="placesTextAppearanceTitleLarge">@style/PlacesTextAppearance</item>
    <item name="placesTextAppearanceBodyMedium">@style/PlacesTextAppearance</item>
    ...

    <!-- Spacing tokens. -->
    <item name="placesSpacingSmall">6dp</item>
    <item name="placesSpacingMedium">12dp</item>
    ...

    <!-- Attribution tokens. -->
    <item name="placesColorAttributionLightTheme">white</item>
    <item name="placesColorAttributionDarkTheme">black</item>
  </style>
</resources>

سپس می‌توانید با فراخوانی setAutocompleteUiCustomization به استایل‌های override شده ارجاع دهید:

ActivityResultLauncher<Intent> placeAutocompleteActivityResultLauncher =
  registerForActivityResult(
    new ActivityResultContracts.StartActivityForResult(),
    new ActivityResultCallback<ActivityResult>() {
      @Override
      public void onActivityResult(ActivityResult result) {
        Intent intent = result.getData();
        if (intent != null) {
          AutocompletePrediction prediction =
            PlaceAutocomplete.getPredictionFromIntent(intent);
          AutocompleteSessionToken sessionToken =
            PlaceAutocomplete.getSessionTokenFromIntent(intent);
          Status status = PlaceAutocomplete.getResultStatusFromIntent(intent);
          ...
        }
      }
    }
  );

Intent placeAutocompleteIntent =
  new PlaceAutocomplete.IntentBuilder()
    .setInitialQuery("INSERT_QUERY_TEXT")
    .setOrigin(new LatLng(10.0, 10.0))
    ...

    .setAutocompleteUiCustomization(
      AutocompleteUiCustomization.builder()
        .listItemIcon(AutocompleteUiIcon.noIcon())
        .listDensity(AutocompleteListDensity.MULTI_LINE)
        .theme(R.style.BrandedTheme)
        .build())
  .build(this);

placeAutocompleteActivityResultLauncher.launch(placeAutocompleteIntent);

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

برنامه شما می‌تواند با فراخوانی PlacesClient.findAutocompletePredictions() و ارسال یک شیء FindAutocompletePredictionsRequest ، فهرستی از نام مکان‌ها و/یا آدرس‌های پیش‌بینی‌شده را از API تکمیل خودکار دریافت کند. مثال زیر یک فراخوانی کامل PlacesClient.findAutocompletePredictions() را نشان می‌دهد.

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();
LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);
final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Sicilian piz")
            .setRegionCode("ES")
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

پاسخ‌های تکمیل خودکار (جدید)

این API یک FindAutocompletePredictionsResponse در یک Task برمی‌گرداند. FindAutocompletePredictionsResponse شامل فهرستی از حداکثر پنج شیء AutocompletePrediction است که مکان‌های پیش‌بینی‌شده را نشان می‌دهند. اگر هیچ مکان شناخته‌شده‌ای مطابق با پرس‌وجو و معیارهای فیلتر وجود نداشته باشد، این فهرست می‌تواند خالی باشد.

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

• getFullText(CharacterStyle) متن کامل توضیحات یک مکان را برمی‌گرداند. این ترکیبی از متن اصلی و فرعی است. مثال: " برج ایفل، خیابان آناتول فرانس، پاریس، فرانسه ". علاوه بر این، این متد به شما امکان می‌دهد بخش‌هایی از توضیحات را که با جستجو مطابقت دارند، با استفاده CharacterStyle و با سبک دلخواه خود، هایلایت کنید. پارامتر CharacterStyle اختیاری است. اگر نیازی به هایلایت کردن ندارید، آن را روی null تنظیم کنید.
• getPrimaryText(CharacterStyle) متن اصلی توصیف کننده یک مکان را برمی‌گرداند. این متن معمولاً نام مکان است. مثال‌ها: « برج ایفل » و « خیابان پیت ۱۲۳ ».
• getSecondaryText(CharacterStyle) متن فرعی توصیف یک مکان را برمی‌گرداند. این متن، برای مثال، به عنوان خط دوم هنگام نمایش پیش‌بینی‌های تکمیل خودکار مفید است. مثال‌ها: « خیابان آناتول فرانس، پاریس، فرانسه » و « سیدنی، نیو ساوت ولز ».
• getPlaceId() شناسه مکان مکان پیش‌بینی‌شده را برمی‌گرداند. شناسه مکان یک شناسه متنی است که به‌طور منحصربه‌فرد یک مکان را مشخص می‌کند و می‌توانید بعداً برای بازیابی شیء Place از آن استفاده کنید. برای اطلاعات بیشتر در مورد شناسه‌های مکان در تکمیل خودکار، به جزئیات مکان (جدید) مراجعه کنید. برای اطلاعات کلی در مورد شناسه‌های مکان، به نمای کلی شناسه مکان مراجعه کنید.
• getTypes() لیستی از انواع مکان‌های مرتبط با این مکان را برمی‌گرداند.
• getDistanceMeters() فاصله‌ی مستقیم بین این مکان و مبدا مشخص شده در درخواست را بر حسب متر برمی‌گرداند.

پارامترهای مورد نیاز

• پرس و جو

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

  برای تنظیم پارامتر پرس‌وجو، هنگام ساخت شیء FindAutocompletePredictionsRequest متد setQuery() را فراخوانی کنید.

پارامترهای اختیاری

• انواع اولیه

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

  یک مکان فقط می‌تواند یک نوع اصلی از انواع جدول A یا جدول B مرتبط با آن داشته باشد. برای مثال، نوع اصلی ممکن است "mexican_restaurant" یا "steak_house" باشد.

  درخواست با خطای INVALID_REQUEST رد می‌شود اگر:

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

  برای تنظیم پارامتر انواع اصلی، هنگام ساخت شیء FindAutocompletePredictionsRequest ، متد setTypesFilter() را فراخوانی کنید.

• کشورها

  فقط نتایجی از فهرست کشورهای مشخص‌شده را لحاظ کنید، که به صورت فهرستی با حداکثر ۱۵ ccTLD ("دامنه سطح بالا") با مقادیر دو کاراکتری مشخص شده‌اند. در صورت حذف، هیچ محدودیتی برای پاسخ اعمال نمی‌شود. به عنوان مثال، برای محدود کردن مناطق به آلمان و فرانسه:

  اگر هر دو locationRestriction و includedRegionCodes را مشخص کنید، نتایج در ناحیه تقاطع این دو تنظیم قرار می‌گیرند.

  برای تنظیم پارامتر countries، هنگام ساخت شیء FindAutocompletePredictionsRequest ، متد setCountries() را فراخوانی کنید.

• افست ورودی

  آفست کاراکتر یونیکد مبتنی بر صفر که موقعیت مکان‌نما را در پرس‌وجو نشان می‌دهد. موقعیت مکان‌نما می‌تواند بر پیش‌بینی‌های برگشتی تأثیر بگذارد. اگر خالی باشد، به طور پیش‌فرض طول پرس‌وجو را در نظر می‌گیرد.

  برای تنظیم پارامتر آفست ورودی، هنگام ساخت شیء FindAutocompletePredictionsRequest متد setInputOffset() را فراخوانی کنید.

• سوگیری مکانی یا محدودیت مکانی

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

  • سوگیری مکانی

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

    برای تنظیم پارامتر بایاس موقعیت مکانی، هنگام ساخت شیء FindAutocompletePredictionsRequest ، متد setLocationBias() را فراخوانی کنید.

  • محدودیت مکان

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

    برای تنظیم پارامتر محدودیت مکان، هنگام ساخت شیء FindAutocompletePredictionsRequest ، متد setLocationRestriction() را فراخوانی کنید.

  ناحیه بایاس مکان یا محدودیت مکان را به عنوان یک نمای مستطیلی یا به عنوان یک دایره مشخص کنید.

  • یک دایره با نقطه مرکزی و شعاع بر حسب متر تعریف می‌شود. شعاع باید بین 0.0 تا 50000.0 باشد، که شامل همه می‌شود. مقدار پیش‌فرض 0.0 است. برای محدودیت مکان، باید شعاع را روی مقداری بزرگتر از 0.0 تنظیم کنید. در غیر این صورت، درخواست هیچ نتیجه‌ای برنمی‌گرداند.

  • مستطیل، یک دریچه دید طول و عرض جغرافیایی است که به صورت دو نقطه low و high که به صورت مورب روبروی هم قرار دارند، نمایش داده می‌شود. یک دریچه دید، یک منطقه بسته در نظر گرفته می‌شود، به این معنی که شامل مرز خود نیز می‌شود. محدوده‌های عرض جغرافیایی باید بین ۹۰- تا ۹۰ درجه و محدوده‌های طول جغرافیایی باید بین ۱۸۰- تا ۱۸۰ درجه باشند:

    • اگر low = high ، نمای دید از آن نقطه واحد تشکیل شده است.
    • اگر low.longitude > high.longitude ، محدوده طول جغرافیایی معکوس می‌شود (صفحه نمایش از خط طول جغرافیایی ۱۸۰ درجه عبور می‌کند).
    • اگر low.longitude = -180 درجه و high.longitude = 180 درجه باشد، صفحه نمایش شامل تمام طول‌های جغرافیایی می‌شود.
    • اگر low.longitude = 180 درجه و high.longitude = -180 درجه باشد، محدوده طول جغرافیایی خالی است.

    هر دو پارامتر low و high باید پر شوند و کادر نمایش داده شده نمی‌تواند خالی باشد. یک viewport خالی منجر به خطا می‌شود.

• مبدا

  نقطه مبدا که از آن فاصله مستقیم تا مقصد محاسبه می‌شود (با استفاده از getDistanceMeters() قابل دسترسی است). اگر این مقدار حذف شود، فاصله مستقیم بازگردانده نمی‌شود. باید به عنوان مختصات عرض و طول جغرافیایی مشخص شود:

  برای تنظیم پارامتر origin، هنگام ساخت شیء FindAutocompletePredictionsRequest ، متد setOrigin() را فراخوانی کنید.

• کد منطقه

  کد منطقه‌ای مورد استفاده برای قالب‌بندی پاسخ، شامل قالب‌بندی آدرس، که به عنوان یک مقدار دو کاراکتری ccTLD ("دامنه سطح بالا") مشخص شده است. اکثر کدهای ccTLD با کدهای ISO 3166-1 یکسان هستند، با برخی استثنائات قابل توجه. به عنوان مثال، ccTLD بریتانیا "uk" (.co.uk) است در حالی که کد ISO 3166-1 آن "gb" است (از نظر فنی برای موجودیت "پادشاهی متحده بریتانیای کبیر و ایرلند شمالی").

  اگر کد منطقه نامعتبری را مشخص کنید، API خطای INVALID_ARGUMENT را برمی‌گرداند. این پارامتر می‌تواند بر اساس قانون مربوطه بر نتایج تأثیر بگذارد.

  برای تنظیم پارامتر کد منطقه، هنگام ساخت شیء FindAutocompletePredictionsRequest متد setRegionCode() را فراخوانی کنید.

• توکن جلسه

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

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

  برای تنظیم پارامتر توکن جلسه، هنگام ساخت شیء FindAutocompletePredictionsRequest ، متد setSessionToken() را فراخوانی کنید.

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

مثال‌های تکمیل خودکار (جدید)

از محدودیت مکان و سوگیری مکان استفاده کنید

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

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

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Amoeba")
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

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

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Amoeba")
            .setLocationBias(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

استفاده از انواع اولیه

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

مثال زیر یک رشته پرس‌وجو از نوع "Soccer" را مشخص می‌کند و از پارامتر انواع اصلی برای محدود کردن نتایج به فروشگاه‌های از نوع "sporting_goods_store" استفاده می‌کند:

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

final List<Place.Field> primaryTypes = Arrays.asList("sporting_goods_store");

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Soccer")
            .setIncludedPrimaryTypes(primaryTypes)
            .setLocationBias(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

اگر پارامتر انواع اصلی را حذف کنید، نتایج ممکن است شامل موسساتی از نوعی باشد که ممکن است شما نخواهید، مانند "athletic_field" .

از مبدا استفاده کنید

وقتی پارامتر origin را در درخواست وارد می‌کنید، که به صورت مختصات طول و عرض جغرافیایی مشخص شده است، API فاصله مستقیم از مبدا تا مقصد را در پاسخ لحاظ می‌کند (با استفاده از getDistanceMeters() قابل دسترسی است). این مثال origin را روی مرکز سانفرانسیسکو تنظیم می‌کند:

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Amoeba")
            .setOrigin(center)
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

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

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

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

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

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

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

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

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

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

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

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

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

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

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

سوگیری مکانی

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

محدود کردن موقعیت مکانی

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

همچنین می‌توانید با اضافه کردن پارامتر locationRestriction ، نتایج را به ناحیه‌ای که توسط location و پارامتر radius تعریف شده است، محدود کنید. این به Autocomplete (جدید) دستور می‌دهد که فقط نتایج درون آن ناحیه را برگرداند.