تعرض خدمة الإكمال التلقائي في حزمة تطوير البرامج (SDK) للأماكن لأجهزة Android عبارات بحث مقترحة استجابةً لطلبات بحث المستخدم. أثناء كتابة المستخدمين، تعرض خدمة الإكمال التلقائي اقتراحات لأماكن مثل الأنشطة التجارية والعناوين ورموز Plus Codes ونقاط الاهتمام.
يمكنك إضافة ميزة الإكمال التلقائي إلى تطبيقك بالطرق التالية:
- أضِف أداة إكمال تلقائي لتوفير وقت التطوير وضمان تجربة متّسقة للمستخدم.
- الحصول على توقّعات الأماكن بشكل آلي لإنشاء تجربة مستخدم مخصّصة
إضافة أداة إكمال تلقائي
إنّ أداة الإكمال التلقائي هي مربّع حوار البحث مزوّد بوظيفة مدمَجة
للإكمال التلقائي. عندما يُدخل المستخدِم عبارات بحث، يعرض التطبيق المصغّر قائمة بالأماكن المتوقّعة للاختيار منها. عندما يختار المستخدم خيارًا، يتم عرض مثيل Place
، والذي يمكن أن يستخدمه تطبيقك بعد ذلك للحصول على تفاصيل عن المكان المحدّد.
هناك خياران لإضافة أداة الإكمال التلقائي إلى تطبيقك:
الخيار 1: تضمين الإكمال التلقائي للدعمFragment
لإضافة AutocompleteSupportFragment
إلى تطبيقك، اتّبِع الخطوات التالية:
- أضِف جزءًا إلى تنسيق XML لنشاطك.
- يمكنك إضافة مستمع إلى نشاطك أو جزء منه.
إضافة الإكمال التلقائي لواجهة برمجة التطبيقات إلى نشاط
لإضافة 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
مع عرض مكان استجابةً لاختياره. يعرض الرمز التالي إنشاء إشارة إلى الجزء وإضافة مستمع إلى 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: استخدام هدف لبدء نشاط الإكمال التلقائي
إذا كنت تريد أن يستخدم تطبيقك مسارًا مختلفًا للتنقّل (على سبيل المثال، لبدء تجربة الإكمال التلقائي من أحد الرموز بدلاً من حقل البحث)، يمكن لتطبيقك تشغيل الإكمال التلقائي باستخدام القصد من البحث.
لتشغيل تطبيق الإكمال التلقائي التلقائي حسب النية بالشراء، اتّبِع الخطوات التالية:
- استخدِم
Autocomplete.IntentBuilder
لإنشاء هدف، وتمرير وضعAutocomplete
المطلوب. - تحديد مشغّل نتائج النشاط
registerForActivityResult
الذي يمكن استخدامه لإطلاق النية بالشراء والتعامل مع توقّعات المكان المحدّد للمستخدم في النتيجة.
إنشاء هدف إكمال تلقائي
يستخدم المثال الوارد في ما يلي
Autocomplete.IntentBuilder
هدف إنشاء أداة الإكمال التلقائي بهدف:
لغة Java
// Set the fields to specify which types of place data to // return after the user has made a selection. List<Place.Field> fields = Arrays.asList(Place.Field.ID, Place.Field.NAME); // Start the autocomplete intent. Intent intent = new Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields) .build(this); startAutocomplete.launch(intent);
Kotlin
// Set the fields to specify which types of place data to // return after the user has made a selection. val fields = listOf(Place.Field.ID, Place.Field.NAME) // Start the autocomplete intent. val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields) .build(this) startAutocomplete.launch(intent)
عند الرغبة في إطلاق التطبيق المصغّر للإكمال التلقائي، يمكنك الاختيار من بين أوضاع العرض المركّب أو وضع ملء الشاشة. تعرض لقطات الشاشة التالية كل وضع عرض:


