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

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

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

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

إضافة أداة إكمال تلقائي

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

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

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

الخيار 1: تضمين الإكمال التلقائي للدعمFragment

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

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

إضافة الإكمال التلقائي لواجهة برمجة التطبيقات إلى نشاط

لإضافة 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.
    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);
        }
    });

      

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

      

الخيار 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.
    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);

      

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

      

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

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

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

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

      

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

      

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

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

      

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

      

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

بالنسبة إلى كل مكان متوقّع، يمكنك اتّباع الطرق التالية لاسترداد تفاصيل المكان:

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

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

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

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

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

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

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

لتقييد النتائج، عليك إجراء ما يلي:

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

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

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

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

      

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

      

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

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

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

      

    autocompleteFragment.setLocationRestriction(
        RectangularBounds.newInstance(
            LatLng(-33.880490, 151.184363),
            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(Arrays.asList("landmark", "restaurant", "store"));

      

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

      

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

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

      

    autocompleteFragment.setTypesFilter(listOf(PlaceTypes.ADDRESS))

      

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

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

      

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

      

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

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

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

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

      

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

      

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

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

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

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

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

لمزيد من التفاصيل، يمكنك الاطّلاع على مستندات الإحالات.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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