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

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

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

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

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

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

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

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

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

لإضافة 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، وإلا لن يعمل الجزء بشكل صحيح.

إضافة قيمةPlaceSelection Listener إلى نشاط معيّن

تعالج السمة 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: استخدام هدف لتشغيل نشاط الإكمال التلقائي

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

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

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

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

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

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

      

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

      

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

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

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

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

      

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

      

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

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

      

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

      

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

يمكنك استدعاء الطرق التالية لكل مكان متنبأ به لعرض تفاصيل المكان:

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

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

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

تستخدم حزمة تطوير برامج الأماكن لأجهزة 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() وتحديد ما يصل إلى خمس قيم type من الجدول 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(PlaceTypes.ADDRESS, PlaceTypes.ESTABLISHMENT));

      

    autocompleteFragment.setTypesFilter(listOf(PlaceTypes.ADDRESS))

      

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

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

      

    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .setTypesFilter(listOf(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، أو حزمة SDK للأماكن لأجهزة Android أداة الإكمال التلقائي أو حزمة SDK للأماكن في نظام التشغيل iOS عناصر التحكم في الإكمال التلقائي لواجهة المستخدم
• فهم حقول البيانات الأساسية الخاصة بميزة "الإكمال التلقائي" للمكان من البداية
• إنّ حقلَي "انحياز الموقع الجغرافي" و"حظر الموقع الجغرافي" هما أمران اختياريان، ولكن قد يكون لهما تأثير كبير في أداء الإكمال التلقائي.
• استخدِم معالجة الأخطاء لضمان تراجع مستوى تطبيقك بشكل مناسب في حال عرض واجهة برمجة التطبيقات خطأ.
• يُرجى التأكّد من معالجة التطبيق في حال عدم تحديد الخيار وتوفير طريقة للمستخدمين للمتابعة.

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

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

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

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

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

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

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

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

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

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

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

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

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