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

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

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

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

إضافة أداة إكمال تلقائي

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

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

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

الخيار 1: تضمين جزء الإكمال التلقائي للدعم

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

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

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

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

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

      

    // 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")
        }
    })

      

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

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

لتشغيل أداة الإكمال التلقائي باستخدام intent، اتبع الخطوات التالية:

1. استخدِم Autocomplete.IntentBuilder لإنشاء هدف، مع اجتياز وضع Autocomplete المطلوب. يجب أن ينشد الهدف intent startActivityForResult، مع إدخال رمز طلب يحدد الهدف.
2. يمكنك إلغاء معاودة الاتصال بـ onActivityResult لتلقّي المكان المحدَّد.

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

يوضح المثال أدناه استخدام Autocomplete.IntentBuilder لإنشاء نية لتشغيل أداة الإكمال التلقائي كهدف:

    private static int AUTOCOMPLETE_REQUEST_CODE = 1;

    // 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);
    startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE);

      

    private val AUTOCOMPLETE_REQUEST_CODE = 1

    // 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)
    startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE)

      

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

إلغاء معاودة الاتصال على onActivityResult

لتلقي إشعار عند تحديد المستخدم لمكان ما، يجب أن يحل تطبيقك محل onActivityResult() للنشاط، مع التحقق من رمز الطلب الذي مررته لقصدك، كما هو موضح في المثال التالي.

@Override
protected void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) {
    if (requestCode == AUTOCOMPLETE_REQUEST_CODE) {
        if (resultCode == RESULT_OK) {
            Place place = Autocomplete.getPlaceFromIntent(data);
            Log.i(TAG, "Place: " + place.getName() + ", " + place.getId());
        } else if (resultCode == AutocompleteActivity.RESULT_ERROR) {
            // TODO: Handle the error.
            Status status = Autocomplete.getStatusFromIntent(data);
            Log.i(TAG, status.getStatusMessage());
        } else if (resultCode == RESULT_CANCELED) {
            // The user canceled the operation.
        }
        return;
    }
    super.onActivityResult(requestCode, resultCode, data);
}

      

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    if (requestCode == AUTOCOMPLETE_REQUEST_CODE) {
        when (resultCode) {
            Activity.RESULT_OK -> {
                data?.let {
                    val place = Autocomplete.getPlaceFromIntent(data)
                    Log.i(TAG, "Place: ${place.name}, ${place.id}")
                }
            }
            AutocompleteActivity.RESULT_ERROR -> {
                // TODO: Handle the error.
                data?.let {
                    val status = Autocomplete.getStatusFromIntent(data)
                    Log.i(TAG, status.statusMessage ?: "")
                }
            }
            Activity.RESULT_CANCELED -> {
                // The user canceled the operation.
            }
        }
        return
    }
    super.onActivityResult(requestCode, resultCode, data)
}

      

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

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

    // 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(TypeFilter.ADDRESS.toString()))
        .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());
        }
    });

      

    // 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(TypeFilter.ADDRESS.toString()))
            .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)
            }
        }

      

تعرض واجهة برمجة التطبيقات FindAutocompletePredictionsResponse في Task. يحتوي FindAutocompletePredictionsResponse على قائمة بالكائنات AutocompletePrediction التي تمثل الأماكن المتوقعة. قد تكون القائمة فارغة، إذا لم يكن هناك مكان معروف المقابل لطلب البحث ومعايير التصفية.

بالنسبة إلى كل مكان متوقع، يمكنك استدعاء الطرق التالية لاسترداد تفاصيل المكان:

• تعرض getFullText(CharacterStyle) النص الكامل لوصف المكان. وهو مزيج من النص الأساسي والثانوي. على سبيل المثال: "برج خليفة، جادة الأناضول، باريس، فرنسا". بالإضافة إلى ذلك، تتيح لك هذه الطريقة تمييز أقسام الوصف التي تطابق البحث مع نمط من اختيارك، وذلك باستخدام CharacterStyle. المعلمة CharacterStyle اختيارية. يمكنك تعيينه إلى "فارغ" إذا لم تكن بحاجة إلى أي تمييز.
• تعرض getPrimaryText(CharacterStyle) النص الرئيسي الذي يصف مكانًا. وعادة ما يكون هذا هو اسم المكان. أمثلة: "برج خليفة"، و "123 شارع بيت".
• تعرض getSecondaryText(CharacterStyle) النص الفرعي لوصف المكان. وهذا مفيد، على سبيل المثال، في السطر الثاني عند عرض توقعات الإكمال التلقائي. أمثلة: "Avenue Anatole France, Paris, France" و "سيدني، نيو ساوث ويلز".
• تعرض getPlaceId() معرّف المكان للمكان المتوقع. معرّف المكان هو معرّف نصي يحدّد بشكل فريد مكانًا، ويمكنك استخدامه لاسترداد الكائن Place مرة أخرى لاحقًا. لمزيد من المعلومات حول أرقام تعريف الأماكن في الأماكن SDK لنظام التشغيل Android، راجع تفاصيل المكان. للحصول على معلومات عامة عن أرقام تعريف الأماكن، راجع نظرة عامة على أرقام تعريف الأماكن.
• getPlaceTypes() تعرض قائمة بأنواع الأماكن المرتبطة بهذا المكان.
• getDistanceMeters() تعرض المسافة المستقيمة بالأمتار بين هذا المكان والمصدر المحدد في الطلب.

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

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

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

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

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

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

