الإكمال التلقائي للأماكن

اختَر النظام الأساسي: Android iOS JavaScript خدمة الويب

تعرض خدمة الإكمال التلقائي في حزمة تطوير برامج الأماكن لأجهزة Android توقعات الأماكن استجابةً لطلبات بحث المستخدم. أثناء كتابة المستخدمين، تعرض خدمة الإكمال التلقائي اقتراحات لأماكن مثل الأنشطة التجارية والعناوين ورموز الجمع ونقاط الاهتمام.

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

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

تطبيق الإكمال التلقائي المصغّر هو مربّع حوار للبحث مع وظائف مضمّنة للإكمال التلقائي. عندما يُدخِل المستخدم عبارات بحث، تعرِض الأداة قائمة بالأماكن المتوقّعة للاختيار من بينها. عندما يختار المستخدم اختيارًا، يتم عرض مثيل 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



    // Initialize the AutocompleteSupportFragment.
    val autocompleteFragment =
        supportFragmentManager.findFragmentById(R.id.autocomplete_fragment)
                as AutocompleteSupportFragment

    // Specify the types of place data to return.
    autocompleteFragment.setPlaceFields(listOf(Place.Field.ID, Place.Field.NAME))

    // Set up a PlaceSelectionListener to handle the response.
    autocompleteFragment.setOnPlaceSelectedListener(object : PlaceSelectionListener {
        override fun onPlaceSelected(place: Place) {
            // TODO: Get info about the selected place.
            Log.i(TAG, "Place: ${place.name}, ${place.id}")
        }

        override fun onError(status: Status) {
            // TODO: Handle the error.
            Log.i(TAG, "An error occurred: $status")
        }
    })

      

Java


    // Initialize the AutocompleteSupportFragment.
    AutocompleteSupportFragment autocompleteFragment = (AutocompleteSupportFragment)
            getSupportFragmentManager().findFragmentById(R.id.autocomplete_fragment);

    // Specify the types of place data to return.
    autocompleteFragment.setPlaceFields(Arrays.asList(Place.Field.ID, Place.Field.NAME));

    // Set up a PlaceSelectionListener to handle the response.
    autocompleteFragment.setOnPlaceSelectedListener(new PlaceSelectionListener() {
        @Override
        public void onPlaceSelected(@NonNull Place place) {
            // TODO: Get info about the selected place.
            Log.i(TAG, "Place: " + place.getName() + ", " + place.getId());
        }


        @Override
        public void onError(@NonNull Status status) {
            // TODO: Handle the error.
            Log.i(TAG, "An error occurred: " + status);
        }
    });

      

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

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

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

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

إنشاء غرض للإكمال التلقائي

يستخدم المثال التالي Autocomplete.IntentBuilder لإنشاء غرض لتشغيل أداة الإكمال التلقائي كهدف:

Kotlin




    // Set the fields to specify which types of place data to
    // return after the user has made a selection.
    val fields = listOf(Place.Field.ID, Place.Field.NAME)

    // Start the autocomplete intent.
    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .build(this)
    startAutocomplete.launch(intent)

      

Java



    // Set the fields to specify which types of place data to
    // return after the user has made a selection.
    List<Place.Field> fields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

    // Start the autocomplete intent.
    Intent intent = new Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
            .build(this);
    startAutocomplete.launch(intent);

      

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

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

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

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

Kotlin



private val startAutocomplete =
    registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult ->
        if (result.resultCode == Activity.RESULT_OK) {
            val intent = result.data
            if (intent != null) {
                val place = Autocomplete.getPlaceFromIntent(intent)
                Log.i(
                    TAG, "Place: ${place.name}, ${place.id}"
                )
            }
        } else if (result.resultCode == Activity.RESULT_CANCELED) {
            // The user canceled the operation.
            Log.i(TAG, "User canceled autocomplete")
        }
    }

      

Java


