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

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

تعرض خدمة الإكمال التلقائي في حزمة تطوير برامج الأماكن لنظام التشغيل 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 إلى نشاط

تعالج السمة 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 الذي يمكن استخدامه لتشغيل 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);

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

نعم

يمكنك تنفيذ ميزة "الإكمال التلقائي" للأماكن تلقائيًا بدون الرموز المميّزة للجلسة واستدعاء واجهة برمجة التطبيقات Geocoding API على اقتراحات الأماكن المحدَّدة.
تقدِّم Geocoding API العناوين وإحداثيات خطوط الطول/العرض مقابل 0.005 دولار أمريكي لكل طلب. فإجراء أربعة طلبات من بيانات الإكمال التلقائي للأماكن - لكل طلب يكلف 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" للاطّلاع على معلومات الأسعار الكاملة.

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

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

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

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

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

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