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

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

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

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

طلب البحث

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

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

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

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

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

يمكن أن يكون للمكان نوع أساسي واحد فقط من الأنواع الواردة في الجدول "أ" أو الجدول "ب" المرتبطة به. على سبيل المثال، قد يكون النوع الأساسي "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). تتطابق معظم رموز ccTLD مع رموز ISO 3166-1، مع بعض الاستثناءات الملحوظة. على سبيل المثال، نطاق المستوى الأعلى الذي يمثّل رمز البلد للمملكة المتحدة هو "uk"‏ (‎.co.uk)، في حين أنّ رمز ISO 3166-1 هو "gb" (من الناحية الفنية لكيان "المملكة المتحدة لبريطانيا العظمى وأيرلندا الشمالية").

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

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

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

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

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

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

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

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

استخدام ميزتَي "تقييد الموقع الجغرافي" و"الانحياز للموقع الجغرافي"

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

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

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

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

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

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

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

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

الإكمال التلقائي المستنِد إلى الجلسة (جديد) مع تفاصيل المكان (جديد)

استخدام ميزة "الإكمال التلقائي (جديد)" المستندة إلى الجلسة مع ميزة "تفاصيل المكان (جديد)"
بما أنّ تطبيقك يتطلّب استخدام واجهة برمجة التطبيقات Place Details (New)، مثل اسم المكان أو حالة النشاط التجاري أو ساعات العمل، يجب أن يستخدم تنفيذك لواجهة برمجة التطبيقات Autocomplete (New) رمزًا مميزًا للجلسة (برمجيًا أو مضمّنًا في تطبيقات JavaScript أو Android أو iOS المصغّرة) لكل جلسة بالإضافة إلى رموز التخزين التعريفية السارية في Places، استنادًا إلى حقول بيانات المكان التي تطلبها.¹

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

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

1. رقم تعريف المكان من ردّ "الإكمال التلقائي (الجديد)"
2. الرمز المميّز للجلسة المستخدَم في طلب الإكمال التلقائي (الجديد)
3. المَعلمة fields التي تحدّد حقول بيانات ميزة "الإكمال التلقائي (جديد)" التي تحتاج إليها

ميزة "الإكمال التلقائي" (الجديدة) لكل طلب مع Geocoding API

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

ننصحك باتّباع أفضل الممارسات المتعلّقة بالأداء لمساعدة المستخدمين في الحصول على عبارة البحث المقترَحة التي يبحثون عنها باستخدام عدد أقل من الأحرف.

ميزة "الإكمال التلقائي (جديد)" المستندة إلى الجلسة للتطبيقات التي تستخدم العناوين فقط

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

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

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

1. رقم تعريف المكان من ردّ "الإكمال التلقائي (الجديد)"
2. الرمز المميّز للجلسة المستخدَم في طلب الإكمال التلقائي (الجديد)
3. المَعلمة fields التي تحدّد الحقول مثل العنوان والشكل الهندسي

ننصحك بتأخير طلبات "الإكمال التلقائي (جديد)"
يمكنك استخدام استراتيجيات مثل تأخير طلب "الإكمال التلقائي (جديد)" إلى أن يكتب المستخدم الأحرف الثلاثة أو الأربعة الأولى لكي يرسل تطبيقك عددًا أقل من الطلبات. على سبيل المثال، إذا أرسلت طلبات بيانات من واجهة برمجة التطبيقات "الإكمال التلقائي (جديد)" لكل حرف بعد أن يكتب المستخدم الحرف الثالث، يعني ذلك أنّه إذا كتب المستخدم سبعة أحرف ثم اختار عبارة بحث مقترَحة ترسل لها طلب بيانات من واجهة برمجة التطبيقات واحدًا من Geocoding API، ستكون التكلفة الإجمالية لـ 4 طلبات بيانات من واجهة برمجة التطبيقات "الإكمال التلقائي (جديد)" لكل طلب + الترميز الجغرافي.¹

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

ننصحك باتّباع أفضل الممارسات المتعلّقة بالأداء لمساعدة المستخدمين في الحصول على التوقّعات التي يبحثون عنها باستخدام عدد أقل من الأحرف.

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

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

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

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

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

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

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

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