private final ActivityResultLauncher<Intent> startAutocomplete = registerForActivityResult(
        new ActivityResultContracts.StartActivityForResult(),
        result -> {
            if (result.getResultCode() == Activity.RESULT_OK) {
                Intent intent = result.getData();
                if (intent != null) {
                    Place place = Autocomplete.getPlaceFromIntent(intent);
                    Log.i(TAG, "Place: ${place.getName()}, ${place.getId()}");
                }
            } else if (result.getResultCode() == Activity.RESULT_CANCELED) {
                // The user canceled the operation.
                Log.i(TAG, "User canceled autocomplete");
            }
        });

      

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

يمكنك إنشاء واجهة مستخدم مخصّصة على "بحث Google" كبديل لواجهة المستخدم التي توفّرها أداة الإكمال التلقائي. لإجراء ذلك، يجب أن يتلقّى تطبيقك توقّعات عن الأماكن بشكل آلي. يمكن أن يحصل تطبيقك على قائمة بأسماء الأماكن و/أو العناوين المتوقّعة من واجهة برمجة التطبيقات للإكمال التلقائي عن طريق استدعاء 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.ADDRESS))
            .setSessionToken(token)
            .setQuery(query)
            .build()
    placesClient.findAutocompletePredictions(request)
        .addOnSuccessListener { response: FindAutocompletePredictionsResponse ->
            for (prediction in response.autocompletePredictions) {
                Log.i(TAG, prediction.placeId)
                Log.i(TAG, prediction.getPrimaryText(null).toString())
            }
        }.addOnFailureListener { exception: Exception? ->
            if (exception is ApiException) {
                Log.e(TAG, "Place not found: ${exception.statusCode}")
            }
        }

      

Java


    // 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(Arrays.asList(PlaceTypes.ADDRESS))
            .setSessionToken(token)
            .setQuery(query)
            .build();

    placesClient.findAutocompletePredictions(request).addOnSuccessListener((response) -> {
        for (AutocompletePrediction prediction : response.getAutocompletePredictions()) {
            Log.i(TAG, prediction.getPlaceId());
            Log.i(TAG, prediction.getPrimaryText(null).toString());
        }
    }).addOnFailureListener((exception) -> {
        if (exception instanceof ApiException) {
            ApiException apiException = (ApiException) exception;
            Log.e(TAG, "Place not found: " + apiException.getStatusCode());
        }
    });

      

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

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

  • تعرض getFullText(CharacterStyle) النص الكامل لوصف المكان. هذا مزيج من النص الأساسي والثانوي. مثال: "برج إيفل، جادة أناتول فرنسا، باريس، فرنسا". بالإضافة إلى ذلك، تتيح لك هذه الطريقة تمييز أقسام الوصف التي تتطابق مع البحث بنمط من اختيارك، وذلك باستخدام CharacterStyle. وتُعدّ المَعلمة CharacterStyle اختيارية. قم بتعيينه على قيمة فارغة إذا لم تكن بحاجة إلى أي تظليل.
  • تعرض دالة getPrimaryText(CharacterStyle) النص الرئيسي الذي يصف المكان. عادةً ما يكون هذا اسم المكان. أمثلة: "برج إيفل"، و "123 شارع السلام".
  • تعرض getSecondaryText(CharacterStyle) نص الشركة الفرعية لوصف المكان. يكون هذا مفيدًا، على سبيل المثال، كسطر ثانٍ عند عرض توقعات الإكمال التلقائي. أمثلة: "شارع أناتول فرنسا، باريس، فرنسا"، و "سيدني، نيو ساوث ويلز".
  • تعرض getPlaceId() معرّف المكان للمكان المتوقّع. معرّف المكان هو معرّف نصي يحدّد المكان بشكل فريد، ويمكنك استخدامه لاسترداد عنصر Place مجددًا لاحقًا. لمزيد من المعلومات حول معرّفات الأماكن في حزمة SDK للأماكن لأجهزة Android، راجع تفاصيل المكان. للحصول على معلومات عامة حول معرّفات الأماكن، راجع نظرة عامة على معرّف المكان.
  • تعرض الدالة getPlaceTypes() قائمة بأنواع الأماكن المرتبطة بهذا المكان.
  • getDistanceMeters() لعرض المسافة المستقيمة بالمتر بين هذا المكان والمصدر المحدد في الطلب.

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

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

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

تعرّف على المزيد من المعلومات حول الرموز المميّزة للجلسة.

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

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

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

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

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

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

