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

اختيار النظام الأساسي: نظام التشغيل Android iOS JavaScript خدمة ويب

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

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

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

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

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

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

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

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

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

لإضافة AutocompleteSupportFragment إلى نشاط، أضِف جزءًا جديدًا إلى تنسيق XML. على سبيل المثال:

<fragment android:id="@+id/autocomplete_fragment"
  android:layout_width="match_parent"
  android:layout_height="wrap_content"
  android:name="com.google.android.libraries.places.widget.AutocompleteSupportFragment"
  />
  • لا يتضمّن المقتطف تلقائيًا أي حدود أو خلفية. لتوفير شكل مرئي متسق، يمكنك دمج المقتطف ضمن عنصر تنسيق آخر، مثل CardView.
  • إذا كنت تستخدم مقتطف "الإكمال التلقائي"، وتريد إلغاء onActivityResult، عليك استدعاء super.onActivityResult، وإلا لن يعمل المقتطف بشكل صحيح.

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

تعالج PlaceSelectionListener عرض مكان استجابةً لاختيار المستخدم. تعرض التعليمة البرمجية التالية إنشاء إشارة إلى المقتطف و إضافة مستمع إلى AutocompleteSupportFragment:

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

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

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

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

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

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

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

لتلقّي إشعار عندما يختار المستخدم مكانًا، حدِّد لانطلاق 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) ألفا -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 لاحقًا. لمزيد من المعلومات عن أرقام تعريف الأماكن في حزمة تطوير برامج الأماكن لأجهزة Android، اطّلع على المكان التفاصيل للحصول على مزيد من المعلومات العامة عن أرقام تعريف الأماكن، اطّلِع على نظرة عامة على أرقام تعريف الأماكن.
  • getPlaceTypes() تعرض قائمة أنواع الأماكن المرتبطة بهذا المكان.
  • تُعرِض دالة getDistanceMeters() المسافة المستقيمة بالكيلومترات بين هذا المكان و المصدر المحدّد في الطلب.

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

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

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

لمزيد من التفاصيل، راجع الوثائق على الإحالة.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

نعم

يمكنك تنفيذ ميزة "الإكمال التلقائي" للأماكن تلقائيًا بدون الرموز المميّزة للجلسة واستدعاء واجهة برمجة التطبيقات Geocoding API على اقتراحات الأماكن المحدَّدة.
توفر Geocoding API العناوين وإحداثيات خطوط العرض/خطوط الطول مقابل 0.005 دولار أمريكي لكل طلب. تبلغ تكلفة إرسال أربعة طلبات Place Autocomplete - Per Request ‏0.01132 دولار أمريكي، وبالتالي فإنّ التكلفة الإجمالية لأربعة طلبات بالإضافة إلى طلب واحد من Geocoding API بشأن التوقّع المحدّد للمكان ستكون 0.01632 دولار أمريكي، وهو أقل من سعر الإكمال التلقائي لكل جلسة الذي يبلغ 0.017 دولار أمريكي لكل جلسة.1

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

لا

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

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

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

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

ننصحك بتأجيل طلبات الإكمال التلقائي للأماكن
يمكنك استخدام استراتيجيات مثل تأخير طلب الإكمال التلقائي للأماكن حتى يكتب المستخدم أول ثلاثة أو أربعة أحرف كي يقلل التطبيق من الطلبات. على سبيل المثال، إذا كان تقديم طلبات الإكمال التلقائي من "الأماكن" لكل حرف بعد كتابة المستخدم للحرف الثالث يعني أنه إذا كتب المستخدم سبعة أحرف ثم اختار توقعًا تُجري له طلبًا واحدًا من أجل Geocoding API، ستكون التكلفة الإجمالية 0.01632 دولار أمريكي (أو ما يعادله بالعملة المحلية) (4 * $0.00283 لكل طلب + 0.005 دولار أمريكي (أو ما يعادله بالعملة المحلية) للترميز الجغرافي).1

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

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

  1. التكاليف المدرجة هنا بالدولار الأمريكي. يُرجى الرجوع إلى صفحة الفوترة في Google Maps Platform للحصول على معلومات الأسعار الكاملة.

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

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

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

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

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

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