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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

حصر الوصول إلى الموقع الجغرافي

يمكنك حصر النتائج على منطقة محدّدة من خلال تمرير المَعلمة locationRestriction.

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