Kotlin



    autocompleteFragment.setLocationBias(
        RectangularBounds.newInstance(
            LatLng(-33.880490, 151.184363),
            LatLng(-33.858754, 151.229596)
        )
    )

      

Java


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

      

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

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

Kotlin



    autocompleteFragment.setLocationRestriction(
        RectangularBounds.newInstance(
            LatLng(-33.880490, 151.184363),
            LatLng(-33.858754, 151.229596)
        )
    )

      

Java


    autocompleteFragment.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



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

      

Java


    autocompleteFragment.setTypesFilter(Arrays.asList("landmark", "restaurant", "store"));

      

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

Kotlin



    autocompleteFragment.setTypesFilter(listOf(PlaceTypes.ADDRESS))

      

Java


    autocompleteFragment.setTypesFilter(Arrays.asList(PlaceTypes.ADDRESS, PlaceTypes.ESTABLISHMENT));

      

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

Kotlin



    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .setTypesFilter(listOf(PlaceTypes.ADDRESS))
        .build(this)

      

Java


    Intent intent = new Autocomplete.IntentBuilder(
            AutocompleteActivityMode.FULLSCREEN, fields)
            .setTypesFilter(Arrays.asList(PlaceTypes.ADDRESS))
            .build(this);

      

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

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

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

Kotlin



    autocompleteFragment.setCountries("AU", "NZ")

      

Java


    autocompleteFragment.setCountries("AU", "NZ");

      

حدود الاستخدام

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

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

عرض الإحالات في تطبيقك

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

لمزيد من التفاصيل، اطّلع على المستندات المتعلقة بجهات تحديد المصدر.

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

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

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

  • تتمثل أسرع طريقة لتطوير واجهة مستخدم عاملة في استخدام واجهة برمجة تطبيقات JavaScript لـ "خرائط Google" أداة الإكمال التلقائي أو حزمة تطوير البرامج (SDK) للأماكن المخصّصة لنظام التشغيل Android أو أداة الإكمال التلقائي أو حزمة تطوير البرامج للأماكن المخصّصة لنظام التشغيل iOS التحكم في الإكمال التلقائي لواجهة المستخدم
  • فهم حقول البيانات الأساسية الخاصة بالإكمال التلقائي للأماكن من البداية
  • يُعدّ حقلا "انحياز الموقع الجغرافي" و"حظر الموقع الجغرافي" اختياريًا، ولكن قد يكون لهما تأثير كبير في أداء الإكمال التلقائي.
  • استخدِم معالجة الأخطاء لضمان تراجع أداء تطبيقك بشكل آمن إذا ظهرت واجهة برمجة التطبيقات خطأ.
  • تأكَّد من أنّ تطبيقك يعالجه في حال عدم تحديد أي خيار، وأنّه يوفِّر للمستخدمين طريقة للمتابعة.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

هل يختار المستخدمون في مؤسستك عبارة بحث مقترحة خاصة بميزة "الإكمال التلقائي" عن الأماكن من خلال أربعة طلبات أو أقل في المتوسط؟

نعم

تنفيذ ميزة الإكمال التلقائي للأماكن بشكل آلي بدون الرموز المميّزة للجلسة وطلب واجهة برمجة التطبيقات Geocoding API عند اقتراح المكان المحدّد
توفّر واجهة برمجة التطبيقات للترميز الجغرافي العناوين وإحداثيات خطوط الطول/العرض مقابل 0.005 دولار أمريكي (أو ما يعادله بالعملة المحلية) لكل طلب. يكلّف إجراء أربعة طلبات من طلبات الإكمال التلقائي - حسب الطلب 0.01132 دولار أمريكي، وبالتالي سيكون إجمالي التكلفة لأربعة طلبات بالإضافة إلى طلب بيانات واجهة برمجة التطبيقات للترميز الجغرافي حول توقّع المكان المحدّد هو 0.01632 دولار أمريكي، وهو أقل من سعر الإكمال التلقائي لكل جلسة الذي يبلغ 0.017 دولار أمريكي لكل جلسة.1

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

لا

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

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

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

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

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

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

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


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

أفضل ممارسات الأداء

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

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

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

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

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