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

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

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

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

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

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

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

• الخيار 1: تضمين AutocompleteSupportFragment
• الخيار 2: استخدِم هدفًا لبدء نشاط الإكمال التلقائي.

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

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

      

    // Initialize the AutocompleteSupportFragment.
    AutocompleteSupportFragment autocompleteFragment = (AutocompleteSupportFragment)
            getSupportFragmentManager().findFragmentById(R.id.autocomplete_fragment);

    // Specify the types of place data to return.
    autocompleteFragment.setPlaceFields(Arrays.asList(Place.Field.ID, Place.Field.NAME));

    // Set up a PlaceSelectionListener to handle the response.
    autocompleteFragment.setOnPlaceSelectedListener(new PlaceSelectionListener() {
        @Override
        public void onPlaceSelected(@NonNull Place place) {
            // TODO: Get info about the selected place.
            Log.i(TAG, "Place: " + place.getName() + ", " + place.getId());
        }


        @Override
        public void onError(@NonNull Status status) {
            // TODO: Handle the error.
            Log.i(TAG, "An error occurred: " + status);
        }
    });

      

الخيار 2: استخدام هدف لبدء نشاط الإكمال التلقائي

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

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

1. استخدِم Autocomplete.IntentBuilder لإنشاء هدف، بتمرير وضع Autocomplete المطلوب.
2. حدِّد مشغِّل نتائج النشاط registerForActivityResult الذي يمكن استخدامه لتشغيل الغرض والتعامل مع التوقّعات المكانية التي اختارها المستخدم في النتيجة.

إنشاء غرض للإكمال التلقائي

يستخدم المثال أدناه Autocomplete.IntentBuilder لإنشاء هدف من أجل تشغيل تطبيق الإكمال التلقائي المصغّر كهدف:

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

      

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

      

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

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

لتلقّي إشعار عندما يختار المستخدم مكانًا، حدِّد مشغِّل تطبيقات registerForActivityResult() الذي يشغِّل النشاط ويعالج أيضًا النتيجة كما هو موضَّح في المثال التالي. إذا اختار المستخدم توقعًا، سيتم عرضه في الغرض المضمَّن في كائن النتيجة. بما أنّ الغرض تم إنشاؤه من خلال Autocomplete.IntentBuilder، يمكن للطريقة Autocomplete.getPlaceFromIntent() استخراج كائن المكان منه.

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

      

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 يحدد حدود خطوط الطول والعرض لحصر النتائج بالمنطقة المحدّدة.
• اختياري: رمز البلد المؤلف من حرفينs (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()).
    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}")
            }
        }

      

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

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

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

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

تعرّف على مزيد من المعلومات حول الرموز المميّزة للجلسة.

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

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

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

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

نتائج التحيز إلى منطقة معينة

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

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

      

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

      

حصر النتائج بمنطقة معيّنة

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

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

      

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

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

      

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

      

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

    autocompleteFragment.setTypesFilter(listOf(PlaceTypes.ADDRESS))

      

    autocompleteFragment.setTypesFilter(Arrays.asList(PlaceTypes.ADDRESS, PlaceTypes.ESTABLISHMENT));

      

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

    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .setTypesFilter(listOf(PlaceTypes.ADDRESS))
        .build(this)

      

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

      

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

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

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

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

      

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

      

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

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

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

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

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

للحصول على مزيد من التفاصيل، اطّلع على مستندات الإحالات.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

على الرغم من إمكانية حدوث مجموعة متنوعة من الأخطاء، إلا أنّ معظم الأخطاء التي راجع حدود الاستخدام لمزيد من المعلومات حول الحصص.

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