تعرض ميزة "الإكمال التلقائي (جديد)" توقعات الأماكن استجابةً لطلب يتضمّن سلسلة بحث نصي وحدودًا جغرافية تتحكّم في منطقة البحث. يمكن أن تتطابق ميزة الإكمال التلقائي مع الكلمات الكاملة والسلاسل الفرعية من الإدخال، ما يؤدي إلى تحديد أسماء الأماكن والعناوين وPlus Codes. يمكن لتطبيقك إرسال طلبات البحث أثناء كتابة المستخدم، لتقديم توقّعات فورية للأماكن وطلبات البحث.
على سبيل المثال، يمكنك استدعاء ميزة "الإكمال التلقائي" باستخدام سلسلة تحتوي على بيانات جزئية أدخلها المستخدم، مثل "Sicilian piz"، مع حصر منطقة البحث في سان فرانسيسكو، كاليفورنيا. تحتوي الاستجابة بعد ذلك على قائمة بتوقّعات الأماكن التي تتطابق مع سلسلة البحث ومنطقة البحث، مثل المطعم المسمّى "Sicilian Pizza Kitchen". تم تصميم توقعات الأماكن التي يتم عرضها للمستخدم لمساعدته في اختيار المكان المطلوب. يمكنك إرسال طلب تفاصيل المكان (جديد) للحصول على مزيد من المعلومات حول أي من توقعات الأماكن التي تم عرضها.
يمكنك دمج وظيفة "الإكمال التلقائي (جديد)" في تطبيقك بطريقتَين رئيسيتَين:
- إضافة أداة الإكمال التلقائي للأماكن: توفّر هذه الأداة تجربة إكمال تلقائي جاهزة للاستخدام من خلال فئة
PlaceAutocompleteالتي تعرض عبارات بحث مقترحة أثناء كتابة المستخدم. - الحصول على توقّعات الأماكن آليًا: يمكنك طلب واجهة برمجة التطبيقات مباشرةً لاسترداد التوقّعات وعرضها في واجهة مستخدم مخصّصة.
إضافة أداة الإكمال التلقائي للأماكن
لتوفير تجربة متسقة وسهلة لاستخدام ميزة "الإكمال التلقائي للأماكن"، يمكنك إضافة أداة "الإكمال التلقائي للأماكن" إلى تطبيقك. توفّر الأداة واجهة مخصّصة بملء الشاشة تعالج إدخالات المستخدم وتعرض توقعات الأماكن للمستخدم مع عرض عناصر AutocompletePrediction للتطبيق. يمكنك بعد ذلك إرسال طلب تفاصيل المكان (جديد) للحصول على معلومات إضافية حول أي من توقعات الأماكن.
كما هو الحال عند الحصول على توقعات الأماكن آليًا،
تتيح لك أداة "الإكمال التلقائي للأماكن" استخدام الرموز المميزة للجلسات
لتجميع طلبات الإكمال التلقائي في جلسة لأغراض الفوترة. يمكنك تمرير رمز مميز للجلسة عند إنشاء نية استخدام التطبيق المصغّر من خلال استدعاء setAutocompleteSessionToken(). إذا لم تقدّم رمزًا مميّزًا للجلسة، ستنشئ لك الأداة رمزًا مميّزًا يمكنك الوصول إليه من خلال استدعاء getSessionTokenFromIntent(). لمزيد من المعلومات حول استخدام الرموز المميّزة للجلسات، يُرجى الاطّلاع على المقالة لمحة عن الرموز المميّزة للجلسات.
لإضافة أداة الإكمال التلقائي للمكان إلى تطبيقك، اتّبِع الخطوات التالية:
(اختياري) حدِّد رمزًا مميزًا للجلسة. إذا لم تقدّم رمزًا مميزًا للجلسة، ستنشئ لك الأداة رمزًا مميزًا.
حدِّد
autocompleteIntentباستخدام المَعلمات المطلوبة والرمز المميز للجلسة.حدِّد
ActivityResultLauncherلـStartActivityForResult. سيتولّى مشغّل التطبيقات هذا معالجة النتيجة التي يتم عرضها من نشاط الإكمال التلقائي.تعامَل مع النتيجة في دالة الاستدعاء الخاصة بـ
ActivityResultLauncher. يتضمن ذلك استخراجAutocompletePredictionوAutocompleteSessionToken(إذا لم تكن قد قدّمت بياناتك الخاصة)، ومعالجة الأخطاء، وإجراء طلبfetchPlace()اختياري للحصول على تفاصيل إضافية عن مكان معيّن.تشغيل الغرض باستخدام
placeAutocompleteActivityResultLauncher
توضّح النماذج التالية كيفية إضافة أداة الإكمال التلقائي للأماكن باستخدام كل من Kotlin وJava:
Kotlin
// Provide the API key that has enabled "Places API (New)" in the Google Cloud Console. Places.initializeWithNewPlacesApiEnabled(/* Context= */ context, /* API Key= */ key) // Optional, create a session token for Autocomplete request and the followup FetchPlace request. val sessionToken: AutocompleteSessionToken = AutocompleteSessionToken.newInstance() val autocompleteIntent: Intent = PlaceAutocomplete.createIntent(this) { // ... provide input params for origin, countries, types filter ... setAutocompleteSessionToken(sessionToken) } val placeAutocompleteActivityResultLauncher: ActivityResultLauncher<Intent> = registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult -> val intent = result.data if (intent != null && result.resultCode == PlaceAutocompleteActivity.RESULT_OK) { // get prediction object val prediction: AutocompletePrediction? = PlaceAutocomplete.getPredictionFromIntent(intent!!) // get session token val sessionToken: AutocompleteSessionToken? = PlaceAutocomplete.getSessionTokenFromIntent(intent!!) // create PlacesClient to make FetchPlace request (optional) val placesClient: PlacesClient = Places.createClient(this) val response = placesClient.awaitFetchPlace(prediction.placeId, Field.DISPLAY_NAME) { sessionToken = sessionToken // optional } } } // Launch Activity placeAutocompleteActivityResultLauncher.launch(autocompleteIntent)
جافا
// Provide the API key that has enabled "Places API (New)" in the Google Cloud Console. Places.initializeWithNewPlacesApiEnabled(/* Context= */ context, /* API Key= */ key); // Optional, create a session token for Autocomplete request and the followup FetchPlace request AutocompleteSessionToken sessionToken = AutocompleteSessionToken.newInstance(); Intent autocompleteIntent = new PlaceAutocomplete.IntentBuilder() // ... set input params for origin, countries, types filter ... .setSessionToken(sessionToken) // optional .build(this); ActivityResultLauncher<Intent> placeAutocompleteActivityResultLauncher = registerForActivityResult( new ActivityResultContracts.StartActivityForResult(), new ActivityResultCallback<ActivityResult>() { @Override public void onActivityResult(ActivityResult result) { Intent intent = result.getData(); if (result.getResultCode() == PlaceAutocompleteActivity.RESULT_OK) { // get prediction object AutocompletePrediction prediction = PlaceAutocomplete.getPredictionFromIntent( Preconditions.checkNotNull(intent)); // get session token AutocompleteSessionToken sessionToken = PlaceAutocomplete.getSessionTokenFromIntent( Preconditions.checkNotNull(intent)); // create PlacesClient to make FetchPlace request (optional) PlacesClient placesClient = Places.createClient(this); FetchPlaceRequest request = FetchPlaceRequest.builder(prediction.getPlaceId(), Arrays.asList(Field.DISPLAY_NAME)) .setSessionToken(sessionToken).build(); Task<FetchPlaceResponse> task = placesClient.fetchPlace(request); } } } ); // Launch Activity placeAutocompleteActivityResultLauncher.launch(autocompleteIntent);
تخصيص المظهر
عند إنشاء تجربة "إكمال تلقائي"، يمكنك تحديد مظهر يلغي أيًّا من سمات الأنماط التلقائية. يمكنك تخصيص ألوان وخطوط ومسافات وحدود وزوايا مكوّن "الإكمال التلقائي للأماكن". القيمة التلقائية هي
PlacesMaterialTheme. تستخدم أي سمات مظهر لم يتم إلغاؤها الأنماط التلقائية.
يمكنك تحديد عمليات إلغاء المظهر في …/res/values/themes.xml. على سبيل المثال:
<?xml version="1.0" encoding="utf-8"?> <resources> <style name="BrandedTheme" parent="PlacesMaterialTheme"> <!-- Color tokens. --> <item name="placesColorOnNeutralContainer">#5300e8</item> <item name="placesColorOnNeutralContainerVariant">#ee6002</item> ... <!-- Typography tokens. --> <item name="placesTextAppearanceTitleLarge">@style/PlacesTextAppearance</item> <item name="placesTextAppearanceBodyMedium">@style/PlacesTextAppearance</item> ... <!-- Spacing tokens. --> <item name="placesSpacingSmall">6dp</item> <item name="placesSpacingMedium">12dp</item> ... <!-- Attribution tokens. --> <item name="placesColorAttributionLightTheme">white</item> <item name="placesColorAttributionDarkTheme">black</item> </style> </resources>
يمكنك بعد ذلك الإشارة إلى أنماط الإلغاء من خلال استدعاء setAutocompleteUiCustomization:
ActivityResultLauncher<Intent> placeAutocompleteActivityResultLauncher = registerForActivityResult( new ActivityResultContracts.StartActivityForResult(), new ActivityResultCallback<ActivityResult>() { @Override public void onActivityResult(ActivityResult result) { Intent intent = result.getData(); if (intent != null) { AutocompletePrediction prediction = PlaceAutocomplete.getPredictionFromIntent(intent); AutocompleteSessionToken sessionToken = PlaceAutocomplete.getSessionTokenFromIntent(intent); Status status = PlaceAutocomplete.getResultStatusFromIntent(intent); ... } } } ); Intent placeAutocompleteIntent = new PlaceAutocomplete.IntentBuilder() .setInitialQuery("INSERT_QUERY_TEXT") .setOrigin(new LatLng(10.0, 10.0)) ... .setAutocompleteUiCustomization( AutocompleteUiCustomization.builder() .listItemIcon(AutocompleteUiIcon.noIcon()) .listDensity(AutocompleteListDensity.MULTI_LINE) .theme(R.style.BrandedTheme) .build()) .build(this); placeAutocompleteActivityResultLauncher.launch(placeAutocompleteIntent);
الحصول على توقعات الأماكن آليًا
يمكن لتطبيقك الحصول على قائمة بأسماء الأماكن و/أو العناوين المتوقّعة من
واجهة برمجة التطبيقات الخاصة بميزة "الإكمال التلقائي" من خلال طلب
PlacesClient.findAutocompletePredictions()،
وتمرير عنصر
FindAutocompletePredictionsRequest. يعرض المثال أدناه طلبًا كاملاً إلى
PlacesClient.findAutocompletePredictions().
Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();
LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);
final FindAutocompletePredictionsRequest autocompletePlacesRequest =
FindAutocompletePredictionsRequest.builder()
.setQuery("Sicilian piz")
.setRegionCode("ES")
.setLocationRestriction(circle)
.build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
.addOnSuccessListener(
(response) -> {
List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
}
).addOnFailureListener(
exception -> {
Log.e(TAG, "some exception happened" + exception.getMessage());
})
);ردود الإكمال التلقائي (جديدة)
تعرض واجهة برمجة التطبيقات
FindAutocompletePredictionsResponse
في
Task.
يحتوي
FindAutocompletePredictionsResponse
على قائمة تضم ما يصل إلى خمسة عناصر
AutocompletePrediction
تمثّل الأماكن المتوقّعة. قد تكون القائمة فارغة إذا لم يكن هناك مكان معروف يتطابق مع طلب البحث ومعايير الفلتر.
بالنسبة إلى كل مكان متوقّع، يمكنك استدعاء الطرق التالية لاسترداد تفاصيل المكان:
- تعرض
getFullText(CharacterStyle)النص الكامل لوصف المكان. هذا مزيج من النص الأساسي والثانوي. مثال: "برج إيفل، شارع أناتول فرانس، باريس، فرنسا". بالإضافة إلى ذلك، يتيح لك هذا الإجراء تمييز أقسام الوصف التي تتطابق مع البحث باستخدام نمط من اختيارك، وذلك باستخدامCharacterStyle. مَعلمةCharacterStyleاختيارية. اضبط القيمة على null إذا لم تكن بحاجة إلى أي تمييز. getPrimaryText(CharacterStyle)تعرض النص الرئيسي الذي يصف مكانًا. عادةً ما يكون هذا هو اسم المكان. أمثلة: "برج إيفل" و "شارع التحرير 123".getSecondaryText(CharacterStyle)تعرض النص الفرعي لوصف المكان. ويُعدّ ذلك مفيدًا، على سبيل المثال، كسطر ثانٍ عند عرض عبارات البحث المقترحة. أمثلة: "Avenue Anatole France, Paris, France" و "Sydney, New South Wales".getPlaceId()تعرض رقم تعريف المكان المتوقّع. رقم تعريف المكان هو معرّف نصي يحدّد مكانًا بشكل فريد، ويمكنك استخدامه لاسترداد عنصرPlaceمرة أخرى لاحقًا. لمزيد من المعلومات حول أرقام تعريف الأماكن في ميزة "الإكمال التلقائي"، يُرجى الاطّلاع على تفاصيل المكان (الإصدار الجديد). للحصول على معلومات عامة عن أرقام تعريف الأماكن، يُرجى الاطّلاع على نظرة عامة على رقم تعريف المكان.- تعرض السمة
getTypes()قائمة بأنواع الأماكن المرتبطة بهذا المكان. getDistanceMeters()تعرض المسافة المستقيمة بالأمتار بين هذا المكان ونقطة الانطلاق المحدّدة في الطلب.
المعلمات المطلوبة
-
طلب البحث
سلسلة النص المطلوب البحث عنها حدِّد الكلمات الكاملة والسلاسل الفرعية وأسماء الأماكن والعناوين ورموز Plus Codes. تعرض خدمة "الإكمال التلقائي (جديدة)" نتائج مطابقة محتملة استنادًا إلى هذه السلسلة، وترتّب النتائج حسب مدى صلتها بموضوع البحث.
لضبط مَعلمة طلب البحث، استدعِ طريقة
setQuery()عند إنشاء العنصرFindAutocompletePredictionsRequest.
المعلمات الاختيارية
-
الأنواع الأساسية
قائمة تضم ما يصل إلى خمس قيم من أنواع الجدول "أ" أو الجدول "ب" تُستخدَم لفلترة الأماكن التي يتم عرضها في الاستجابة. يجب أن يتطابق المكان مع إحدى قيم الأنواع الأساسية المحدّدة ليتم تضمينه في الاستجابة.
يمكن أن يكون للمكان نوع أساسي واحد فقط من الأنواع الواردة في الجدول "أ" أو الجدول "ب" المرتبطة به. على سبيل المثال، قد يكون النوع الأساسي
"mexican_restaurant"أو"steak_house".يتم رفض الطلب مع ظهور الخطأ
INVALID_REQUESTفي الحالات التالية:- تم تحديد أكثر من خمسة أنواع.
- يتم تحديد أي أنواع غير معروفة.
لضبط مَعلمة الأنواع الأساسية، استخدِم طريقة
setTypesFilter()عند إنشاء عنصرFindAutocompletePredictionsRequest. -
البلدان
يتم تضمين النتائج من قائمة البلدان المحدّدة فقط، والتي يتم تحديدها كقائمة تضم ما يصل إلى 15 قيمة من قيم نطاق المستوى الأعلى الذي يتم ترميزه حسب البلد (ccTLD) المكوّنة من حرفَين. في حال عدم تضمينها، لن يتم تطبيق أي قيود على الردّ. على سبيل المثال، لحصر المناطق في ألمانيا وفرنسا:
إذا حدّدت كلاً من
locationRestrictionوincludedRegionCodes، ستظهر النتائج في منطقة تقاطع الإعدادَين.لضبط مَعلمة البلدان، استدعِ طريقة
setCountries()عند إنشاء العنصرFindAutocompletePredictionsRequest. -
إزاحة الإدخال
تمثّل هذه السمة إزاحة أحرف Unicode المستندة إلى الصفر والتي تشير إلى موضع المؤشر في طلب البحث. يمكن أن يؤثر موضع المؤشر في التوقعات التي يتم عرضها. إذا كان هذا الحقل فارغًا، يتم ضبطه تلقائيًا على طول طلب البحث.
لضبط مَعلمة إزاحة الإدخال، استخدِم طريقة
setInputOffset()عند إنشاء عنصرFindAutocompletePredictionsRequest. تحيّز الموقع الجغرافي أو القيود المفروضة على الموقع الجغرافي
يمكنك تحديد تحيّز للموقع الجغرافي أو قيود على الموقع الجغرافي، ولكن ليس كليهما، لتحديد منطقة البحث. يمكنك اعتبار حصر النتائج حسب الموقع الجغرافي على أنّه تحديد المنطقة التي يجب أن تقع النتائج ضمنها، وتفضيل النتائج حسب الموقع الجغرافي على أنّه تحديد المنطقة التي يجب أن تكون النتائج قريبة منها. ويكمن الاختلاف الرئيسي في أنّه مع التحيز الجغرافي، قد يتم عرض نتائج من خارج المنطقة المحدّدة.
الانحياز حسب الموقع الجغرافي
تحدّد هذه السمة منطقة للبحث. يُعدّ هذا الموقع الجغرافي بمثابة تحيّز وليس قيدًا، لذا قد يتم عرض نتائج خارج المنطقة المحدّدة.
لضبط مَعلمة ميل الموقع الجغرافي، استدعِ الإجراء
setLocationBias()عند إنشاء العنصرFindAutocompletePredictionsRequest.القيود المفروضة على المواقع الجغرافية
تحدّد هذه السمة منطقة للبحث. لا يتم عرض نتائج خارج المنطقة المحدّدة.
لضبط مَعلمة تقييد الموقع الجغرافي، استخدِم الإجراء
setLocationRestriction()عند إنشاء العنصرFindAutocompletePredictionsRequest.
حدِّد المنطقة التي يتم فيها تطبيق التحيز أو القيود المتعلقة بالموقع الجغرافي على شكل إطار عرض مستطيل أو دائرة.
يتم تحديد الدائرة من خلال النقطة المركزية ونصف القطر بالمتر. يجب أن يتراوح نصف القطر بين 0.0 و50000.0 (بما يشمل هذين الرقمَين). القيمة التلقائية هي 0.0. بالنسبة إلى قيود الموقع الجغرافي، يجب ضبط النطاق على قيمة أكبر من 0.0. وفي حال عدم توفّرها، لن يعرض الطلب أي نتائج.
المستطيل هو إطار عرض لخطوط الطول والعرض، ويتم تمثيله كنقطتَي
lowوhighمتقابلتَين قطريًا. تُعتبر منطقة العرض منطقة مغلقة، ما يعني أنّها تتضمّن حدودها. يجب أن تتراوح حدود خطوط العرض بين -90 و90 درجة، ويجب أن تتراوح حدود خطوط الطول بين -180 و180 درجة:- إذا كان
low=high، يتألف إطار العرض من تلك النقطة الواحدة. - إذا كانت قيمة
low.longitudeأكبر من قيمةhigh.longitude، يتم عكس نطاق خط الطول (يعبر إطار العرض خط الطول 180 درجة). - إذا كانت قيمة
low.longitudeتساوي -180 درجة وقيمةhigh.longitudeتساوي 180 درجة، ستتضمّن إطار العرض جميع خطوط الطول. - إذا كانت قيمة
low.longitudeتساوي 180 درجة وقيمةhigh.longitudeتساوي -180 درجة، يكون نطاق خط الطول فارغًا.
يجب ملء كل من
lowوhigh، ويجب ألا يكون المربع الممثَّل فارغًا. يؤدي عدم توفّر إطار عرض إلى حدوث خطأ.- إذا كان
-
الأصل
تمثّل هذه السمة نقطة البداية التي يتم منها احتساب المسافة في خط مستقيم إلى الوجهة (يتم الوصول إليها باستخدام
getDistanceMeters()). وفي حال حذف هذه القيمة، لن يتم عرض المسافة في خط مستقيم. يجب تحديدها كإحداثيات خطوط الطول والعرض:لضبط مَعلمة المصدر، استدعِ الإجراء
setOrigin()عند إنشاء العنصرFindAutocompletePredictionsRequest. -
رمز المنطقة
رمز المنطقة المستخدَم لتنسيق الردّ، بما في ذلك تنسيق العنوان، ويتم تحديده كقيمة مكوّنة من حرفَين في نطاق المستوى الأعلى لرمز البلد (ccTLD). تتطابق معظم رموز نطاقات المستوى الأعلى لرمز البلد مع رموز ISO 3166-1، مع بعض الاستثناءات الملحوظة. على سبيل المثال، نطاق المستوى الأعلى لرمز البلد في المملكة المتحدة هو "uk" (.co.uk)، بينما رمز ISO 3166-1 هو "gb" (وهو يشير تقنيًا إلى الكيان "المملكة المتحدة لبريطانيا العظمى وأيرلندا الشمالية").
إذا حدّدت رمز منطقة غير صالح، ستعرض واجهة برمجة التطبيقات رسالة الخطأ
INVALID_ARGUMENT. يمكن أن تؤثر المَعلمة في النتائج استنادًا إلى القانون الساري.لضبط مَعلمة رمز المنطقة، استدعِ الإجراء
setRegionCode()عند إنشاء العنصرFindAutocompletePredictionsRequest. -
الرمز المميّز للجلسة
رموز الجلسات المميزة هي سلاسل من إنشاء المستخدمين تتتبّع طلبات الإكمال التلقائي (جديد)، أي الطلبات التي يتم إجراؤها من خلال الأداة والطلبات الآلية، باعتبارها "جلسات". تستخدم ميزة "الإكمال التلقائي" الرموز المميّزة للجلسات لتجميع مرحلتَي طلب البحث والاختيار في عملية بحث واحدة باستخدام ميزة "الإكمال التلقائي" في جلسة منفصلة لأغراض الفوترة. تبدأ الجلسة عندما يبدأ المستخدم بكتابة طلب بحث، وتنتهي عندما يختار مكانًا. يمكن أن تتضمّن كل جلسة طلبات بحث متعددة، يليها اختيار مكان واحد. بعد انتهاء الجلسة، يصبح الرمز المميّز غير صالح، ويجب أن ينشئ تطبيقك رمزًا مميّزًا جديدًا لكل جلسة. ننصح باستخدام الرموز المميّزة للجلسات لجميع جلسات الإكمال التلقائي الآلية (عند تضمين جزء أو تشغيل الإكمال التلقائي باستخدام نية، تتولّى واجهة برمجة التطبيقات ذلك تلقائيًا).
تستخدِم ميزة "الإكمال التلقائي"
AutocompleteSessionTokenلتحديد كل جلسة. يجب أن يمرِّر تطبيقك رمزًا مميزًا جديدًا للجلسة عند بدء كل جلسة جديدة، ثم يمرِّر الرمز المميز نفسه مع معرّف المكان في طلبfetchPlace()اللاحق لاسترداد "تفاصيل المكان" للمكان الذي اختاره المستخدم.لضبط مَعلمة الرمز المميز للجلسة، استدعِ طريقة
setSessionToken()عند إنشاء الكائنFindAutocompletePredictionsRequest.لمزيد من المعلومات، يُرجى الاطّلاع على الرموز المميزة للجلسات.
أمثلة على الإكمال التلقائي (الجديد)
استخدام ميزتَي "تقييد الموقع الجغرافي" و"الانحياز للموقع الجغرافي"
تستخدم ميزة "الإكمال التلقائي (جديد)" الانحياز لعنوان IP تلقائيًا للتحكّم في منطقة البحث. باستخدام ميزة "تفضيل عنوان IP"، تستخدم واجهة برمجة التطبيقات عنوان IP الخاص بالجهاز لتفضيل النتائج. يمكنك استخدام تقييد الموقع الجغرافي أو الانحياز للموقع الجغرافي، ولكن ليس كليهما، لتحديد منطقة للبحث.
يحدّد قيد الموقع الجغرافي المنطقة المطلوب البحث فيها. لا يتم عرض النتائج خارج المنطقة المحدّدة. يستخدم المثال التالي قيود الموقع الجغرافي للحدّ من الطلب إلى قيود الموقع الجغرافي الدائرية بنطاق جغرافي يبلغ 5,000 متر ويكون مركزه مدينة سان فرانسيسكو:
Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();
LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);
final FindAutocompletePredictionsRequest autocompletePlacesRequest =
FindAutocompletePredictionsRequest.builder()
.setQuery("Amoeba")
.setLocationRestriction(circle)
.build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
.addOnSuccessListener(
(response) -> {
List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
}
).addOnFailureListener(
exception -> {
Log.e(TAG, "some exception happened" + exception.getMessage());
})
);باستخدام ميزة "تحديد الموقع الجغرافي"، يعمل الموقع الجغرافي كعامل تحيّز، ما يعني أنّه يمكن عرض نتائج حول الموقع الجغرافي المحدّد، بما في ذلك النتائج خارج المنطقة المحدّدة. يغيّر المثال التالي الطلب السابق لاستخدام تحيّز الموقع الجغرافي:
Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();
LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);
final FindAutocompletePredictionsRequest autocompletePlacesRequest =
FindAutocompletePredictionsRequest.builder()
.setQuery("Amoeba")
.setLocationBias(circle)
.build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
.addOnSuccessListener(
(response) -> {
List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
}
).addOnFailureListener(
exception -> {
Log.e(TAG, "some exception happened" + exception.getMessage());
})
);استخدام الأنواع الأساسية
استخدِم المَعلمة primary types لحصر النتائج من طلب بحث على نوع معيّن كما هو موضّح في الجدول أ والجدول ب. يمكنك تحديد مصفوفة تتضمّن ما يصل إلى خمس قيم. في حال حذف هذه المَعلمة، يتم عرض جميع الأنواع.
يحدّد المثال التالي سلسلة طلب بحث "كرة قدم" ويستخدم مَعلمة الأنواع الأساسية لحصر النتائج بالمؤسسات من النوع "sporting_goods_store":
Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();
final List<Place.Field> primaryTypes = Arrays.asList("sporting_goods_store");
LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);
final FindAutocompletePredictionsRequest autocompletePlacesRequest =
FindAutocompletePredictionsRequest.builder()
.setQuery("Soccer")
.setIncludedPrimaryTypes(primaryTypes)
.setLocationBias(circle)
.build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
.addOnSuccessListener(
(response) -> {
List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
}
).addOnFailureListener(
exception -> {
Log.e(TAG, "some exception happened" + exception.getMessage());
})
);في حال حذف مَعلمة الأنواع الأساسية، يمكن أن تتضمّن النتائج مؤسسات من نوع قد لا تريده، مثل "athletic_field".
استخدام المصدر
عند تضمين مَعلمة origin في الطلب، والمحدّدة كإحداثيات خطوط العرض والطول، تتضمّن واجهة برمجة التطبيقات المسافة في خط مستقيم من نقطة الانطلاق إلى الوجهة في الاستجابة (يتم الوصول إليها باستخدام getDistanceMeters()). يضبط هذا المثال نقطة الانطلاق على وسط سان فرانسيسكو:
Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();
LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);
final FindAutocompletePredictionsRequest autocompletePlacesRequest =
FindAutocompletePredictionsRequest.builder()
.setQuery("Amoeba")
.setOrigin(center)
.setLocationRestriction(circle)
.build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
.addOnSuccessListener(
(response) -> {
List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
}
).addOnFailureListener(
exception -> {
Log.e(TAG, "some exception happened" + exception.getMessage());
})
);تحسين ميزة "الإكمال التلقائي (جديد)"
يوضّح هذا القسم أفضل الممارسات لمساعدتك في الاستفادة إلى أقصى حدّ من خدمة "الإكمال التلقائي (جديد)".
في ما يلي بعض الإرشادات العامة:
- أسرع طريقة لتطوير واجهة مستخدم فعّالة هي استخدام تطبيق "الإكمال التلقائي" (الجديد) المصغّر في Maps JavaScript API، أو تطبيق "الإكمال التلقائي" (الجديد) المصغّر في حزمة تطوير البرامج بالاستناد إلى بيانات "الأماكن" لنظام التشغيل Android، أو تطبيق "الإكمال التلقائي" (الجديد) المصغّر في حزمة تطوير البرامج بالاستناد إلى بيانات "الأماكن" لنظام التشغيل iOS.
- يمكنك فهم حقول البيانات الأساسية في ميزة "الإكمال التلقائي (جديد)" من البداية.
- إنّ حقول تحديد الموقع الجغرافي وحظر المواقع الجغرافية اختيارية، ولكن يمكن أن يكون لها تأثير كبير في أداء ميزة "الإكمال التلقائي".
- استخدِم معالجة الأخطاء للتأكّد من أنّ تطبيقك يتراجع بشكل سلس في حال عرضت واجهة برمجة التطبيقات خطأً.
- تأكَّد من أنّ تطبيقك يتعامل مع الحالات التي لا يتم فيها تحديد أي خيار، ويوفّر للمستخدمين طريقة للمتابعة.
أفضل الممارسات لتحسين التكلفة
تحسين التكلفة الأساسي
لتحسين تكلفة استخدام خدمة "الإكمال التلقائي" (الإصدار الجديد)، استخدِم أقنعة الحقول في أدوات "تفاصيل المكان" (الإصدار الجديد) و"الإكمال التلقائي" (الإصدار الجديد) لعرض حقول البيانات التي تحتاج إليها فقط في "الإكمال التلقائي" (الإصدار الجديد).
تحسين التكلفة المتقدّم
ننصحك بتنفيذ ميزة "الإكمال التلقائي (الجديدة)" آليًا للوصول إلى رمز التخزين التعريفي: أسعار طلبات الإكمال التلقائي وطلب نتائج Geocoding API حول المكان المحدّد بدلاً من ميزة "تفاصيل المكان (الجديدة)". يكون التسعير لكل طلب مع Geocoding API أكثر فعالية من حيث التكلفة مقارنةً بالتسعير لكل جلسة (المستند إلى الجلسة) في حال استيفاء الشرطَين التاليَين:
- إذا كنت بحاجة فقط إلى خط العرض وخط الطول أو عنوان المكان الذي اختاره المستخدم، توفّر Geocoding API هذه المعلومات بتكلفة أقل من طلب تفاصيل المكان (جديد).
- إذا اختار المستخدمون عبارة بحث مقترحة ضمن متوسط أربعة طلبات أو أقل من طلبات عبارات البحث المقترحة (الجديدة)، يمكن أن يكون السعر لكل طلب أقل تكلفة من السعر لكل جلسة.
هل يتطلّب تطبيقك أي معلومات أخرى غير العنوان وخط العرض/خط الطول للتوقّع المحدّد؟
نعم، يجب إضافة المزيد من التفاصيل
استخدِم ميزة "الإكمال التلقائي (جديد)" المستندة إلى الجلسة مع ميزة "تفاصيل المكان (جديد)".
بما أنّ تطبيقك يتطلّب استخدام ميزة "تفاصيل المكان (الجديدة)"، مثل اسم المكان أو حالة المؤسسة
أو ساعات العمل، يجب أن يستخدم تنفيذك لميزة "الإكمال التلقائي (الجديدة)" رمزًا مميزًا للجلسة
(برمجيًا أو مضمّنًا في تطبيقات
JavaScript
أو Android
أو iOS
المصغّرة)
لكل جلسة بالإضافة إلى رموز التخزين التعريفية السارية في Places،
استنادًا إلى حقول بيانات المكان التي تطلبها.1
تنفيذ التطبيق المصغّر
يتم دمج إدارة الجلسات تلقائيًا في التطبيقات المصغّرة
JavaScript
أو Android
أو iOS. ويشمل ذلك كلاً من طلبات "الإكمال التلقائي (الجديد)" وطلب "تفاصيل المكان (الجديد)"
بشأن عبارة البحث المقترَحة المحدّدة. تأكَّد من تحديد المَعلمة fields لضمان طلب حقول بيانات الإكمال التلقائي (الجديدة) التي تحتاج إليها فقط.
التنفيذ الآلي
استخدِم
رمزًا مميزًا للجلسة
مع طلبات "الإكمال التلقائي (الجديد)". عند طلب تفاصيل المكان (الإصدار الجديد) حول عبارة البحث المقترَحة المحدّدة، يجب تضمين المَعلمات التالية:
- رقم تعريف المكان من ردّ "الإكمال التلقائي (الجديد)"
- الرمز المميّز للجلسة المستخدَم في طلب الإكمال التلقائي (الجديد)
- المَعلمة
fieldsالتي تحدّد حقول بيانات ميزة "الإكمال التلقائي (جديد)" التي تحتاج إليها
لا، يجب توفير العنوان والموقع الجغرافي فقط
قد تكون Geocoding API خيارًا أكثر فعالية من حيث التكلفة من تفاصيل المكان (جديد) لتطبيقك، وذلك استنادًا إلى أداء استخدامك لميزة "الإكمال التلقائي (جديد)". تختلف كفاءة ميزة "الإكمال التلقائي (جديدة)" في كل تطبيق حسب ما يدخله المستخدمون ومكان استخدام التطبيق وما إذا تم تنفيذ أفضل ممارسات تحسين الأداء.
للإجابة عن السؤال التالي، عليك تحليل عدد الأحرف التي يكتبها المستخدم في المتوسط قبل اختيار عبارة مقترَحة من ميزة "الإكمال التلقائي (جديد)" في تطبيقك.
هل يختار المستخدمون توقّعًا من ميزة "الإكمال التلقائي (جديد)" في أربعة طلبات أو أقل في المتوسط؟
نعم
تنفيذ ميزة "الإكمال التلقائي (جديدة)" آليًا بدون رموز مميّزة للجلسة واستدعاء Geocoding API بشأن توقّع المكان المحدّد
توفّر واجهة Geocoding API العناوين وإحداثيات خطوط العرض والطول.
إنّ إجراء أربعة طلبات
إكمال تلقائي
بالإضافة إلى طلب بيانات من Geocoding API
بشأن عبارة البحث المقترَحة المحدّدة للمكان هو أقل من تكلفة الإكمال التلقائي (الجديد) لكل جلسة.1
ننصحك باتّباع أفضل الممارسات المتعلّقة بالأداء لمساعدة المستخدمين في الحصول على التوقّعات التي يبحثون عنها باستخدام عدد أقل من الأحرف.
لا
استخدِم ميزة "الإكمال التلقائي (جديد)" المستندة إلى الجلسة مع ميزة "تفاصيل المكان (جديد)".
بما أنّ متوسط عدد الطلبات التي تتوقّع إرسالها قبل أن يختار المستخدم
توقّعًا من ميزة "الإكمال التلقائي (جديد)" يتجاوز تكلفة التسعير لكل جلسة، يجب أن يستخدم تطبيقك
لميزة "الإكمال التلقائي (جديد)" رمزًا مميزًا للجلسة لكل من طلبات ميزة "الإكمال التلقائي (جديد)"
وطلب "تفاصيل المكان (جديد)" المرتبط
لكل جلسة.
1
تنفيذ التطبيق المصغّر
تتضمّن التطبيقات المصغّرة
JavaScript
وAndroid
وiOS
إدارة الجلسات تلقائيًا. ويشمل ذلك طلبات "الإكمال التلقائي (جديد)" وطلبات "تفاصيل المكان (جديد)" بشأن العبارة المقترَحة المحدّدة. احرص على تحديد مَعلمة fields لضمان طلب الحقول التي تحتاج إليها فقط.
التنفيذ آليًا
استخدِم
الرمز المميز للجلسة
مع طلبات "الإكمال التلقائي (جديد)".
عند طلب تفاصيل المكان (الإصدار الجديد) حول عبارة البحث المقترَحة المحدّدة،
يجب تضمين المَعلمات التالية:
- رقم تعريف المكان من ردّ "الإكمال التلقائي (الجديد)"
- الرمز المميّز للجلسة المستخدَم في طلب الإكمال التلقائي (الجديد)
- المَعلمة
fieldsالتي تحدّد الحقول، مثل العنوان والشكل الهندسي
تأخير طلبات "الإكمال التلقائي (جديد)"
يمكنك استخدام استراتيجيات مثل تأخير طلب "الإكمال التلقائي (جديد)" إلى أن يكتب المستخدم الأحرف الثلاثة أو الأربعة الأولى، وذلك لكي يقدّم تطبيقك عددًا أقل من الطلبات. على سبيل المثال، إذا أرسلت طلبات "الإكمال التلقائي (جديد)" لكل حرف بعد أن يكتب المستخدم الحرف الثالث، يعني ذلك أنّه إذا كتب المستخدم سبعة أحرف ثم اختار عبارة بحث مقترَحة ترسل لها طلب بيانات من واجهة برمجة التطبيقات واحدًا من Geocoding API، ستكون التكلفة الإجمالية مقابل 4 طلبات "الإكمال التلقائي (جديد)" لكل طلب + الترميز الجغرافي.1
إذا كان تأخير الطلبات سيؤدي إلى خفض متوسط الطلبات الآلية إلى أقل من أربعة، يمكنك اتّباع الإرشادات المتعلّقة بتنفيذ ميزة "الإكمال التلقائي" (الجديدة) عالية الأداء باستخدام Geocoding API. يُرجى العِلم أنّ تأخير الطلبات قد يظهر للمستخدم على أنّه وقت استجابة، وقد يتوقّع المستخدم ظهور عبارات بحث مقترَحة مع كل ضغطة مفتاح جديدة.
ننصحك باتّباع أفضل ممارسات الأداء لمساعدة المستخدمين في الحصول على التوقّع الذي يبحثون عنه بعدد أقل من الأحرف.
-
للاطّلاع على التكاليف، يُرجى الرجوع إلى قوائم أسعار "منصة خرائط Google".
أفضل الممارسات المتعلّقة بالأداء
توضّح الإرشادات التالية طرق تحسين أداء ميزة "الإكمال التلقائي (جديد)":
- أضِف القيود المفروضة على البلدان والانحياز للموقع الجغرافي واللغة المفضّلة (لعمليات التنفيذ الآلية) إلى عملية تنفيذ ميزة "الإكمال التلقائي (جديد)". لا حاجة إلى تحديد اللغة المفضّلة عند استخدام التطبيقات المصغّرة لأنّها تستند إلى اللغة المفضّلة المحدّدة في متصفّح المستخدم أو جهازه الجوّال.
- إذا كانت ميزة "الإكمال التلقائي (جديد)" مصحوبة بخريطة، يمكنك تحديد الموقع الجغرافي حسب إطار العرض في الخريطة.
- في الحالات التي لا يختار فيها المستخدم إحدى عبارات البحث المقترَحة من ميزة "الإكمال التلقائي (الجديدة)"، وذلك بشكل عام لأنّ أيًا من عبارات البحث المقترَحة هذه ليس عنوان النتيجة المطلوب، يمكنك إعادة استخدام إدخال المستخدم الأصلي لمحاولة الحصول على نتائج أكثر صلة بالموضوع:
- إذا كنت تتوقّع أن يُدخل المستخدم معلومات العنوان فقط، أعِد استخدام البيانات الأصلية التي أدخلها المستخدم في طلب إلى Geocoding API.
- إذا كنت تتوقّع أن يُدخل المستخدم طلبات بحث عن مكان معيّن بالاسم أو العنوان، استخدِم طلب "تفاصيل المكان (جديد)". إذا كان من المتوقّع ظهور النتائج في منطقة معيّنة فقط، استخدِم الانحياز للموقع الجغرافي.
- المستخدمون الذين يُدخلون عناوين فرعية، مثل عناوين وحدات أو شقق معيّنة داخل مبنى على سبيل المثال، يؤدي العنوان التشيكي "Stroupežnického 3191/17, Praha" إلى عرض عبارة بحث مقترَحة جزئية في ميزة "الإكمال التلقائي" (الإصدار الجديد).
- المستخدمون الذين يُدخلون عناوين تحتوي على بادئات لأجزاء من الطرق، مثل "23-30 29th St, Queens" في مدينة نيويورك أو "47-380 Kamehameha Hwy, Kaneohe" في جزيرة كاواي في هاواي
تحديد الموقع الجغرافي
يمكنك تحسين النتائج لمنطقة معيّنة من خلال تمرير مَعلمة location ومَعلمة radius. يؤدي ذلك إلى توجيه ميزة "الإكمال التلقائي (جديد)" إلى تفضيل عرض النتائج ضمن المنطقة المحدّدة. وقد يستمر عرض النتائج خارج المنطقة المحدّدة. يمكنك استخدام المَعلمة includedRegionCodes لفلترة النتائج
وعرض الأماكن ضمن بلد محدّد فقط.
تقييد الموقع الجغرافي
يمكنك حصر النتائج بمنطقة معيّنة من خلال تمرير مَعلمة locationRestriction.
يمكنك أيضًا حصر النتائج بالمنطقة المحدّدة بواسطة location
والمَعلمة radius، وذلك من خلال إضافة المَعلمة
locationRestriction. يوجّه هذا الإعداد ميزة "الإكمال التلقائي (جديدة)" لعرض النتائج فقط ضمن تلك المنطقة.