يتوفر الآن الجيل التالي من حزمة SDK للأماكن لنظام التشغيل Android مع إصدار حزمة SDK للأماكن لنظام التشغيل Android (جديد).

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

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

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

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

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

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

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

أداة الإكمال التلقائي هي مربّع حوار بحث يتضمَّن ميزة الإكمال التلقائي. الوظيفة. عندما يُدخل المستخدم عبارات بحث، يعرض التطبيق المصغّر قائمة الأماكن المتوقعة للاختيار من بينها. عندما يقوم المستخدم بالاختيار، 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 إلى نشاط

تعالج السمة 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 يمكن استخدامها لإطلاق intent والتعامل مع المكان الذي اختاره المستخدم التنبؤ في النتيجة.

إنشاء هدف للإكمال التلقائي

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

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

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

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

تستخدم حزمة تطوير برامج الأماكن لأجهزة 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");

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

نعم، يجب توفير المزيد من التفاصيل.

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

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

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

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

لا، تحتاج فقط إلى العنوان والموقع الجغرافي

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

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

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

نعم

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

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

لا

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

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

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

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

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

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

التكاليف المدرجة هنا بالدولار الأمريكي. يُرجى الرجوع إلى صفحة الفوترة في "منصة خرائط Google" للاطّلاع على معلومات الأسعار الكاملة.

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

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

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

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

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

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