إكمال تلقائي (جديد)

تعرض خدمة "الإكمال التلقائي" (جديدة) توقعات للأماكن استجابةً لطلب يتضمّن سلسلة بحث نصية وحدودًا جغرافية تتحكّم في مساحة البحث. يمكن أن تتطابق ميزة الإكمال التلقائي مع الكلمات الكاملة والسلاسل الفرعية من الإدخال، ما يؤدي إلى تحديد أسماء الأماكن والعناوين والرموز الإضافية. يمكن لتطبيقك إرسال طلبات البحث أثناء كتابة المستخدم، وذلك لتقديم توقعات فورية بشأن الأماكن وطلبات البحث.

على سبيل المثال، يمكنك طلب الإكمال التلقائي باستخدام سلسلة كإدخال تتضمّن جزءًا من إدخال المستخدم، مثل "بيتزا صقلية"، مع حصر منطقة البحث في سان فرانسيسكو، كاليفورنيا. تحتوي الاستجابة بعد ذلك على قائمة بتوقّعات الأماكن التي تطابق سلسلة البحث ومنطقة البحث، مثل المطعم الذي يحمل اسم "مطبخ بيتزا صقلية". تم تصميم توقعات الأماكن التي يتم عرضها لمساعدة المستخدم في اختيار المكان المطلوب. يمكنك إرسال طلب تفاصيل المكان (جديد) للحصول على مزيد من المعلومات حول أي من توقعات الأماكن التي تم عرضها.

يمكنك دمج وظيفة "الإكمال التلقائي (جديد)" في تطبيقك بطريقتَين رئيسيتَين:

• إضافة أداة Place Autocomplete: توفّر هذه الأداة تجربة إكمال تلقائي جاهزة للاستخدام من خلال فئة PlaceAutocomplete التي تعرض عبارات مقترَحة أثناء كتابة المستخدم.
• الحصول على توقّعات بشأن الأماكن آليًا: يمكنك طلب البيانات من واجهة برمجة التطبيقات مباشرةً لاسترداد التوقّعات وعرضها في واجهة مستخدم مخصّصة.

إضافة أداة الإكمال التلقائي للأماكن

لتوفير تجربة متسقة في ميزة الإكمال التلقائي لأسماء الأماكن بسهولة أكبر، يمكنك إضافة أداة الإكمال التلقائي لأسماء الأماكن إلى تطبيقك. توفّر الأداة واجهة مخصّصة بملء الشاشة تعالج إدخالات المستخدم وتعرض توقعات حول الأماكن للمستخدم مع عرض عناصر AutocompletePrediction للتطبيق. يمكنك بعد ذلك إرسال طلب تفاصيل المكان (جديد) للحصول على معلومات إضافية حول أي من التوقعات حول الأماكن.

كما هو الحال عند الحصول على توقعات حول الأماكن آليًا، تتيح لك أداة Place Autocomplete استخدام رموز الجلسات لتجميع طلبات الإكمال التلقائي في جلسة لأغراض الفوترة. يمكنك تمرير رمز مميّز للجلسة عند إنشاء الغرض الخاص بالأداة من خلال استدعاء setAutocompleteSessionToken(). إذا لم تقدّم رمزًا مميزًا للجلسة، ستنشئ لك الأداة رمزًا مميزًا يمكنك الوصول إليه من خلال استدعاء getSessionTokenFromIntent(). لمزيد من المعلومات عن استخدام رموز الجلسات، راجِع مقالة لمحة عن رموز الجلسات.

لإضافة أداة "الإكمال التلقائي للأماكن" إلى تطبيقك، اتّبِع الخطوات التالية:

1. (اختياري) حدِّد رمزًا مميزًا للجلسة. إذا لم تقدّم رمزًا مميّزًا للجلسة، ستنشئ لك الأداة رمزًا.

2. حدِّد autocompleteIntent مع المَعلمات المطلوبة ورمز الجلسة.

3. حدِّد ActivityResultLauncher لـ StartActivityForResult. سيتعامل مشغّل التطبيق هذا مع النتيجة التي تم إرجاعها من نشاط الإكمال التلقائي.

