ميزة "الإكمال التلقائي للأماكن" (الإصدار القديم)

المطوّرون في المنطقة الاقتصادية الأوروبية

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

يمكنك إضافة ميزة "الإكمال التلقائي" إلى تطبيقك بالطرق التالية:

إضافة تطبيق مصغّر للإكمال التلقائي

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

هناك خياران لإضافة تطبيق الإكمال التلقائي المصغّر إلى تطبيقك:

الخيار 1: تضمين AutocompleteSupportFragment

لإضافة AutocompleteSupportFragment إلى تطبيقك، اتّبِع الخطوات التالية:

  1. أضِف جزءًا إلى تنسيق XML الخاص بنشاطك.
  2. أضِف مستمعًا إلى نشاطك أو المقتطف.

إضافة AutocompleteSupportFragment إلى نشاط

لإضافة AutocompleteSupportFragment إلى نشاط، أضِف جزءًا جديدًا إلى تنسيق XML. على سبيل المثال:

<fragment android:id="@+id/autocomplete_fragment"
  android:layout_width="match_parent"
  android:layout_height="wrap_content"
  android:name="com.google.android.libraries.places.widget.AutocompleteSupportFragment"
  />
  • لا يتضمّن الجزء أي حدود أو خلفية بشكل تلقائي. لتوفير مظهر مرئي متّسق، يمكنك دمج الجزء في عنصر تنسيق آخر، مثل CardView.
  • إذا كنت تستخدم مقتطف "الإكمال التلقائي"، وتحتاج إلى إلغاء onActivityResult، عليك استدعاء super.onActivityResult، وإلا لن يعمل المقتطف بشكل صحيح.

إضافة PlaceSelectionListener إلى نشاط

تعالج السمة PlaceSelectionListener عرض مكان استجابةً لاختيار المستخدم. يوضّح الرمز التالي كيفية إنشاء مرجع إلى الجزء وإضافة مستمع إلى AutocompleteSupportFragment:

Kotlin

    // Build a BasicPlaceAutocomplete intent to allow the user to select a place.
    val basicAutocompleteIntent = BasicPlaceAutocomplete.createIntent(this) {
        setCountries(listOf("AU", "NZ"))
    }

جافا

    // Build a BasicPlaceAutocomplete intent to allow the user to select a place.
    Intent basicAutocompleteIntent =
            new BasicPlaceAutocomplete.IntentBuilder()
                    .setCountries(List.of("AU", "NZ"))
                    .build(this);

الخيار 2: استخدام intent لتشغيل نشاط الإكمال التلقائي

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

لتشغيل تطبيق الإكمال التلقائي المصغّر باستخدام نية، اتّبِع الخطوات التالية:

  1. استخدِم Autocomplete.IntentBuilder لإنشاء نية، مع تمرير وضع Autocomplete المطلوب.
  2. حدِّد مشغّل نتائج النشاط registerForActivityResult الذي يمكن استخدامه لتشغيل الطلب ومعالجة توقّعات المكان الذي اختاره المستخدم في النتيجة.

إنشاء نية إكمال تلقائي

يستخدم المثال أدناه Autocomplete.IntentBuilder لإنشاء intent لتشغيل تطبيق الإكمال التلقائي المصغّر كـ intent:

Kotlin

    val intent = PlaceAutocomplete.createIntent(this) {
        setTypesFilter(listOf(PlaceTypes.ESTABLISHMENT))
    }

    startAutocomplete.launch(intent)

جافا

    // Start the autocomplete intent.
    Intent intent =
            new PlaceAutocomplete.IntentBuilder()
                    .setTypesFilter(List.of(PlaceTypes.ESTABLISHMENT))
                    .build(this);
    startAutocomplete.launch(intent);

عند استخدام نية لتشغيل تطبيق مصغّر للإكمال التلقائي، يمكنك الاختيار من بين أوضاع العرض على سطح الشاشة أو بملء الشاشة. تعرض لقطات الشاشة التالية كل وضع عرض على التوالي:

عند عرضها في وضع &quot;التراكب&quot;، تظهر أداة الإكمال التلقائي فوق واجهة المستخدم التي تستدعيها.
الشكل 1: تطبيق مصغّر للإكمال التلقائي في وضع OVERLAY
عند عرضها في وضع ملء الشاشة، تملأ أداة الإكمال التلقائي الشاشة بأكملها.
الشكل 2: تطبيق "الإكمال التلقائي" المصغّر في وضع "ملء الشاشة"

تسجيل معاودة الاتصال لنتيجة intent

لتلقّي إشعار عندما يختار المستخدم مكانًا، حدِّد مشغّل registerForActivityResult() الذي يشغّل النشاط ويعالج النتيجة أيضًا كما هو موضّح في المثال التالي. إذا اختار المستخدم عبارة مقترَحة، سيتم إرسالها في الطلب المضمّن في عنصر النتيجة. بما أنّ الغرض تم إنشاؤه بواسطة Autocomplete.IntentBuilder، يمكن للإجراء Autocomplete.getPlaceFromIntent() استخراج عنصر Place منه.

Kotlin

private val startAutocomplete =
    registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult ->
        if (result.resultCode == RESULT_OK) {
            val intent = result.data
            if (intent != null) {
                val prediction = PlaceAutocomplete.getPredictionFromIntent(intent)
                if (prediction != null) {
                    binding.autocompleteResult.text = getString(
                        R.string.place_selection,
                        prediction.getPrimaryText(null),
                        prediction.placeId,
                        prediction.getSecondaryText(null),
                    )
                    Log.i(
                        TAG,
                        "Place: ${prediction.getPrimaryText(null)}, ${prediction.placeId}",
                    )
                }
            }
        } else if (result.resultCode == RESULT_CANCELED) {
            // The user canceled the operation.
            binding.autocompleteResult.setText(R.string.user_canceled_autocomplete)
            Log.i(TAG, "User canceled autocomplete")
        } else if (result.resultCode == PlacesSdkAutocompleteActivity.RESULT_ERROR) {
            val intent = result.data
            if (intent != null) {
                val status = PlaceAutocomplete.getResultStatusFromIntent(intent)
                Log.e(TAG, "An error occurred: ${status?.statusMessage}")
            }
        }
    }

جافا

private final ActivityResultLauncher<Intent> startAutocomplete =
        registerForActivityResult(
                new ActivityResultContracts.StartActivityForResult(),
                result -> {
                    if (result.getResultCode() == Activity.RESULT_OK) {
                        Intent intent = result.getData();
                        if (intent != null) {
                            AutocompletePrediction prediction =
                                    PlaceAutocomplete.getPredictionFromIntent(intent);
                            if (prediction != null) {
                                binding.autocompleteResult.setText(
                                        getString(
                                                R.string.place_selection,
                                                prediction.getPrimaryText(null),
                                                prediction.getPlaceId(),
                                                prediction.getSecondaryText(null)));
                                Log.i(
                                        TAG,
                                        "Place: "
                                                + prediction.getPrimaryText(null)
                                                + ", "
                                                + prediction.getPlaceId());
                            }
                        }
                    } else if (result.getResultCode() == Activity.RESULT_CANCELED) {
                        // The user canceled the operation.
                        binding.autocompleteResult.setText(R.string.user_canceled_autocomplete);
                        Log.i(TAG, "User canceled autocomplete");
                    } else if (result.getResultCode()
                            == com.google.android.libraries.places.widget
                                    .PlaceAutocompleteActivity.RESULT_ERROR) {
                        Intent intent = result.getData();
                        if (intent != null) {
                            Status status = PlaceAutocomplete.getResultStatusFromIntent(intent);
                            if (status != null) {
                                Log.e(TAG, "An error occurred: " + status.getStatusMessage());
                            }
                        }
                    }
                });

