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

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

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

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

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

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

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

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

الخيار 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 عرض مكان استجابةً لاختيار المستخدم. تعرض التعليمة البرمجية التالية إنشاء إشارة إلى المقتطف و إضافة مستمع إلى AutocompleteSupportFragment:

    // 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")
        }
    })

      

    // 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 لإنشاء نية لتشغيل التطبيق المصغّر للإكمال التلقائي كهدف:

    // 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)

      

    // 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);

      

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

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

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

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")
        }
    }

      

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

      

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

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

    // 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}")
            }
        }

      

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

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

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

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

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

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

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

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

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

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

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

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

      

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

      

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

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

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

      

    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 ويحدّد قيم أنواع متعدّدة.

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

      

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

      

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

    autocompleteFragment.setTypesFilter(listOf(PlaceTypes.ADDRESS))

      

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

      

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

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

      

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

      

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

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

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

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

      

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

      

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

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

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

عرض الإسنادات في تطبيقك

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

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

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

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

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

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

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

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

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

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

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

• إذا كنت بحاجة فقط إلى خط العرض/خط الطول أو عنوان المكان الذي اختاره المستخدم، تقدّم واجهة برمجة التطبيقات Geocoding API هذه المعلومات بتكلفة أقل من طلب الحصول على تفاصيل المكان.
• إذا اختار المستخدمون توقّعًا للإكمال التلقائي في المتوسط خلال أربعة طلبات توقّعات للإكمال التلقائي أو أقل، قد يكون السعر لكل طلب أكثر فعالية من حيث التكلفة مقارنةً بالسعر لكل جلسة.

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

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

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

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

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

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

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