4. تعامَل مع النتيجة في دالة معاودة الاتصال الخاصة بـ ActivityResultLauncher. يتضمّن ذلك استخراج AutocompletePrediction وAutocompleteSessionToken (في حال لم تقدّمها)، والتعامل مع الأخطاء، وإجراء طلب fetchPlace() اختياريًا للحصول على تفاصيل إضافية حول مكان ما.

5. تشغيل الغرض باستخدام placeAutocompleteActivityResultLauncher

توضّح النماذج التالية كيفية إضافة أداة Place Autocomplete باستخدام كل من Kotlin وJava:

// 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:

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. يوضّح المثال أدناه عملية استدعاء كاملة للدالة 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());
        })
    );

ردود الإكمال التلقائي (جديدة)

تعرض واجهة برمجة التطبيقات FindAutocompletePredictionsResponse في Task. يحتوي FindAutocompletePredictionsResponse على قائمة تضم ما يصل إلى خمسة عناصر AutocompletePrediction تمثّل الأماكن المتوقّعة. قد تكون القائمة فارغة إذا لم يكن هناك مكان معروف يتطابق مع طلب البحث ومعايير الفلتر.

يمكنك استدعاء الطرق التالية لاسترداد تفاصيل المكان لكل مكان متوقّع:

• تعرض السمة getFullText(CharacterStyle) النص الكامل لوصف المكان. هذا هو مزيج من النص الأساسي والثانوي. مثال: "برج إيفل، شارع أناتول فرانس، باريس، فرنسا". بالإضافة إلى ذلك، يتيح لك هذا الإجراء تمييز أقسام الوصف التي تتطابق مع البحث باستخدام نمط من اختيارك، وذلك باستخدام CharacterStyle. المَعلمة CharacterStyle اختيارية. اضبط القيمة على null إذا لم تكن بحاجة إلى أي تمييز.
• تعرض السمة getPrimaryText(CharacterStyle) النص الرئيسي الذي يصف مكانًا. عادةً ما يكون هذا هو اسم المكان. أمثلة: "برج إيفل" و "123 شارع بيت".
• تعرض السمة getSecondaryText(CharacterStyle) النص الفرعي لوصف مكان. ويكون ذلك مفيدًا، على سبيل المثال، كسطر ثانٍ عند عرض توقّعات الإكمال التلقائي. أمثلة: "Avenue Anatole France, Paris, France" و "Sydney, New South Wales".
• تعرض getPlaceId() معرّف المكان المتوقّع. معرّف المكان هو معرّف نصي يحدّد مكانًا بشكل فريد، ويمكنك استخدامه لاسترداد الكائن Place مرة أخرى لاحقًا. لمزيد من المعلومات حول معرّفات الأماكن في خدمة "الإكمال التلقائي"، يُرجى الاطّلاع على تفاصيل المكان (جديد). للحصول على معلومات عامة حول معرّفات الأماكن، راجِع نظرة عامة حول معرّف المكان.
• تعرض getTypes() قائمة بأنواع الأماكن المرتبطة بهذا المكان.
• تعرض getDistanceMeters() المسافة بين هذا المكان والمصدر المحدّد في الطلب، وذلك بخط مستقيم وبالأمتار.

المعلمات المطلوبة

• طلب البحث

  سلسلة النص المطلوب البحث عنها. حدِّد الكلمات الكاملة والسلاسل الفرعية وأسماء الأماكن والعناوين ورموز المواقع المفتوحة. تعرض خدمة "الإكمال التلقائي (جديدة)" نتائج مطابقة محتملة استنادًا إلى هذه السلسلة، وترتّب النتائج حسب مدى صلتها بموضوع البحث.

  لضبط مَعلمة طلب البحث، استدعِ طريقة setQuery() عند إنشاء العنصر FindAutocompletePredictionsRequest.

المعلمات الاختيارية

• الأنواع الأساسية

  قائمة تضمّ ما يصل إلى خمس قيم من النوع type من الجدول أ أو الجدول ب، وتُستخدَم لفلترة الأماكن التي يتم عرضها في الردّ. يجب أن يتطابق المكان مع إحدى قيم النوع الأساسي المحدّدة ليتم تضمينه في الردّ.

  يمكن أن يكون للمكان نوع أساسي واحد فقط من الأنواع المرتبطة به في الجدول (أ) أو الجدول (ب). على سبيل المثال، قد يكون النوع الأساسي "mexican_restaurant" أو "steak_house".

  يتم رفض الطلب مع ظهور الخطأ INVALID_REQUEST في الحالات التالية:

  • تم تحديد أكثر من خمسة أنواع.
  • يتم تحديد أي أنواع غير معروفة.

  لضبط مَعلمة الأنواع الأساسية، استدعِ طريقة setTypesFilter() عند إنشاء الكائن FindAutocompletePredictionsRequest.

