هذا المنتج أو هذه الميزة في حالة "قديم". لمزيد من المعلومات عن الحالة "قديمة"، يُرجى الاطّلاع على المنتجات والميزات القديمة. لنقل البيانات إلى Places API (الإصدار الجديد)، يُرجى الاطّلاع على دليل نقل البيانات.

تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

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

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

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

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

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

الخيار 1: تضمين AutocompleteSupportFragment

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

أضِف مقتطفًا إلى تنسيق XML لنشاطك.
أضِف مستمعًا إلى نشاطك أو المقتطف.

إضافة 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:

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: استخدام نية لبدء نشاط الإكمال التلقائي

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

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

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

إنشاء نية إكمال تلقائي

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

Kotlin

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

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

Java

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

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

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

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

عند عرض التطبيق المصغّر للإكمال التلقائي في وضع ملء الشاشة، يملؤه الشاشة بالكامل. — **الشكل 2**: التطبيق المصغّر للإكمال التلقائي في وضع ملء الشاشة

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

نعم، يجب تقديم المزيد من التفاصيل

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

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

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

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

لا، يجب إدخال العنوان والموقع الجغرافي فقط.

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

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

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

نعم

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

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

لا

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

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

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

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

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

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

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

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

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

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

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

الإكمال التلقائي للأماكن تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

الخيار 1: تضمين AutocompleteSupportFragment

إضافة AutocompleteSupportFragment إلى نشاط

إضافة مراقب اختيار الأماكن إلى نشاط

Kotlin

Java

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

إنشاء نية إكمال تلقائي

Kotlin

Java

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

Kotlin

Java

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

Kotlin

Java

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

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

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

Kotlin

Java

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

Kotlin

Java

فلترة النتائج حسب أنواع الأماكن أو مجموعة الأنواع

Kotlin

Java

Kotlin

Java

Kotlin

Java

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

Kotlin

Java

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

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

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

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

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

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

نعم، يجب تقديم المزيد من التفاصيل

لا، يجب إدخال العنوان والموقع الجغرافي فقط.

نعم

لا

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

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

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