تسجيل معاودة الاتصال كنتيجة intent
لتلقّي إشعار عند اختيار المستخدم مكانًا، حدِّد مشغّل التطبيقات registerForActivityResult()
، والذي يشغِّل النشاط ويعالج النتيجة كما هو موضّح في المثال التالي. إذا اختار المستخدم أحد عبارات البحث المقترحة، سيتم عرضه
حسب النية بالشراء المضمّنة في عنصر النتيجة. بما أنّ intent
تم إنشاؤها من قِبل Autocomplete.IntentBuilder
، يمكن للطريقة
Autocomplete.getPlaceFromIntent()
استخراج عنصر المكان منه.
لغة Java
private final ActivityResultLauncher<Intent> startAutocomplete = registerForActivityResult( new ActivityResultContracts.StartActivityForResult(), result -> { if (result.getResultCode() == Activity.RESULT_OK) { Intent intent = result.getData(); if (intent != null) { Place place = Autocomplete.getPlaceFromIntent(intent); Log.i(TAG, "Place: ${place.getName()}, ${place.getId()}"); } } else if (result.getResultCode() == Activity.RESULT_CANCELED) { // The user canceled the operation. Log.i(TAG, "User canceled autocomplete"); } });
Kotlin
private val startAutocomplete = registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult -> if (result.resultCode == Activity.RESULT_OK) { val intent = result.data if (intent != null) { val place = Autocomplete.getPlaceFromIntent(intent) Log.i( TAG, "Place: ${place.name}, ${place.id}" ) } } else if (result.resultCode == Activity.RESULT_CANCELED) { // The user canceled the operation. Log.i(TAG, "User canceled autocomplete") } }
الحصول على توقعات عن الأماكن آليًا
يمكنك إنشاء واجهة مستخدم مخصّصة للبحث بدلاً من واجهة المستخدم التي توفرها
أداة الإكمال التلقائي. لإجراء ذلك، يجب أن يحصل تطبيقك على عبارات بحث مقترَحة
للتطبيقات آليًا. يمكن أن يحصل تطبيقك على قائمة بأسماء الأماكن و/أو العناوين المتوقّعة من واجهة برمجة التطبيقات الخاصة بميزة "الإكمال التلقائي" من خلال طلب
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(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()); } });
Kotlin
// Create a new token for the autocomplete session. Pass this to FindAutocompletePredictionsRequest, // and once again when the user makes a selection (for example when calling fetchPlace()). val token = AutocompleteSessionToken.newInstance() // Create a RectangularBounds object. val bounds = RectangularBounds.newInstance( LatLng(-33.880490, 151.184363), LatLng(-33.858754, 151.229596) ) // Use the builder to create a FindAutocompletePredictionsRequest. val request = FindAutocompletePredictionsRequest.builder() // Call either setLocationBias() OR setLocationRestriction(). .setLocationBias(bounds) //.setLocationRestriction(bounds) .setOrigin(LatLng(-33.8749937, 151.2041382)) .setCountries("AU", "NZ") .setTypesFilter(listOf(PlaceTypes.ADDRESS)) .setSessionToken(token) .setQuery(query) .build() placesClient.findAutocompletePredictions(request) .addOnSuccessListener { response: FindAutocompletePredictionsResponse -> for (prediction in response.autocompletePredictions) { Log.i(TAG, prediction.placeId) Log.i(TAG, prediction.getPrimaryText(null).toString()) } }.addOnFailureListener { exception: Exception? -> if (exception is ApiException) { Log.e(TAG, "Place not found: ${exception.statusCode}") } }
تعرض واجهة برمجة التطبيقات
FindAutocompletePredictionsResponse
في
Task
. تتضمّن السمة FindAutocompletePredictionsResponse
قائمة بالكائنات
AutocompletePrediction
التي تمثّل الأماكن المتوقّعة. وقد تكون القائمة فارغة، إذا لم يكن هناك مكان معروف المقابل لطلب البحث ومعايير الفلتر.
بالنسبة إلى كل مكان متوقّع، يمكنك اتّباع الطرق التالية لاسترداد تفاصيل المكان:
getFullText(CharacterStyle)
تعرض النص الكامل لوصف المكان. هذا مزيج من النص الأساسي والثانوي. مثال: "برج إيفل، شارع أناضول في فرنسا، باريس، فرنسا" بالإضافة إلى ذلك، تتيح لك هذه الطريقة تظليل أقسام الوصف التي تطابق البحث بنمط من اختيارك، وذلك باستخدامCharacterStyle
. المعلَمةCharacterStyle
اختيارية. ويمكنك ضبطه على قيمة فارغة إذا لم تكن بحاجة إلى أي تمييز.getPrimaryText(CharacterStyle)
يعرض النص الرئيسي الذي يصف مكانًا. ويكون عادةً اسم المكان. على سبيل المثال: "برج إيفل" و "123 شارع بيت".getSecondaryText(CharacterStyle)
تعرض النص الفرعي لوصف المكان. ويُعدّ هذا الأمر مفيدًا، على سبيل المثال، كسطر ثانٍ عند عرض عبارات البحث المقترحة من خلال ميزة "الإكمال التلقائي". أمثلة: "شارع الأناضول في فرنسا"، باريس، فرنسا" و"سيدني ونيو ساوث ويلز"getPlaceId()
تعرض معرّف المكان للمكان المتوقع. رقم تعريف المكان هو معرّف نصي يحدِّد مكانًا بشكلٍ فريد يمكنك استخدامه لاسترداد العنصرPlace
مرة أخرى لاحقًا. للحصول على مزيد من المعلومات عن أرقام تعريف الأماكن في حزمة تطوير برامج الأماكن لأجهزة Android، يمكنك الاطّلاع على تفاصيل المكان. للحصول على معلومات عامة عن أرقام تعريف الأماكن، اطّلِع على نظرة عامة على رقم تعريف المكان.getPlaceTypes()
يعرض قائمة بأنواع الأماكن المرتبطة بهذا المكان.getDistanceMeters()
تعرض مسافة الخط المستقيم بالمتر بين هذا المكان والمصدر المحدّد في الطلب.
الرموز المميزة للجلسة
تعمل الرموز المميّزة للجلسة على تجميع طلبات البحث ومراحل الاختيار في عملية الإكمال التلقائي للمستخدم في جلسة منفصلة لأغراض الفوترة. وتبدأ الجلسة عندما يبدأ المستخدم في كتابة طلب بحث، وتنتهي عند اختيار مكان. يمكن أن تحتوي كل جلسة على طلبات بحث متعددة، متبوعة باختيار مكان واحد. بعد اختتام الجلسة، لن يصبح الرمز المميز صالحًا. يجب أن ينشئ تطبيقك رمزًا مميزًا جديدًا لكل جلسة. ننصحك باستخدام الرموز المميّزة للجلسة في جميع جلسات الإكمال التلقائي المبرمَجة (عند تضمين جزء أو تفعيل الإكمال التلقائي باستخدام هدف، ستتولّى واجهة برمجة التطبيقات هذا الإجراء تلقائيًا).
تستخدم حزمة تطوير برامج الأماكن لأجهزة 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()
وحدِّد ما يصل إلى خمس قيم type من الجدول 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(PlaceTypes.ADDRESS, PlaceTypes.ESTABLISHMENT));
Kotlin
autocompleteFragment.setTypesFilter(listOf(PlaceTypes.ADDRESS))
يوضّح مثال الرمز التالي الاتصال بـ setTypesFilter()
على
IntentBuilder
لضبط فلتر يعرض النتائج بدقة فقط مع تحديد مجموعة الأنواع.
لغة Java
Intent intent = new Autocomplete.IntentBuilder( AutocompleteActivityMode.FULLSCREEN, fields) .setTypesFilter(Arrays.asList(PlaceTypes.ADDRESS)) .build(this);
Kotlin
val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields) .setTypesFilter(listOf(PlaceTypes.ADDRESS)) .build(this)
فلترة النتائج حسب البلد
لفلترة نتائج الإكمال التلقائي إلى ما يصل إلى خمسة بلدان، يمكنك الاتصال بالرقم
setCountries()
لضبط رمز البلد.
ويمكنك بعد ذلك تمرير الفلتر إلى جزء أو قصد. ويجب إدخال البلدان كرمز بلد متوافق وفقًا لمعيار ISO 3166-1 Alpha-2.
يوضّح مثال الرمز التالي الاتصال بالرقم setCountries()
على
AutocompleteSupportFragment
لضبط فلتر يعرض النتائج ضمن
البلدان المحدّدة فقط.
لغة Java
autocompleteFragment.setCountries("AU", "NZ");
Kotlin
autocompleteFragment.setCountries("AU", "NZ")
حدود الاستخدام
لم يعد استخدامك لواجهة برمجة تطبيقات الأماكن، بما في ذلك حزمة تطوير البرامج (SDK) للأماكن المخصصة لأجهزة Android، يقتصر على الحدّ الأقصى لعدد الطلبات في اليوم (QPD). ومع ذلك، لا تزال حدود الاستخدام التالية سارية:
- يبلغ الحد الأقصى لمعدّل الضريبة 100 طلب في الثانية (QPS). ويتم احتسابه كمجموع الطلبات من جهة العميل والخادم لجميع التطبيقات التي تستخدم بيانات اعتماد المشروع نفسه.
عرض الإحالات في تطبيقك
- إذا كان تطبيقك يستخدم خدمة الإكمال التلقائي آليًا، يجب أن تعرض واجهة المستخدم الإحالة "بواسطة Google"، أو تظهر ضمن خريطة تحمل علامة Google التجارية.
- إذا كان تطبيقك يستخدم أداة الإكمال التلقائي، ليس عليك اتخاذ أي إجراء إضافي (يتم عرض الإحالة المطلوبة تلقائيًا).
- إذا أردت استرداد معلومات إضافية عن المكان وعرضها بعد الحصول على مكان من خلال رقم التعريف، يجب أيضًا عرض إحالة الجهات الخارجية.
لمزيد من التفاصيل، يمكنك الاطّلاع على مستندات الإحالات.
تحسين عمليات الإكمال التلقائي للأماكن
يصف هذا القسم أفضل الممارسات لمساعدتك في الاستفادة إلى أقصى حد من خدمة "الإكمال التلقائي" للأماكن.
في ما يلي بعض الإرشادات العامة:
- إنّ أسرع طريقة لتطوير واجهة المستخدم صالحة هي استخدام أداة الإكمال التلقائي في "خرائط Google" أو حزمة تطوير برامج (SDK) للأماكن في نظام التشغيل Android تطبيق مصغّر تلقائي أو عنصر تحكّم آخر في حزمة تطوير البرامج (SDK) لعرض الأماكن لأجهزة iOS. التحكّم بالإكمال التلقائي لواجهة المستخدم
- اكتسِب فهمًا أساسيًا لحقول البيانات الخاصة بميزة "الإكمال التلقائي" من الأماكن من البداية.
- إنّ حقول انحياز الموقع الجغرافي وقيود الموقع الجغرافي اختيارية، ولكن يمكن أن يكون لها تأثير كبير في أداء الإكمال التلقائي.
- استخدِم التعامل مع الأخطاء للتأكّد من انخفاض مستوى أداء تطبيقك بشكلٍ سليم إذا كانت واجهة برمجة التطبيقات تعرض خطأً.
- احرص على أن يتعامل تطبيقك مع عدم توفّر أي خيار وأن يوفّر للمستخدمين طريقة للمتابعة.
أفضل ممارسات تحسين التكلفة
تحسين التكلفة الأساسية
لتحسين تكلفة استخدام خدمة "الإكمال التلقائي" للأماكن، استخدِم أقنعة الحقل في "تفاصيل المكان" والتطبيقات المصغّرة الخاصة بميزة "الإكمال التلقائي" لعرض حقول بيانات الأماكن التي تحتاج إليها فقط.
تحسين التكلفة المتقدّم
يمكنك التنفيذ الآلي للإكمال التلقائي للأماكن من أجل الوصول إلى التسعير حسب الطلب وطلب نتائج واجهة برمجة التطبيقات للترميز الجغرافي بشأن المكان المحدّد بدلاً من تفاصيل المكان. إنّ سعر كل طلب، مع واجهة برمجة التطبيقات الجغرافية، هو أكثر فعالية من حيث التكلفة من السعر لكل جلسة (مستند إلى الجلسة) إذا تم استيفاء الشرطين التاليين:
- إذا كنت بحاجة فقط إلى خط العرض/خط الطول أو عنوان المكان المحدّد للمستخدم، تقدّم واجهة برمجة التطبيقات للترميز الجغرافي هذه المعلومات بأقل من طلب بشأن تفاصيل المكان.
- إذا اختار المستخدمون عبارة بحث مقترَحة تلقائيًا ضمن متوسط أربعة عبارات بحث مقترَحة أو أقل، قد يكون سعر كل طلب أكثر فعالية من حيث التكلفة لكل جلسة.
هل يتطلب تطبيقك أي معلومات غير العنوان وخط العرض/خط الطول للتوقّع المحدّد؟
نعم، بحاجة إلى مزيد من التفاصيل
استخدام ميزة "الإكمال التلقائي" المستندة إلى الجلسات مع تفاصيل المكان.
بما أنّ طلبك يتطلّب تفاصيل المكان، مثل اسم المكان أو حالة النشاط التجاري أو ساعات العمل، يجب أن يستخدم تنفيذ ميزة "الإكمال التلقائي" للمكان رمزًا مميّزًا للجلسة (تلقائيًا أو مضمّنًا في أدوات Android أو Android أو iOS) بتكلفة إجمالية تبلغ 0.017 دولار أمريكي (أو ما يعادلها بالعملة المحلية) لكل جلسة بالإضافة إلى رموز تخزين البيانات للأماكن
تنفيذ الأدوات
يتم دمج إدارة الجلسات تلقائيًا في أدوات JavaScript أو Android أو iOS. ويتضمّن ذلك كلاً من طلبات الإكمال التلقائي للأماكن وطلب تفاصيل المكان على عبارة البحث المقترَحة التي تم اختيارها. تأكّد من تحديد المعلَمة fields
للتأكّد من أنك تطلب فقط حقول بيانات المكان التي تحتاج إليها.
التنفيذ الآلي
استخدِم الرمز المميّز للجلسة مع طلبات الإكمال التلقائي للأماكن. عند طلب تفاصيل المكان عن عبارة البحث المقترحة المحدّدة، أدرِج المعلّمات التالية:
- رقم تعريف المكان من الردّ التلقائي المتعلّق بالمكان
- الرمز المميز للجلسة المستخدم في طلب الإكمال التلقائي للأماكن
- المعلَمة
fields
التي تحدّد حقول بيانات المكان التي تحتاج إليها
لا، يحتاج فقط إلى العنوان والموقع
يمكن أن تكون واجهة برمجة التطبيقات للترميز الجغرافي خيارًا أكثر فعالية من حيث التكلفة مقارنةً بتفاصيل المكان المتعلقة بتطبيقك، وذلك استنادًا إلى أداء استخدامك لميزة "الإكمال التلقائي" للمكان. تختلف كفاءة الإكمال التلقائي لكل تطبيق بناءً على ما يدخله المستخدمون ومكان استخدام التطبيق وما إذا تم تنفيذ أفضل ممارسات تحسين الأداء.
للإجابة عن السؤال التالي، يجب تحليل عدد الأحرف التي يكتبها المستخدم في المتوسط قبل اختيار عبارة بحث مقترحة من خلال ميزة "الإكمال التلقائي" في تطبيقك.
هل يختار المستخدمون عبارات بحث مقترحة من خلال ميزة "الإكمال التلقائي للأماكن" في أربعة طلبات أو أقل في المتوسط؟
نعم
تنفيذ ميزة "الإكمال التلقائي" للأماكن من دون استخدام الرموز المميزة للجلسة واستدعاء واجهة برمجة التطبيقات للترميز الجغرافي في توقّع المكان المحدّد
تقدّم واجهة برمجة التطبيقات للترميز الجغرافي عناوين وإحداثيات خطوط العرض/خطوط الطول مقابل 0.005 دولار أمريكي لكل طلب. تبلغ تكلفة أربعة طلبات إكمال تلقائي - لكل طلب 0.01132 دولار أمريكي (أو ما يعادله بالعملة المحلية)، لذا سيكون إجمالي تكلفة أربعة طلبات بالإضافة إلى طلب استدعاء الترميز الجغرافي حول توقعات المكان المختارة هو 0.01632 دولار أمريكي (أو ما يعادله بالعملة المحلية)، وهو أقل من السعر التلقائي الذي يتم تقديمه لكل جلسة بنسبة 0.017 دولار أمريكي (أو ما يعادله بالعملة المحلية) لكل جلسة.1
ننصحك باستخدام أفضل الممارسات المتعلّقة بالأداء لمساعدة المستخدمين في الحصول على التوقّعات التي يبحثون عنها بعدد أقل من الأحرف.
غير متوافق
استخدام ميزة "الإكمال التلقائي" المستندة إلى الجلسات مع تفاصيل المكان.
بما أنّ متوسط عدد الطلبات الذي تتوقّع أن تقدّمه قبل أن يحدِّد أحد المستخدمين توقّعًا يتم إكماله تلقائيًا للمكان، فإن تنفيذ هذا الإجراء يجب أن يستخدم رمزًا مميّزًا للجلسة لكل من طلبات "الإكمال التلقائي" للمكان وطلب "تفاصيل المكان" المرتبط بتكلفة إجمالية قدرها 0.017 لكل جلسة.1
تنفيذ الأدوات
يتم دمج إدارة الجلسات تلقائيًا في أدوات JavaScript أو Android أو iOS. ويتضمّن ذلك كلاً من طلبات الإكمال التلقائي للأماكن وطلب تفاصيل المكان على عبارة البحث المقترَحة التي تم اختيارها. تأكّد من تحديد المعلمة fields
لضمان طلب حقول البيانات الأساسية فقط.
التنفيذ الآلي
استخدِم الرمز المميّز للجلسة مع طلبات الإكمال التلقائي للأماكن. عند طلب تفاصيل المكان عن عبارة البحث المقترحة المحدّدة، أدرِج المعلّمات التالية:
- رقم تعريف المكان من الردّ التلقائي المتعلّق بالمكان
- الرمز المميز للجلسة المستخدم في طلب الإكمال التلقائي للأماكن
- معلمة
fields
التي تحدد حقول البيانات الأساسية مثل العنوان والهندسة
ننصحك بتأجيل طلبات الإكمال التلقائي للأماكن
يمكنك استخدام استراتيجيات مثل تأخير طلب الإكمال التلقائي للأماكن إلى أن يكتب المستخدم أول ثلاثة أو أربعة أحرف، ما يتيح تقديم طلبات أقل لك. على سبيل المثال، عند تقديم طلبات الإكمال التلقائي للأماكن لكل حرف بعد كتابة المستخدم للحرف الثالث، يعني ذلك أنه إذا كتب المستخدم سبعة أحرف ثم اختار توقعًا تقدم طلبًا واحدًا لواجهة برمجة تطبيقات ترميز المواقع الجغرافية، ستكون التكلفة الإجمالية 0.01632 دولار أمريكي (4 * 0.00283 إكمال تلقائي لكل طلب + 0.005 دولار للترميز الجغرافي).1
إذا كان تأخّر إرسال الطلبات يمكن أن يظهر لك متوسط طلبك المبرمَج أقل من أربعة، يمكنك اتّباع الإرشادات المتعلقة بتنفيذ الإكمال التلقائي للأماكن من خلال واجهة برمجة التطبيقات الجغرافية. يُرجى العِلم أنّه يمكن اعتبار طلبات التأخير على أنها وقت استجابة من جانب المستخدم الذي قد يتوقّع رؤية توقعات مع كل ضغطة مفتاح جديدة.
ننصحك باستخدام أفضل الممارسات المتعلّقة بالأداء لمساعدة المستخدمين في الحصول على التوقّعات التي يبحثون عنها بعدد أحرف أقل.
-
التكاليف المُدرَجة هنا بالدولار الأمريكي. يُرجى الرجوع إلى صفحة الفوترة في "منصة خرائط Google" للحصول على معلومات كاملة عن الأسعار.
أفضل الممارسات المتعلقة بالأداء
توضّح الإرشادات التالية طرق تحسين أداء الإكمال التلقائي للأماكن:
- يمكنك إضافة قيود على البلدان وانحياز الموقع الجغرافي واللغة المفضّلة (في عمليات التنفيذ الآلية) إلى تنفيذ ميزة "الإكمال التلقائي" من المكان. ليس من الضروري اختيار اللغة المفضّلة مع التطبيقات المصغّرة، لأنّها تختار إعدادات اللغة المفضّلة من متصفّح المستخدم أو جهازه الجوّال.
- إذا كانت ميزة "الإكمال التلقائي" للأماكن مصحوبة بخريطة، يمكنك انحياز الموقع الجغرافي حسب إطار عرض الخريطة.
- في الحالات التي لا يختار فيها المستخدم أحد عبارات البحث المقترَحة ضمن ميزة "الإكمال التلقائي"، بشكلٍ عام، لأنّ أيًّا من عبارات البحث المقترَحة لا يمثّل عنوان النتيجة المطلوب، يمكنك إعادة استخدام الإدخال الأصلي للمستخدم لمحاولة الحصول على نتائج أكثر صلة:
- إذا كنت تتوقع أن يُدخِل المستخدم معلومات العنوان فقط، أعِد استخدام إدخال المستخدم الأصلي في استدعاء واجهة برمجة التطبيقات Geocode API.
- إذا كنت تعتقد أنّ المستخدم يُدخِل طلبات بحث عن مكان معيّن بالاسم أو العنوان، استخدِم طلب بحث عن مكان. وإذا كان من المتوقّع أن تكون النتائج في منطقة معيّنة فقط، استخدِم انحياز الموقع الجغرافي.
- المستخدمون الذين يُدخِلون عناوين مبانٍ فرعية في البلدان التي لا تتوفّر فيها خدمة الإكمال التلقائي للأماكن من العناوين الفرعية، مثل التشيك وإستونيا وليتوانيا على سبيل المثال، يشير العنوان التشيكي "Stroupeznického 3191/17, Praha" إلى توقّع جزئي في الإكمال التلقائي للأماكن.
- المستخدمون الذين يُدخلون عناوين تتضمّن بادئات أجزاء الطريق، مثل "23-30 29 St. Queens" في مدينة نيويورك أو "47 -380 Kamehameha Hwy, Kaneohe" على جزيرة "كواي" في "هاواي".
تحديد المشاكل وحلّها
على الرغم من وجود مجموعة متنوعة من الأخطاء، غالبًا ما تحدث أغلب الأخطاء التي من المحتمل أن يواجهها تطبيقك أخطاء في الإعداد (على سبيل المثال، تم استخدام مفتاح واجهة برمجة تطبيقات غير صحيح أو تم ضبط مفتاح واجهة برمجة التطبيقات بشكل غير صحيح) أو أخطاء الحصة (تجاوز تطبيقك حصته). اطّلِع على حدود الاستخدام لمزيد من المعلومات عن الحِصص.
يتم عرض الأخطاء التي تحدث أثناء استخدام عناصر التحكّم في الإكمال التلقائي في
ردّ الاتصال من onActivityResult()
. اتصل بـ Autocomplete.getStatus()
للحصول على رسالة الحالة للنتيجة.