• البلدان

  لا تضمِّن سوى النتائج من قائمة البلدان المحدّدة، والتي يتم تحديدها كقائمة تتضمّن ما يصل إلى 15 قيمة لنطاق المستوى الأعلى الذي يتم ترميزه حسب البلد (ccTLD) مؤلّفة من حرفين. في حال عدم تضمينها، لن يتم تطبيق أي قيود على الرد. على سبيل المثال، لتحديد المناطق بألمانيا وفرنسا:

  إذا حدّدت كلاً من locationRestriction وincludedRegionCodes، ستظهر النتائج في المنطقة المشتركة بين الإعدادَين.

  لضبط مَعلمة البلدان، استدعِ طريقة setCountries() عند إنشاء العنصر FindAutocompletePredictionsRequest.

• إزاحة الإدخال

  إزاحة حرف Unicode المستندة إلى الصفر والتي تشير إلى موضع المؤشر في طلب البحث يمكن أن يؤثّر موضع المؤشر في التوقّعات التي يتم عرضها. إذا كان الحقل فارغًا، يتم ضبط القيمة التلقائية على طول طلب البحث.

  لضبط مَعلمة إزاحة الإدخال، استدعِ طريقة setInputOffset() عند إنشاء الكائن FindAutocompletePredictionsRequest.

• تحيّز الموقع الجغرافي أو القيود المفروضة على الموقع الجغرافي

  يمكنك تحديد تحيّز الموقع الجغرافي أو قيود الموقع الجغرافي، ولكن ليس كليهما، لتحديد منطقة البحث. يمكنك اعتبار قيد الموقع الجغرافي بمثابة تحديد المنطقة التي يجب أن تقع النتائج ضمنها، بينما يمكنك اعتبار تحيّز الموقع الجغرافي بمثابة تحديد المنطقة التي يجب أن تكون النتائج قريبة منها. ويكمن الاختلاف الرئيسي في أنّه مع ميزة "التحيّز حسب الموقع الجغرافي"، قد يتم عرض نتائج من خارج المنطقة المحدّدة.

  • الانحياز حسب الموقع الجغرافي

    تحدّد هذه السمة منطقة للبحث. ويُستخدَم هذا الموقع الجغرافي كعامل تحيّز وليس كقيد، لذا قد يتم عرض نتائج من خارج المنطقة المحدّدة.

    لضبط مَعلمة تحيّز الموقع الجغرافي، استدعِ الإجراء setLocationBias() عند إنشاء العنصر FindAutocompletePredictionsRequest.

  • قيود الموقع الجغرافي

    تحدّد هذه السمة منطقة للبحث. لا يتم عرض نتائج خارج المنطقة المحدّدة.

    لضبط مَعلمة تقييد الموقع الجغرافي، استدعِ طريقة setLocationRestriction() عند إنشاء العنصر FindAutocompletePredictionsRequest.

  حدِّد منطقة التحيز أو التقييد حسب الموقع الجغرافي كإطار عرض مستطيل أو كدائرة.

  • يتم تحديد الدائرة من خلال نقطة مركزية ونصف قطر بالأمتار. يجب أن يتراوح نصف القطر بين 0.0 و50000.0، بما في ذلك هذان الرقمَان. القيمة التلقائية هي 0.0. بالنسبة إلى قيود الموقع الجغرافي، يجب ضبط النطاق الجغرافي على قيمة أكبر من 0.0. وفي حال عدم توفّرها، لن يعرض الطلب أي نتائج.

  • المستطيل هو إطار عرض لخطوط الطول والعرض، ويتم تمثيله كنقطتَي low وhigh متقابلتَين قطريًا. يُعدّ إطار العرض منطقة مغلقة، ما يعني أنّه يشمل حدوده. يجب أن تتراوح حدود خط العرض بين 90- و90 درجة شاملة، ويجب أن تتراوح حدود خط الطول بين 180- و180 درجة شاملة:

    • إذا كان low = high، يتألف إطار العرض من تلك النقطة الواحدة.
    • إذا كانت قيمة low.longitude أكبر من قيمة high.longitude، يكون نطاق خط الطول معكوسًا (أي أنّ إطار العرض يتقاطع مع خط الطول 180 درجة).
    • إذا كانت low.longitude = -180 درجة وhigh.longitude = 180 درجة، ستشمل نافذة العرض جميع خطوط الطول.
    • إذا كانت low.longitude = 180 درجة وhigh.longitude = -180 درجة، يكون نطاق خط الطول فارغًا.

    يجب ملء الحقلَين low وhigh، ولا يمكن أن يكون المربع الممثَّل فارغًا. يؤدي عرض نافذة فارغة إلى حدوث خطأ.

