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

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

إذا كان عنوان الفوترة الخاص بك يقع في المنطقة الاقتصادية الأوروبية، ستسري بنود خدمة "منصة خرائط Google" في المنطقة الاقتصادية الأوروبية على استخدامك للخدمات اعتبارًا من 8 تموز (يوليو) 2025. تختلف الوظائف حسب المنطقة. مزيد من المعلومات

تعرض خدمة الإكمال التلقائي في Places SDK لنظام التشغيل 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 إلى نشاط

يتولّى 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: استخدام هدف لتشغيل نشاط الإكمال التلقائي

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

ملاحظة: لا تحتاج إلى اتّباع هذه الخطوات إذا كنت تضمّن جزءًا.

تنبيه: لا تُشغّل AutcompleteActivity مباشرةً. بدلاً من ذلك، استخدِم هدفًا لتشغيل Autocomplete (PlaceAutocomplete في مكتبة التوافق).

لإطلاق أداة الإكمال التلقائي باستخدام هدف، اتّبِع الخطوات التالية:

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

      

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

الشكل 1: أداة الإكمال التلقائي في وضع OVERLAY

الشكل 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");
            }
        });

      

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

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

ملاحظة: لمزيد من المعلومات حول إعداد PlacesClient، راجِع إعداد برنامج واجهة Places API.

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

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

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

تستخدِم حزمة تطوير البرامج Places SDK for 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، بما في ذلك حزمة تطوير البرامج (SDK) الخاصة بـ Places API لنظام التشغيل Android، محصورًا بعدد أقصى من الطلبات في اليوم (QPD). ومع ذلك، ستظل حدود الاستخدام التالية سارية:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

للمساعدة في اختيار عملية تنفيذ Place Autocomplete (الإصدار القديم) التي تناسب احتياجاتك، اختَر علامة التبويب التي تتوافق مع إجابتك عن السؤال التالي.

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

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

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

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

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

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

لا، يجب توفير العنوان والموقع الجغرافي فقط

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

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

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

نعم

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

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

لا

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

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

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

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

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

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

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

---

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

أفضل الممارسات لتحسين الأداء

توضّح الإرشادات التالية طرقًا لتحسين أداء خدمة Place Autocomplete (الإصدار القديم):

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

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

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

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