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

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

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

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

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

يمكن لتطبيقك الحصول على قائمة بأسماء الأماكن و/أو العناوين المتوقّعة من واجهة برمجة التطبيقات الخاصة بميزة "الإكمال التلقائي" من خلال استدعاء 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.

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

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

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

  يمكن أن يتضمّن المكان نوعًا أساسيًا واحدًا فقط من الأنواع في الجدول "أ" أو الجدول "ب" المرتبط به. على سبيل المثال، قد يكون النوع الأساسي هو "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 لتقييد النتائج بالمنشآت من النوع "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());
        })
    );

عمليات تحديد المصدر

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