• الأصل

  نقطة البداية التي يتم منها احتساب المسافة المستقيمة إلى الوجهة (يتم الوصول إليها باستخدام getDistanceMeters()). إذا تم حذف هذه القيمة، لن يتم عرض المسافة المستقيمة. يجب تحديدها على النحو التالي: إحداثيات خطوط الطول والعرض:

  لضبط مَعلمة المصدر، استدعِ طريقة setOrigin() عند إنشاء العنصر FindAutocompletePredictionsRequest.

• رمز المنطقة

  تمثّل هذه السمة رمز المنطقة المستخدَم لتنسيق الردّ، بما في ذلك تنسيق العنوان، ويتم تحديدها كقيمة مكوّنة من حرفَين ccTLD ("نطاق المستوى الأعلى"). معظم رموز نطاقات المستوى الأعلى لرمز البلد تتطابق مع رموز ISO 3166-1، مع بعض الاستثناءات البارزة. على سبيل المثال، نطاق المستوى الأعلى لرمز البلد في المملكة المتحدة هو "uk" (.co.uk)، بينما رمز ISO 3166-1 هو "gb" (وهو يشير تقنيًا إلى الكيان "المملكة المتحدة لبريطانيا العظمى وأيرلندا الشمالية").

  إذا حدّدت رمز منطقة غير صالح، ستعرض واجهة برمجة التطبيقات رسالة خطأ INVALID_ARGUMENT. يمكن أن تؤثّر المَعلمة في النتائج استنادًا إلى القانون الساري.

  لضبط مَعلمة رمز المنطقة، استدعِ طريقة setRegionCode() عند إنشاء العنصر FindAutocompletePredictionsRequest.

• الرمز المميز للجلسة

  رموز الجلسات هي سلاسل من الأحرف والأرقام ينشئها المستخدمون لتتبُّع طلبات الإكمال التلقائي (الجديدة)، سواء كانت الطلبات تتم من خلال الأداة أو بطريقة آلية، ويتم تصنيفها على أنّها "جلسات". تستخدم ميزة "الإكمال التلقائي" رموز الجلسات المميزة لتجميع مراحل طلب البحث والاختيار في عملية بحث الإكمال التلقائي التي يجريها المستخدم في جلسة منفصلة لأغراض الفوترة. تبدأ الجلسة عندما يبدأ المستخدم في كتابة طلب بحث، وتنتهي عندما يختار مكانًا. يمكن أن تتضمّن كل جلسة طلبات بحث متعددة، يليها اختيار مكان واحد. بعد انتهاء الجلسة، لن يكون الرمز المميز صالحًا، ويجب أن ينشئ تطبيقك رمزًا مميزًا جديدًا لكل جلسة. ننصحك باستخدام رموز مميّزة للجلسات في جميع جلسات الإكمال التلقائي الآلية (عند تضمين جزء أو تشغيل الإكمال التلقائي باستخدام هدف، تتولّى واجهة برمجة التطبيقات ذلك تلقائيًا).

  تستخدِم خدمة "الإكمال التلقائي" AutocompleteSessionToken لتحديد كل جلسة. يجب أن يمرِّر تطبيقك رمزًا مميزًا جديدًا للجلسة عند بدء كل جلسة جديدة، ثم يمرِّر الرمز المميز نفسه مع معرّف المكان في طلب fetchPlace() اللاحق لاسترداد "تفاصيل المكان" للمكان الذي اختاره المستخدم.

  لضبط مَعلمة رمز الجلسة، استدعِ الطريقة setSessionToken() عند إنشاء العنصر FindAutocompletePredictionsRequest.

  لمزيد من المعلومات، يُرجى الاطّلاع على رموز الجلسات المميزة.

