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

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
اختيار نظام أساسي: Android iOS JavaScript خدمة الويب

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

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

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

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

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

الخيار 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:

لغة 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);
        }
    });

      

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

      

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

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

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

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

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

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

لغة Java


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

      

Kotlin


    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)

      

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

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

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

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

لغة Java


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

      

Kotlin


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().

لغة 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(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());
        }
    });

      

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(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() على نسخة جزئية لانحياز اقتراحات الإكمال التلقائي إلى منطقة في سيدني بأستراليا.

لغة Java


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

      

Kotlin


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

      

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

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

لغة Java


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

      

Kotlin


    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 ويحدّد قيمًا متعددة للأنواع.

لغة Java


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

      

Kotlin


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

      

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

لغة Java


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

      

Kotlin


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

      

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

لغة Java


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

      

Kotlin


    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، لضبط فلتر يعرض النتائج فقط داخل البلدان المحدّدة.

لغة Java


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

      

Kotlin


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

      

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

نعم، بحاجة إلى المزيد من التفاصيل

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

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

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

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

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

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

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

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

نعم

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

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

لا

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

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

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

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

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

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

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


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

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

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

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

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

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

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