الحصول على توقعات الأماكن آليًا

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

  • مطلوبة: سلسلة query تحتوي على النص الذي كتبه المستخدم.
  • ننصح باستخدام: AutocompleteSessionToken، التي تجمع بين مرحلتَي طلب البحث والاختيار في عملية بحث المستخدم في جلسة منفصلة لأغراض الفوترة. تبدأ الجلسة عندما يبدأ المستخدم في كتابة طلب بحث، وتنتهي عندما يختار مكانًا.
  • إجراء يُنصح به: عنصر RectangularBounds يحدّد حدود خطوط العرض والطول من أجل حصر النتائج بالمنطقة المحدّدة.
  • اختياري: رمز بلد واحد أو أكثر مكوّن من حرفَين (ISO 3166-1 Alpha-2)، يشير إلى البلد أو البلدان التي يجب حصر النتائج فيها.

  • اختياري: TypeFilter، ويمكنك استخدامه لحصر النتائج بنوع المكان المحدّد. تتوفّر أنواع الأماكن التالية:

    • ‫TypeFilter.GEOCODE: تعرض نتائج الترميز الجغرافي فقط، بدلاً من الأنشطة التجارية. استخدِم هذا الطلب لتوضيح النتائج التي قد يكون فيها الموقع الجغرافي المحدّد غير واضح.
    • TypeFilter.ADDRESS – تعرض فقط نتائج الإكمال التلقائي التي تتضمّن عنوانًا دقيقًا. استخدِم هذا النوع عندما تعرف أنّ المستخدم يبحث عن عنوان محدّد بالكامل.
    • ‫TypeFilter.ESTABLISHMENT: تعرض الأماكن التي تمثّل أنشطة تجارية فقط.

    • ‫TypeFilter.REGIONS: تعرض فقط الأماكن التي تتطابق مع أحد الأنواع التالية:

    • LOCALITY

    • SUBLOCALITY

    • POSTAL_CODE

    • COUNTRY

    • ADMINISTRATIVE_AREA_LEVEL_1

    • ADMINISTRATIVE_AREA_LEVEL_2

    • ‫TypeFilter.CITIES: تعرض هذه السمة النتائج التي تطابق LOCALITY أو ADMINISTRATIVE_AREA_LEVEL_3 فقط.

  • اختياري: LatLng يحدّد الموقع الجغرافي لمصدر الطلب. عند طلب setOrigin()، تعرض الخدمة المسافة بالأمتار (distanceMeters) من نقطة الانطلاق المحدّدة، لكل عبارة بحث مقترحة في الردّ.

للحصول على معلومات عن أنواع الأماكن، يُرجى الاطّلاع على دليل أنواع الأماكن.

يعرض المثال أدناه طلبًا كاملاً إلى PlacesClient.findAutocompletePredictions().

Kotlin

    // Create a new token for the autocomplete session. Pass this to FindAutocompletePredictionsRequest,
    // and once again when the user makes a selection (for example when calling fetchPlace()).
    val token = AutocompleteSessionToken.newInstance()

    // Create a RectangularBounds object.
    val bounds = RectangularBounds.newInstance(
        LatLng(-33.880490, 151.184363),
        LatLng(-33.858754, 151.229596),
    )
    // Use the builder to create a FindAutocompletePredictionsRequest.
    val request =
        FindAutocompletePredictionsRequest.builder()
            // Call either setLocationBias() OR setLocationRestriction().
            .setLocationBias(bounds)
            // .setLocationRestriction(bounds)
            .setOrigin(LatLng(-33.8749937, 151.2041382))
            .setCountries("AU", "NZ")
            .setTypesFilter(listOf(PlaceTypes.ESTABLISHMENT))
            .setSessionToken(token)
            .setQuery(query)
            .build()
    placesClient.findAutocompletePredictions(request)
        .addOnSuccessListener { response: FindAutocompletePredictionsResponse ->
            val builder = StringBuilder()
            for (prediction in response.autocompletePredictions) {
                builder.append(prediction.getPrimaryText(null).toString()).append("\n")
                Log.i(TAG, prediction.placeId)
                Log.i(TAG, prediction.getPrimaryText(null).toString())
            }
            binding.autocompleteResult.text = builder.toString()
        }.addOnFailureListener { exception: Exception? ->
            if (exception is ApiException) {
                Log.e(TAG, "Place not found: ${exception.statusCode}")
                binding.autocompleteResult.text = getString(R.string.place_not_found, exception.message)
            }
        }