لتقييد النتائج، نفذ ما يلي:

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

نتائج الانحياز لمنطقة محددة

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

    autocompleteFragment.setLocationBias(RectangularBounds.newInstance(
        new LatLng(-33.880490, 151.184363),
        new LatLng(-33.858754, 151.229596)));

      

    autocompleteFragment.setLocationBias(
        RectangularBounds.newInstance(
            LatLng(-33.880490, 151.184363),
            LatLng(-33.858754, 151.229596)
        )
    )

      

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

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

    autocompleteFragment.setLocationRestriction(RectangularBounds.newInstance(
        new LatLng(-33.880490, 151.184363),
        new LatLng(-33.858754, 151.229596)));

      

    autocompleteFragment.setLocationRestriction(
        RectangularBounds.newInstance(
            LatLng(-33.880490, 151.184363),
            LatLng(-33.858754, 151.229596)
        )
    )

      

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

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

يمكنك تقييد النتائج من طلب الإكمال التلقائي بحيث لا تعرض سوى نوع مكان معين. حدد فلترًا باستخدام أنواع الأماكن أو مجموعة أنواع مدرجة في الجداول 1 و2 و3 في أنواع الأماكن. إذا لم يتم تحديد أي شيء، يتم عرض جميع الأنواع.

لفلترة نتائج الإكمال التلقائي، يمكنك استدعاء setTypesFilter() لضبط الفلتر.

لتحديد نوع أو فلتر مجموعة مختارات:

• يمكنك الاتصال بـ setTypesFilter() وتحديد ما يصل إلى خمس قيم من نوع الجدول 1 والجدول 2 على أنواع الأماكن. يتم تحديد قيم النوع من خلال الثوابت في PlaceTypes.

• اتصل بـ setTypesFilter() وحدد مجموعة أنواع من الجدول 3 الموضحة في أنواع الأماكن. يتم تحديد قيم المجموعة من خلال الثوابت في PlaceTypes.

  يُسمح بنوع واحد فقط من الجدول 3 في الطلب. إذا حددت قيمة من الجدول 3، فلا يمكنك تحديد قيمة من الجدول 1 أو الجدول 2. فإذا حدث ذلك، حدث خطأ.

يستدعي مثال الرمز التالي setTypesFilter() على AutocompleteSupportFragment ويحدّد قيمًا متعددة للأنواع.

    autocompleteFragment.setTypesFilter(Arrays.asList("landmark", "restaurant", "store"));

      

    autocompleteFragment.setTypesFilter(listOf("landmark", "restaurant", "store"))

      

يوضح مثال الرمز التالي استدعاء setTypesFilter() على AutocompleteSupportFragment لضبط فلتر يعرض النتائج فقط مع عنوان دقيق من خلال تحديد مجموعة النوع.

    autocompleteFragment.setTypesFilter(Arrays.asList(TypeFilter.ADDRESS.toString()));

      

    autocompleteFragment.setTypesFilter(listOf(TypeFilter.ADDRESS.toString()))

      

يوضح مثال الرمز التالي استدعاء setTypesFilter() على IntentBuilder لضبط فلتر يعرض النتائج فقط مع عنوان دقيق من خلال تحديد مجموعة النوع.

    Intent intent = new Autocomplete.IntentBuilder(
        AutocompleteActivityMode.FULLSCREEN, fields)
        .setTypesFilter(Arrays.asList(TypeFilter.ADDRESS.toString()))
        .build(this);
    startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE);

      

    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .setTypesFilter(listOf(TypeFilter.ADDRESS.toString()))
        .build(this)
    startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE)

      

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

لتصفية نتائج الإكمال التلقائي إلى خمسة بلدان بحد أقصى، اتصل بالرقم setCountries() لتعيين رمز البلد. ثم مرِّر الفلتر إلى جزء أو غرض. يجب إدخال البلدان بتنسيق رمز بلد متوافق مع معيار ISO 3166-1 Alpha-2.

يوضّح مثال الرمز التالي طلب setCountries() على AutocompleteSupportFragment، لضبط فلتر يعرض النتائج فقط داخل البلدان المحدّدة.

    autocompleteFragment.setCountries("AU", "NZ");

      

    autocompleteFragment.setCountries("AU", "NZ")

      

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

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

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

عرض الإحالات في تطبيقك

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

لمزيد من التفاصيل، اطّلع على الوثائق حول النسب.

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

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

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

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

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

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

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

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

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

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

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

أفضل ممارسات الأداء

تصف الإرشادات التالية طرق تحسين أداء الإكمال التلقائي للأماكن:

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

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

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

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