أمثلة على الإكمال التلقائي (جديد)

استخدام قيود الموقع الجغرافي وميزة "تفضيل الموقع الجغرافي"

تستخدم ميزة "الإكمال التلقائي" (الجديدة) ميزة "تحديد الموقع الجغرافي حسب عنوان IP" تلقائيًا للتحكّم في منطقة البحث. باستخدام ميزة "تفضيل عنوان IP"، تستخدم واجهة برمجة التطبيقات عنوان IP الخاص بالجهاز لتفضيل النتائج. يمكنك اختياريًا استخدام قيود الموقع الجغرافي أو تحيّز الموقع الجغرافي، ولكن ليس كليهما، لتحديد منطقة البحث.

يحدّد قيد الموقع الجغرافي المنطقة المطلوب البحث فيها. لا يتم عرض النتائج خارج المنطقة المحدّدة. يستخدم المثال التالي قيود الموقع الجغرافي لحصر الطلب في قيود موقع جغرافي دائرية بنطاق 5,000 متر متمركزة في سان فرانسيسكو:

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

استخدام الأنواع الأساسية

استخدِم المَعلمة primary types لحصر النتائج من طلب بحث على نوع معيّن كما هو موضّح في الجدول أ والجدول ب. يمكنك تحديد مصفوفة تتضمّن ما يصل إلى خمس قيم. في حال الحذف، يتم عرض جميع الأنواع.

يحدّد المثال التالي سلسلة طلب بحث "كرة القدم" ويستخدم المَعلمة primary types لحصر النتائج على المؤسسات من النوع "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 في الطلب، والمحدّدة كإحداثيات خطوط الطول والعرض، تتضمّن واجهة برمجة التطبيقات في الردّ المسافة المستقيمة من نقطة الأصل إلى الوجهة (يمكن الوصول إليها باستخدام getDistanceMeters()). يضبط هذا المثال نقطة الأصل على وسط سان فرانسيسكو:

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.
• التعرّف على حقول البيانات الأساسية لخاصية "الإكمال التلقائي" (جديد) من البداية
• حقلَي "تفضيل الموقع الجغرافي" و"حظر الموقع الجغرافي" اختياريان، ولكن يمكن أن يكون لهما تأثير كبير في أداء ميزة "الإكمال التلقائي".
• استخدِم ميزة معالجة الأخطاء للتأكّد من أنّ تطبيقك يتراجع بشكل سليم في حال عرض واجهة برمجة التطبيقات رسالة خطأ.
• تأكَّد من أنّ تطبيقك يتعامل مع الحالات التي لا يتم فيها تحديد أي خيار، وأنّه يوفّر للمستخدمين طريقة لمواصلة الاستخدام.

أفضل الممارسات لتحسين التكلفة

تحسين التكلفة الأساسية

لتحسين تكلفة استخدام خدمة "الإكمال التلقائي" (الإصدار الجديد)، استخدِم أقنعة الحقول في أدوات "تفاصيل المكان" (الإصدار الجديد) و"الإكمال التلقائي" (الإصدار الجديد) لعرض حقول البيانات التي تحتاج إليها فقط في "الإكمال التلقائي" (الإصدار الجديد).

تحسين التكلفة بشكلٍ متقدّم

ننصحك بتنفيذ ميزة "الإكمال التلقائي (جديدة)" آليًا للوصول إلى رمز التخزين التعريفي: أسعار طلبات الإكمال التلقائي وطلب نتائج Geocoding API حول المكان المحدّد بدلاً من "تفاصيل المكان (جديدة)". يكون التسعير لكل طلب مقترنًا بواجهة برمجة التطبيقات Geocoding API أكثر فعالية من حيث التكلفة من التسعير لكل جلسة (استنادًا إلى الجلسة) في حال استيفاء الشرطَين التاليَين:

