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

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

يعالج 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.DISPLAY_NAME))

    // Set up a PlaceSelectionListener to handle the response.
    autocompleteFragment.setOnPlaceSelectedListener(object : PlaceSelectionListener {
        override fun onPlaceSelected(place: Place) {
            binding.autocompleteResult.text = getString(
                R.string.place_selection,
                place.displayName,
                place.id,
                place.formattedAddress
            )
            Log.i(TAG, "Place: ${place.displayName}, ${place.id}")
        }

        override fun onError(status: Status) {
            binding.autocompleteResult.text = getString(R.string.an_error_occurred, status)
            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.
    assert autocompleteFragment != null;
    autocompleteFragment.setPlaceFields(Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME, Place.Field.FORMATTED_ADDRESS));

    // Set up a PlaceSelectionListener to handle the response.
    autocompleteFragment.setOnPlaceSelectedListener(new PlaceSelectionListener() {
        @Override
        public void onPlaceSelected(@NonNull Place place) {
            binding.autocompleteResult.setText(
                    getString(
                            R.string.place_selection,
                            place.getDisplayName(),
                            place.getId(),
                            place.getFormattedAddress()
                    )
            );
            Log.i(TAG, "Place: " + place.getDisplayName() + ", " + place.getId());
        }


        @Override
        public void onError(@NonNull Status status) {
            binding.autocompleteResult.setText(getString(R.string.an_error_occurred, status));
            Log.e(TAG, "An error occurred: " + status);
        }
    });

      

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

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

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

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.DISPLAY_NAME, Place.Field.FORMATTED_ADDRESS)

    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .setTypesFilter(listOf(PlaceTypes.ESTABLISHMENT))
        .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.DISPLAY_NAME, Place.Field.FORMATTED_ADDRESS);

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

      

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

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

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

private val startAutocomplete =
    registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult ->
        if (result.resultCode == RESULT_OK) {
            val intent = result.data
            if (intent != null) {
                val place = Autocomplete.getPlaceFromIntent(intent)
                binding.autocompleteResult.text = getString(
                    R.string.place_selection,
                    place.displayName,
                    place.id,
                    place.formattedAddress)
                Log.i(
                    TAG, "Place: ${place.displayName}, ${place.id}"
                )
            }
        } 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")
        }
    }

      

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);
                    binding.autocompleteResult.setText(
                            getString(
                                    R.string.place_selection,
                                    place.getDisplayName(),
                                    place.getId(),
                                    place.getFormattedAddress()
                            )
                    );
                    Log.i(TAG, "Place: " + place.getDisplayName() + ", " + place.getId());
                }
            } 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");
            }
        });

      

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

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

• مطلوبة: سلسلة query تحتوي على النص الذي كتبه المستخدم.
• الإجراء المقترَح: A 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.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() المسافة المستقيمة بالأمتار بين هذا المكان ونقطة الأصل المحدّدة في الطلب.

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

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

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

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

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

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

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

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

توجيه النتائج إلى منطقة معيّنة

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

        autocompleteFragment.setLocationBias(bounds)

      

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

      

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

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

        autocompleteFragment.setLocationRestriction(bounds)

      

        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(List.of("landmark", "restaurant", "store"));

      

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

    autocompleteFragment.setTypesFilter(listOf(PlaceTypes.ADDRESS))

      

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

      

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

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

      

    Intent intent = new Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
            .setTypesFilter(List.of(PlaceTypes.ESTABLISHMENT))
            .build(this);

      

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

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

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

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

      

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

      

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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