جافا

    // Create a new token for the autocomplete session. Pass this to
    // FindAutocompletePredictionsRequest,
    // and once again when the user makes a selection (for example when calling fetchPlace()).
    AutocompleteSessionToken token = AutocompleteSessionToken.newInstance();

    // Create a RectangularBounds object.
    RectangularBounds bounds =
            RectangularBounds.newInstance(
                    new LatLng(-33.880490, 151.184363), new LatLng(-33.858754, 151.229596));
    // Use the builder to create a FindAutocompletePredictionsRequest.
    FindAutocompletePredictionsRequest request =
            FindAutocompletePredictionsRequest.builder()
                    // Call either setLocationBias() OR setLocationRestriction().
                    .setLocationBias(bounds)
                    // .setLocationRestriction(bounds)
                    .setOrigin(new LatLng(-33.8749937, 151.2041382))
                    .setCountries("AU", "NZ")
                    .setTypesFilter(List.of(PlaceTypes.ESTABLISHMENT))
                    .setSessionToken(token)
                    .setQuery(query)
                    .build();

    placesClient
            .findAutocompletePredictions(request)
            .addOnSuccessListener(
                    (response) -> {
                        StringBuilder builder = new StringBuilder();
                        for (AutocompletePrediction prediction :
                                response.getAutocompletePredictions()) {
                            builder.append(prediction.getPrimaryText(null).toString())
                                    .append("\n");
                            Log.i(TAG, prediction.getPlaceId());
                            Log.i(TAG, prediction.getPrimaryText(null).toString());
                        }
                        binding.autocompleteResult.setText(builder.toString());
                    })
            .addOnFailureListener(
                    (exception) -> {
                        if (exception instanceof ApiException apiException) {
                            Log.e(TAG, "Place not found: " + apiException.getStatusCode());
                            binding.autocompleteResult.setText(
                                    getString(
                                            R.string.place_not_found,
                                            apiException.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 مرة أخرى لاحقًا. لمزيد من المعلومات حول أرقام تعريف الأماكن في حزمة تطوير البرامج بالاستناد إلى الموقع الجغرافي لنظام التشغيل Android، يُرجى الاطّلاع على تفاصيل المكان. للحصول على معلومات عامة عن أرقام تعريف الأماكن، يُرجى الاطّلاع على نظرة عامة على رقم تعريف المكان.
  • تعرض السمة getPlaceTypes() قائمة بأنواع الأماكن المرتبطة بهذا المكان.
  • getDistanceMeters() تعرض المسافة المستقيمة بالأمتار بين هذا المكان ونقطة الانطلاق المحدّدة في الطلب.

الرموز المميزة للجلسات

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

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

مزيد من المعلومات عن الرموز المميّزة للجلسات

تقييد نتائج الإكمال التلقائي

يمكنك حصر نتائج الإكمال التلقائي على منطقة جغرافية معيّنة و/أو فلترة النتائج حسب نوع واحد أو أكثر من أنواع الأماكن، أو حسب ما يصل إلى خمسة بلدان. يمكنك تطبيق هذه القيود على نشاط الإكمال التلقائي، وAutocompleteSupportFragment، وواجهات برمجة التطبيقات الآلية للإكمال التلقائي.

لتقييد النتائج، اتّبِع الخطوات التالية:

  • لتفضيل النتائج ضمن المنطقة المحدّدة، يمكنك استدعاء setLocationBias() (قد يتم عرض بعض النتائج من خارج المنطقة المحدّدة).
  • لعرض النتائج ضمن المنطقة المحدّدة فقط، يمكنك استدعاء setLocationRestriction() (سيتم عرض النتائج ضمن المنطقة المحدّدة فقط).
  • لعرض النتائج التي تتوافق مع نوع مكان معيّن فقط، يمكنك استدعاء setTypesFilter() (على سبيل المثال، سيؤدي تحديد TypeFilter.ADDRESS إلى عرض النتائج التي تتضمّن عنوانًا دقيقًا فقط).
  • لعرض النتائج من خمسة بلدان محدّدة كحد أقصى فقط، يمكنك طلب setCountries(). يجب إدخال البلدان كرمز بلد مكوّن من حرفَين ومتوافق مع معيار ISO 3166-1 Alpha-2.

تحيز النتائج لمنطقة معيّنة

لتحسين نتائج الإكمال التلقائي لمنطقة جغرافية معيّنة، يمكنك استدعاء setLocationBias()، مع تمرير RectangularBounds. يوضّح مثال الرمز البرمجي التالي كيفية استدعاء setLocationBias() في مثيل جزء لتحيز اقتراحات الإكمال التلقائي إلى منطقة في سيدني، أستراليا.

Kotlin

        intentBuilder.setLocationBias(bounds)

جافا

        intentBuilder.setLocationBias(
                RectangularBounds.newInstance(
                        new LatLng(-33.880490, 151.184363),
                        new LatLng(-33.858754, 151.229596)));

حصر النتائج بمنطقة معيّنة

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

Kotlin

        intentBuilder.setLocationRestriction(bounds)

جافا

        intentBuilder.setLocationRestriction(
                RectangularBounds.newInstance(
                        new LatLng(-33.880490, 151.184363),
                        new LatLng(-33.858754, 151.229596)));

ملاحظة: لا ينطبق هذا القيد إلا على المسارات الكاملة، وقد يتم عرض نتائج اصطناعية تقع خارج الحدود المستطيلة استنادًا إلى مسار يتداخل مع قيد الموقع الجغرافي.

فلترة النتائج حسب أنواع الأماكن أو مجموعة الأنواع

يمكنك حصر النتائج من طلب إكمال تلقائي بحيث تعرض فقط نوع مكان معيّن. حدِّد فلترًا باستخدام أنواع الأماكن أو مجموعة أنواع مُدرَجة في الجداول 1 و2 و3 ضمن أنواع الأماكن. في حال عدم تحديد أي نوع، يتم عرض جميع الأنواع.

لفلترة نتائج الإكمال التلقائي، يمكنك استدعاء setTypesFilter() لضبط الفلتر.

لتحديد فلتر نوع أو مجموعة أنواع:

  • استدعِ setTypesFilter() وحدِّد ما يصل إلى خمس قيم type من الجدول 1 والجدول 2 المعروضَين في أنواع الأماكن. يتم تحديد قيم النوع من خلال الثوابت في PlaceTypes.

  • استدعِ setTypesFilter() وحدِّد مجموعة أنواع من الجدول 3 المعروض في أنواع الأماكن. يتم تحديد قيم المجموعة من خلال الثوابت في PlaceTypes.

    يُسمح بنوع واحد فقط من الجدول 3 في الطلب. إذا حدّدت قيمة من الجدول 3، لا يمكنك تحديد قيمة من الجدول 1 أو الجدول 2. وإذا حدث ذلك، سيحدث خطأ.

يستدعي مثال الرمز البرمجي التالي setTypesFilter() في AutocompleteSupportFragment ويحدّد قيم أنواع متعددة.

Kotlin

    intentBuilder.setTypesFilter(listOf("landmark", "restaurant", "store"))

جافا

    intentBuilder.setTypesFilter(List.of("landmark", "restaurant", "store"));

يوضّح مثال الرمز البرمجي التالي استدعاء setTypesFilter() على AutocompleteSupportFragment لضبط فلتر يعرض فقط النتائج التي تحتوي على عنوان دقيق من خلال تحديد مجموعة أنواع.

Kotlin

    intentBuilder.setTypesFilter(listOf(PlaceTypes.ADDRESS))

جافا

    intentBuilder.setTypesFilter(List.of(PlaceTypes.ESTABLISHMENT));

يوضّح مثال الرمز البرمجي التالي استدعاء setTypesFilter() على IntentBuilder لضبط فلتر يعرض فقط النتائج التي تحتوي على عنوان دقيق من خلال تحديد مجموعة أنواع.

Kotlin

    val intent = PlaceAutocomplete.createIntent(this) {
        setTypesFilter(listOf(PlaceTypes.ESTABLISHMENT))
    }

جافا

    Intent intent =
            new PlaceAutocomplete.IntentBuilder()
                    .setTypesFilter(List.of(PlaceTypes.ESTABLISHMENT))
                    .build(this);

فلترة النتائج حسب البلد

لفلترة نتائج الإكمال التلقائي لتشمل ما يصل إلى خمسة بلدان، يمكنك استدعاء setCountries() لضبط رمز البلد. بعد ذلك، مرِّر الفلتر إلى جزء أو نية. يجب إدخال البلدان ك رمز بلد مكوّن من حرفَين ومتوافق مع معيار ISO 3166-1 Alpha-2.

يوضّح مثال الرمز التالي كيفية استدعاء setCountries() على AutocompleteSupportFragment، لضبط فلتر يعرض النتائج ضمن البلدان المحدّدة فقط.

Kotlin

    intentBuilder.setCountries(listOf("AU", "NZ"))

جافا

    intentBuilder.setCountries(List.of("AU", "NZ"));

سقف الاستخدام

لم يعُد استخدامك لواجهة Places API (القديمة)، بما في ذلك حزمة تطوير البرامج (SDK) لأماكن Android (القديمة)، مقتصرًا على حدّ أقصى لعدد الطلبات في اليوم (QPD). ومع ذلك، لا تزال حدود الاستخدام التالية سارية:

  • الحدّ الأقصى لمعدّل الطلبات هو 6,000 طلب في الدقيقة. ويتم احتسابها كمجموع طلبات من جهة العميل وجهة الخادم لجميع التطبيقات التي تستخدم بيانات الاعتماد للمشروع نفسه.

عرض معلومات تحديد المصدر في تطبيقك

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

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

تحسين الإكمال التلقائي للأماكن (القديم)

يصف هذا القسم أفضل الممارسات لمساعدتك في الاستفادة إلى أقصى حدّ من خدمة "الإكمال التلقائي للأماكن" (القديمة).

إليك بعض الإرشادات العامة:

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

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

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

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

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

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

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

نعم، يجب إضافة المزيد من التفاصيل

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

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

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

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

لا، يحتاج فقط إلى العنوان والموقع الجغرافي

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

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

هل يختار المستخدمون توقّعًا من ميزة "الإكمال التلقائي للأماكن (القديمة)" في أربعة طلبات أو أقل في المتوسط؟

نعم

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

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

لا

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

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

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

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

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

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

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

  1. لمعرفة التكاليف، يُرجى الاطّلاع على قوائم أسعار "منصة خرائط Google".

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

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

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

تحديد المشاكل وحلّها

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

يتم عرض الأخطاء التي تحدث أثناء استخدام عناصر التحكّم في الإكمال التلقائي في دالة الاستدعاء onActivityResult(). يُرجى الاتصال بالرقم Autocomplete.getStatus() للحصول على رسالة الحالة الخاصة بالنتيجة.