• إذا كنت تحتاج فقط إلى خطوط الطول والعرض أو عنوان المكان الذي اختاره المستخدم، تقدّم Geocoding API هذه المعلومات بتكلفة أقل من طلب Place Details (New).
• إذا اختار المستخدمون نتيجة بحث مقترَحة من ميزة "الإكمال التلقائي" في غضون أربعة طلبات أو أقل من ميزة "الإكمال التلقائي (جديد)"، قد يكون التسعير لكل طلب أكثر فعالية من حيث التكلفة من التسعير لكل جلسة.

هل يتطلّب تطبيقك أي معلومات أخرى غير العنوان وخط العرض/خط الطول الخاص بالتوقّع المحدّد؟

أفضل الممارسات المتعلّقة بالأداء

توضّح الإرشادات التالية طرقًا لتحسين أداء ميزة "الإكمال التلقائي (جديد)":

• أضِف قيود البلدان وتحسين الموقع الجغرافي وخيار اللغة المفضّلة (في عمليات التنفيذ الآلية) إلى عملية تنفيذ ميزة "الإكمال التلقائي (جديد)". لا حاجة إلى تحديد اللغة المفضّلة عند استخدام الأدوات المصغّرة لأنّها تستند إلى اللغة المفضّلة المحدّدة في متصفّح المستخدم أو جهازه الجوّال.
• إذا كانت ميزة "الإكمال التلقائي (جديدة)" مصحوبة بخريطة، يمكنك تحديد الموقع الجغرافي حسب إطار عرض الخريطة.
• في الحالات التي لا يختار فيها المستخدم إحدى عبارات البحث المقترَحة من ميزة "الإكمال التلقائي (جديد)"، وذلك عادةً لأنّ أيًا من عبارات البحث المقترَحة هذه ليس عنوان النتيجة المطلوب، يمكنك إعادة استخدام إدخال المستخدم الأصلي لمحاولة الحصول على نتائج أكثر صلة:
  • إذا كنت تتوقّع أن يدخل المستخدم معلومات العنوان فقط، أعِد استخدام إدخال المستخدم الأصلي في طلب إلى Geocoding API.
  • إذا كنت تتوقّع أن يُدخل المستخدم طلبات بحث عن مكان معيّن حسب الاسم أو العنوان، استخدِم طلب "تفاصيل المكان (جديد)". إذا كنت تتوقّع ظهور النتائج في منطقة معيّنة فقط، استخدِم تحسين النتائج حسب الموقع الجغرافي.
  تشمل السيناريوهات الأخرى التي يُنصح فيها بالرجوع إلى Geocoding API ما يلي:
  • المستخدمون الذين يدخلون عناوين أماكن فرعية، مثل عناوين وحدات أو شقق معيّنة داخل مبنى على سبيل المثال، يؤدي إدخال العنوان التشيكي "Stroupežnického 3191/17, Praha" إلى ظهور عبارة بحث مقترَحة جزئية في ميزة "الإكمال التلقائي (الجديدة)".
  • المستخدمون الذين يدخلون عناوين تتضمّن بادئات مقاطع طرق، مثل "23-30 29th St, Queens" في مدينة نيويورك أو "47-380 Kamehameha Hwy, Kaneohe" في جزيرة كاواي في هاواي

تفضيل المواقع الجغرافية

يمكنك توجيه النتائج إلى منطقة محدّدة من خلال تمرير المَعلمة location والمَعلمة radius. يوجّه هذا الخيار ميزة "الإكمال التلقائي (جديد)" إلى تفضيل عرض النتائج ضمن المنطقة المحدّدة. قد يستمر عرض النتائج خارج المنطقة المحدّدة. يمكنك استخدام المَعلمة components لفلترة النتائج وعرض الأماكن الواقعة ضمن بلد محدّد فقط.

تقييد الموقع الجغرافي

لحصر النتائج في منطقة محدّدة، أضِف المَعلمة locationRestriction.

يمكنك أيضًا حصر النتائج بالمنطقة المحدّدة بواسطة location والمَعلمة radius، وذلك من خلال إضافة المَعلمة locationRestriction. يوجّه هذا الإعداد ميزة "الإكمال التلقائي (الجديدة)" لعرض نتائج فقط ضمن تلك المنطقة.