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

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

يمكن لخدمة "الإكمال التلقائي (جديد)" مطابقة الكلمات الكاملة والسلاسل الفرعية من الإدخال، وتحليل أسماء الأماكن والعناوين ورموز Plus Codes. وبالتالي، يمكن للتطبيقات إرسال طلبات البحث أثناء كتابة المستخدم، لتقديم اقتراحات فورية للأماكن.

اقتراحات الأماكن هي أماكن، مثل المؤسسات والعناوين والنقاط المهمة، استنادًا إلى سلسلة نص الإدخال المحدّدة ومنطقة البحث.

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

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

يمكنك دمج وظيفة "الإكمال التلقائي (الجديد)" في تطبيقك بطريقتَين رئيسيتَين:

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

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

طلبات الإكمال التلقائي (الجديدة)

أنشئ طلب إكمال تلقائي من خلال استدعاء طريقة في GMSPlacesClient. يمكنك تمرير المَعلمات في العنصر GMSAutocompleteRequest. يقدّم الردّ اقتراحات للإكمال التلقائي ضمن عنصر GMSAutocompletePlaceSuggestion.

يجب توفير مفتاح واجهة برمجة التطبيقات ومَعلمات query. يمكنك أيضًا تضمين GMSAutocompleteSessionToken لربط الطلبات بجلسة فوترة و GMSAutocompleteFilter لتطبيقها على النتائج.

لمزيد من المعلومات عن المَعلمات المطلوبة والاختيارية، يُرجى الاطّلاع على قسم المَعلمات في هذا المستند.

let center = (37.3913916, -122.0879074)
let northEast = (37.388162, -122.088137)
let southWest = (37.395804, -122.077023)

let bias = RectangularCoordinateRegion(northEast: northEast, southWest: southWest)
let filter = AutocompleteFilter(types: [ .restaurant ], origin: center, coordinateRegionBias: bias)

let autocompleteRequest = AutocompleteRequest(query: "Sicilian piz", filter: filter)
switch await placesClient.fetchAutocompleteSuggestions(with: autocompleteRequest) {
case .success(let autocompleteSuggestions):
  // Handle suggestions.
case .failure(let placesError):
  // Handle error.
}

let token = GMSAutocompleteSessionToken()

let northWestBounds = CLLocationCoordinate2DMake(40.921628, -73.700051)
let southEastBounds = CLLocationCoordinate2DMake(40.477398, -74.259087)

let filter = GMSAutocompleteFilter()
filter.types = [kGMSPlaceTypeRestaurant]
filter.locationBias = GMSPlaceRectangularLocationOption(northWestBounds, southEastBounds)

let request = GMSAutocompleteRequest(query:"Spagh")
request.filter = filter
request.sessionToken = token

GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { ( results, error ) in
      if let error = error {
        print("Autocomplete error: \(error)")
        return
      }
      if let autocompleteResults = results {
        for result in autocompleteResults {
          print("Result \(String(describing: result.placeSuggestion?.placeID)) with \(String(describing: result.placeSuggestion?.attributedFullText))")
        }
      }
    })

CLLocationCoordinate2D northEast = CLLocationCoordinate2DMake(37.388162, -122.088137);
CLLocationCoordinate2D southWest = CLLocationCoordinate2DMake(37.395804, -122.077023);

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.types = @[ kGMSPlaceTypeRestaurant ];
filter.locationBias = GMSPlaceRectangularLocationOption(northEast, southWest);
GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Sicilian piz"];
request.sessionToken = token;
request.filter = filter;

[[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request callback:^(NSArray<GMSAutocompleteSuggestion *> * results, NSError * error){
  // Handle response
  for (GMSAutocompleteSuggestion *suggestion in results) {
    if (suggestion.placeSuggestion) {
      // Show place suggestion data.
    }
  }
}];

ردود الإكمال التلقائي (الجديدة)

تعرض ميزة "الإكمال التلقائي" مصفوفة تتضمّن ما يصل إلى خمسة مثيلات من النوع GMSAutocompleteSuggestion. تحتوي الصفيفة على:

• placeID
• ‫types: الأنواع التي تنطبق على هذا المكان
• ‫distanceMeters: المسافة من نقطة الانطلاق
• ‫attributedFullText: النص الكامل لاقتراح يمكن لشخص عادي قراءته
• ‫attributedPrimaryText: النص الأساسي للاقتراح الذي يمكن لشخص عادي قراءته
• ‫attributedSecondaryText: نص ثانوي يمكن لشخص عادي قراءته لاقتراح معيّن
• ‫structuredFormat: الاسم المحدّد والنص التوضيحي، مثل المدينة أو المنطقة

المعلمات المطلوبة

query

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

المعلمات الاختيارية

sessionToken

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

يمكنك عرض الرمز المميّز لجلسة "الإكمال التلقائي للأماكن" من أجل تمريره إلى خدمات أخرى ليست جزءًا من حزمة Places SDK لأجهزة iOS، مثل Address Validation:

let token = AutocompleteSessionToken()
let filter = AutocompleteFilter(origin: CLLocationCoordinate2DMake(39.7, -94.5))
let request = AutocompleteRequest(query: "Piz", sessionToken: token, filter: filter)

PlacesClient.shared.fetchAutocompleteSuggestions(request: request) {
    case .success(let suggestions):
      ...
    case .failure(let placesError):
      print(placesError) 
}

// pass token's string format to use with a service that is not a part of iOS SDK.
print("token: \(token)")

GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Piz"];
GMSAutocompleteSessionToken *token = [[GMSAutocompleteSessionToken alloc] init];
request.sessionToken = token;

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.origin = [[CLLocation alloc] initWithLatitude:39.7 longitude:-94.5];
filter.locationBias = GMSPlaceRectangularLocationOption(topLocation, bottomLocation);

request.filter = filter;
 [[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request
                     callback:^(NSArray<GMSAutocompleteSuggestion *> *_Nullable results,
                                NSError *_Nullable error) {
  ...
}];

// pass token's string format to use with a service that is not a part of iOS SDK.
NSLog(@"%@", token.description);

لمزيد من المعلومات، يُرجى الاطّلاع على الرموز المميّزة للجلسات.

مَعلمات AutocompleteFilter الاختيارية

الأنواع

يمكن أن يكون للمكان نوع أساسي واحد فقط من الأنواع الواردة في الجدول أ أو الجدول ب المرتبطة به. على سبيل المثال، قد يكون النوع الأساسي mexican_restaurant أو steak_house.

تعرض واجهة برمجة التطبيقات تلقائيًا جميع الأماكن استنادًا إلى المَعلمة input، بغض النظر عن قيمة النوع الأساسي المرتبطة بالمكان. يمكنك حصر النتائج على نوع أساسي معيّن أو أنواع أساسية معيّنة من خلال تمرير المَعلمة types.

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

يتم رفض الطلب مع ظهور الخطأ INVALID_REQUEST في الحالات التالية:

• تم تحديد أكثر من خمسة أنواع.
• يتم تحديد أي أنواع غير معروفة.

على سبيل المثال، لحصر النتائج في متاجر السلع الرياضية، حدِّد هذا النوع في AutocompleteFilter:

let filter = AutocompleteFilter(types: [ PlaceType(rawValue: "sporting_goods_store") ])
  

let filter = GMSAutocompleteFilter()
filter.types = ["sporting_goods_store"]
  

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.types = @[ "sporting_goods_store" ];

البلدان

تضمين النتائج من قائمة المناطق المحدّدة فقط، والتي يتم تحديدها كمصفوفة تضم ما يصل إلى 15 قيمة من حرفين لنطاقات ccTLD ("نطاق المستوى الأعلى"). في حال حذف هذه المَعلمة، لن يتم تطبيق أي قيود على الردّ. على سبيل المثال، لحصر المناطق في ألمانيا وفرنسا:

let filter = AutocompleteFilter(countries: ["DE", "FR"])
  

let filter = GMSAutocompleteFilter()
filter.countries = ["DE", "FR"]

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.countries = @[ @"DE", @"FR" ];

إذا حدّدت كلاً من locationRestriction وcountries، ستظهر النتائج في منطقة تقاطع الإعدادَين.

inputOffset

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

locationBias أو locationRestriction

يمكنك تحديد locationBias أو locationRestriction، ولكن ليس كليهما، لتحديد منطقة البحث. يمكنك اعتبار locationRestriction على أنّها تحدّد المنطقة التي يجب أن تقع النتائج ضمنها، وlocationBias على أنّها تحدّد المنطقة التي يجب أن تكون النتائج قريبة منها ولكن يمكن أن تقع خارجها.

• تحدّد السمة locationBias منطقة للبحث. يُستخدم هذا الموقع الجغرافي كعامل انحياز، ما يعني أنّه يمكن عرض النتائج حول الموقع الجغرافي المحدّد، بما في ذلك النتائج خارج المنطقة المحدّدة.

• تحدّد السمة locationRestriction منطقة للبحث. ولا يتم عرض النتائج خارج المنطقة المحدّدة.

حدِّد منطقة locationBias أو locationRestriction كنافذة عرض مستطيلة أو كدائرة.

يتم تحديد الدائرة من خلال نقطة المركز ونصف القطر بالمتر. يجب أن يتراوح نصف القطر بين 0.0 و50000.0 (ضمنًا). القيمة التلقائية هي 0.0. بالنسبة إلى locationRestriction، يجب ضبط نصف القطر على قيمة أكبر من 0.0. وإلا، لن يعرض الطلب أي نتائج.

على سبيل المثال:

let center = CLLocationCoordinate2DMake(40.477398, -74.259087)

let bias = CircularCoordinateRegion(center: center, radius: 1000.0)

let filter = AutocompleteFilter(coordinateRegionBias: bias)
  

let center = CLLocationCoordinate2DMake(40.730610, -73.935242)
let radius = 1000.0

filter.locationBias = GMSPlaceCircularLocationOption(center, radius)

CLLocationCoordinate2D center = CLLocationCoordinate2DMake(40.730610, -73.935242);
radius = 1000.0;

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.locationBias = GMSPlaceCircularLocationOption(center, radius);

المستطيل هو إطار عرض لخطوط العرض والطول، ويتم تمثيله كنقطتَين 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، ولا يمكن أن يكون المربّع الممثَّل فارغًا. يؤدي ترك نافذة العرض فارغة إلى حدوث خطأ.

على سبيل المثال، تشمل إطار العرض هذا مدينة نيويورك بالكامل:

let northEast = CLLocationCoordinate2DMake(40.477398, -74.259087)
let southWest = CLLocationCoordinate2DMake(40.921628, -73.700051)

let filter = AutocompleteFilter(coordinateRegionBias: bias)
  

let high = CLLocationCoordinate2DMake(40.921628, -73.700051)
let low = CLLocationCoordinate2DMake(40.477398, -74.259087)

let filter = GMSAutocompleteFilter()
filter.locationBias = GMSPlaceRectangularLocationOption(high, low)

CLLocationCoordinate2D high = CLLocationCoordinate2DMake(40.477398, -74.259087);
CLLocationCoordinate2D low = CLLocationCoordinate2DMake(440.921628, -73.700051);

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.locationBias = GMSPlaceRectangularLocationOption(high, low);

الأصل

نقطة الانطلاق التي يتم منها احتساب المسافة في خط مستقيم إلى الوجهة (يتم عرضها على شكل distanceMeters). في حال حذف هذه القيمة، لن يتم عرض المسافة في خط مستقيم. يجب تحديدها كإحداثيات خطوط العرض والطول:

let filter = AutocompleteFilter(origin: CLLocation(latitude: 37.395804, longitude: -122.077023))
  

let filter = GMSAutocompleteFilter()
filter.origin =  CLLocation(latitude: 37.395804, longitude: -122.077023)
 

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];

filter.origin = [[CLLocation alloc] initWithLatitude:37.395804 longitude: -122.077023];

regionCode

رمز المنطقة المستخدَم لتنسيق الردّ، ويتم تحديده كقيمة مكوّنة من حرفَين في نطاق المستوى الأعلى لرمز البلد (ccTLD). تتطابق معظم رموز ccTLD مع رموز ISO 3166-1، مع بعض الاستثناءات الملحوظة. على سبيل المثال، نطاق المستوى الأعلى الذي يمثّل رمز البلد للمملكة المتحدة هو "uk"‏ (‎.co.uk)، في حين أنّ رمز ISO 3166-1 هو "gb" (من الناحية الفنية لكيان "المملكة المتحدة لبريطانيا العظمى وأيرلندا الشمالية").

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

shouldIncludePureServiceAreaBusinesses

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

على سبيل المثال:

let filter = AutocompleteFilter()
filter.shouldIncludePureServiceAreaBusinesses = true

let filter = AutocompleteFilter()
filter.shouldIncludePureServiceAreaBusinesses = true

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.shouldIncludePureServiceAreaBusinesses = YES;

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

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

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

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

عند ضبط قيمة الربط show على true، سيتم نقل المستخدم إلى عرض بملء الشاشة حيث يمكنه اختيار مكان. أثناء كتابة المستخدم، يعرض التطبيق المصغّر اقتراحات لأماكن مثل الأنشطة التجارية والعناوين والمعالم السياحية. عندما يختار المستخدم مكانًا، يستدعي التطبيق المصغّر معالج onSelection مع المكان المحدّد، ويغلق العرض بملء الشاشة.

مَعلمات تطبيق "الإكمال التلقائي للأماكن" المصغّر

بالإضافة إلى المَعلمات المتاحة برمجيًا، تقدّم أداة "الإكمال التلقائي للمكان" أيضًا المَعلمات التالية.

إظهار

يحدّد show ما إذا كان سيتم عرض التطبيق المصغّر.

onSelection

الدالة الإغلاقية التي يتم تشغيلها عند اختيار مكان

onError

تمثّل هذه السمة الإغلاق الذي يتم تشغيله عند حدوث خطأ. سيتم تمرير PlacesError في حال حدوث خطأ.

تخصيص المحتوى والمظهر

تحدّد مَعلمات AutocompleteUICustomization تخصيصات واجهة المستخدم التي سيتم تطبيقها على التطبيق المصغّر. خيارات التخصيص هي:

• AutocompleteListDensity: تتيح لك هذه المَعلمة اختيار كثافة قائمة الاقتراحات، إما multiLine أو twoLine.
• AutocompleteUIIcon: تتيح لك هذه المَعلمة اختيار ما إذا كنت تريد عرض الرمز التلقائي لكل عنصر في القائمة.
• theme: تحدّد هذه المَعلمة مظهرًا مخصّصًا يلغي أيًّا من سمات الأنماط التلقائية. يمكنك تخصيص الألوان وأسلوب الخط والتباعد والحدود والزوايا في مكوّن "الإكمال التلقائي للمكان". القيمة التلقائية هي PlacesMaterialTheme. تستخدم أي سمات مظهر لم يتم إلغاؤها الأنماط التلقائية.

الاطّلاع على مثال كامل للرمز البرمجي

أمثلة على ميزة "الإكمال التلقائي (جديد)"

استخدام locationRestriction وlocationBias

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

يحدّد قيد الموقع الجغرافي المنطقة المطلوب البحث فيها. ولا يتم عرض النتائج خارج المنطقة المحدّدة. يستخدم المثال التالي حصر الموقع الجغرافي لحصر الطلب على حصر موقع جغرافي دائري بنصف قطر يبلغ 5000 متر مركزه في سان فرانسيسكو:

let center = (37.775061, -122.419400)
let radius = 5000.0
let restriction = CircularCoordinateRegion(center: center, radius: radius)
let filter = AutocompleteFilter(coordinateRegionRestriction: restriction)
let token = AutocompleteSessionToken()

let autocompleteRequest = AutocompleteRequest(query: "Sicilian piz", sessionToken: token, filter: filter)
switch await placesClient.fetchAutocompleteSuggestions(with: autocompleteRequest) {
case .success(let autocompleteSuggestions):
  for suggestion in autocompleteSuggestions {
    switch suggestion {
    case .place:
      // Show place suggestion data.
    }
  }
case .failure(let placesError):
  // Handle error.
}
  

let token = GMSAutocompleteSessionToken()

let center = CLLocationCoordinate2DMake(37.775061, -122.419400)
let radius = 5000.0

let filter = GMSAutocompleteFilter()
filter.locationRestriction = GMSPlaceCircularLocationOption(center, radius)

let request = GMSAutocompleteRequest(query:"Piz")
request.filter = filter
request.sessionToken = token

GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { ( results, error ) in
      if let error = error {
        print("Autocomplete error: \(error)")
        return
      }
      if let autocompleteResults = results {
        for result in autocompleteResults {
          print("Result \(String(describing: result.placeSuggestion?.placeID)) with \(String(describing: result.placeSuggestion?.attributedFullText))")
        }
      }
    })

CLLocationCoordinate2D center = CLLocationCoordinate2DMake(37.775061, -122.419400);
radius = 5000.0;

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.locationRestriction = GMSPlaceCircularLocationOption(center, radius);
GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Sicilian piz"];
request.sessionToken = token;
request.filter = filter;

[[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request callback:^(NSArray<GMSAutocompleteSuggestion *> * results, NSError * error){
  // Handle response
  for (GMSAutocompleteSuggestion *suggestion in results) {
    if (suggestion.placeSuggestion) {
      // Show place suggestion data.
    }
  }
}];

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

let center = (37.775061, -122.419400)
let radius = 5000.0
let bias = CircularCoordinateRegion(center: center, radius: radius)
let filter = AutocompleteFilter(coordinateRegionBias: bias)
let token = AutocompleteSessionToken()

let autocompleteRequest = AutocompleteRequest(query: "Sicilian piz", sessionToken: token, filter: filter)
switch await placesClient.fetchAutocompleteSuggestions(with: autocompleteRequest) {
case .success(let autocompleteSuggestions):
  for suggestion in autocompleteSuggestions {
    switch suggestion {
    case .place:
      // Show place suggestion data.
    }
  }
case .failure(let placesError):
  // Handle error.
}
  

let token = GMSAutocompleteSessionToken()

let center = CLLocationCoordinate2DMake(37.775061, -122.419400)
let radius = 5000.0

let filter = GMSAutocompleteFilter()
filter.locationBias = GMSPlaceCircularLocationOption(center, radius)

let request = GMSAutocompleteRequest(query:"Piz")
request.filter = filter
request.sessionToken = token

GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { ( results, error ) in
      if let error = error {
        print("Autocomplete error: \(error)")
        return
      }
      if let autocompleteResults = results {
        for result in autocompleteResults {
          print("Result \(String(describing: result.placeSuggestion?.placeID)) with \(String(describing: result.placeSuggestion?.attributedFullText))")
        }
      }
    })

CLLocationCoordinate2D center = CLLocationCoordinate2DMake(37.775061, -122.419400);
radius = 5000.0;

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.locationBias = GMSPlaceCircularLocationOption(center, radius);
GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Sicilian piz"];
request.sessionToken = token;
request.filter = filter;

[[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request callback:^(NSArray<GMSAutocompleteSuggestion *> * results, NSError * error){
  // Handle response
  for (GMSAutocompleteSuggestion *suggestion in results) {
    if (suggestion.placeSuggestion) {
      // Show place suggestion data.
    }
  }
}];

أنواع الاستخدام

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

يحدّد المثال التالي سلسلة طلب بحث "كرة قدم" ويستخدم مَعلمة الأنواع لحصر النتائج بالمؤسسات من النوع "sporting_goods_store":

let filter = AutocompleteFilter(types: [ PlaceType(rawValue: "sporting_goods_store") ])
let token = AutocompleteSessionToken()

let autocompleteRequest = AutocompleteRequest(query: "Soccer", sessionToken: token, filter: filter)
switch await placesClient.fetchAutocompleteSuggestions(with: autocompleteRequest) {
case .success(let autocompleteSuggestions):
  for suggestion in autocompleteSuggestions {
    switch suggestion {
    case .place:
      // Show place suggestion data.
    }
  }
case .failure(let placesError):
  // Handle error.
}
    

let token = GMSAutocompleteSessionToken()

let filter = GMSAutocompleteFilter()
filter.types = ["sporting_goods_store"]

let request = GMSAutocompleteRequest(query:"Soccer")
request.filter = filter
request.sessionToken = token

GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { ( results, error ) in
      if let error = error {
        print("Autocomplete error: \(error)")
        return
      }
      if let autocompleteResults = results {
        for result in autocompleteResults {
          print("Result \(String(describing: result.placeSuggestion?.placeID)) with \(String(describing: result.placeSuggestion?.attributedFullText))")
        }
      }
    })

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.types = @[ "sporting_goods_store" ];
GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Soccer"];
request.sessionToken = token;
request.filter = filter;

[[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request callback:^(NSArray<GMSAutocompleteSuggestion *> * results, NSError * error){
  // Handle response
  for (GMSAutocompleteSuggestion *suggestion in results) {
    if (suggestion.placeSuggestion) {
      // Show place suggestion data.
    }
  }
}];

استخدام المصدر

عند تضمين المَعلمة origin في الطلب، والمحدّدة كإحداثيات خطوط العرض والطول، تتضمّن واجهة برمجة التطبيقات المسافة في خط مستقيم من نقطة الانطلاق إلى الوجهة في الاستجابة. تعرض الاستجابة المسافة على أنّها distanceMeters.

يضبط هذا المثال نقطة الانطلاق على وسط مدينة دبي:

let filter = AutocompleteFilter(origin: CLLocation(latitude: 37.7749, longitude: -122.4194))
let token = AutocompleteSessionToken()

let autocompleteRequest = AutocompleteRequest(query: "Amoeba", sessionToken: token, filter: filter)
switch await placesClient.fetchAutocompleteSuggestions(with: autocompleteRequest) {
case .success(let autocompleteSuggestions):
  for suggestion in autocompleteSuggestions {
    switch suggestion {
    case .place:
      // Show place suggestion data.
    }
  }
case .failure(let placesError):
  // Handle error.
}
  

let token = GMSAutocompleteSessionToken()

let origin = CLLocation(latitude: 37.7749, longitude: -122.4194)

let filter = GMSAutocompleteFilter()

filter.origin =  origin

let request = GMSAutocompleteRequest(query:"Amoeba")
request.filter = filter
request.sessionToken = token

GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { ( results, error ) in
      if let error = error {
        print("Autocomplete error: \(error)")
        return
      }
      if let autocompleteResults = results {
        for result in autocompleteResults {
          print("Result \(String(describing: result.placeSuggestion?.placeID)) with \(String(describing: result.placeSuggestion?.attributedFullText)) and distance: \(String(describing: result.placeSuggestion?.distanceMeters))")
        }
      }
    })

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.origin = [[CLLocation alloc] initWithLatitude:37.395804 longitude:-122.077023];
GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Amoeba"];
request.sessionToken = token;
request.filter = filter;

[[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request callback:^(NSArray<GMSAutocompleteSuggestion *> * results, NSError * error){
  // Handle response
  for (GMSAutocompleteSuggestion *suggestion in results) {
    if (suggestion.placeSuggestion) {
      // Show place suggestion data.
      }
    }
}];

تخصيص المحتوى والمظهر

let uiCustomization = AutocompleteUICustomization(
    listDensity: .multiLine,
    listItemIcon: .noIcon,
    theme: PlacesMaterialTheme()
)

إضافة تطبيق مصغّر لميزة "الإكمال التلقائي للأماكن" (الرمز الكامل)

struct PlaceAutocompleteDemoView: View {

  @State private var fetchedPlace: Place?
  @State private var placesError: PlacesError?
  @State private var showWidget = false

  public var body: some View {
    VStack {
      Button("Search for a place") {
        showWidget.toggle()
      }
      .placeAutocomplete(
        show: $showWidget,
        onSelection: { (autocompletePlaceSuggestion, autocompleteSessionToken) in
          Task {
            let placesClient = await PlacesClient.shared
            let fetchPlaceRequest = FetchPlaceRequest(
              placeID: autocompletePlaceSuggestion.placeID,
              placeProperties: [.displayName, .formattedAddress],
              sessionToken: autocompleteSessionToken
            )

            switch await placesClient.fetchPlace(with: fetchPlaceRequest) {
            case .success(let place):
              print("Fetched place: \(place)")
              self.fetchedPlace = place
            case .failure(let placesError):
              print("Failed to fetch place: \(placesError)")
              self.placesError = placesError
            }
          }
        },
        onError: { placesError in
          self.placesError = placesError
        }
      )
    }
  }
}

تحسين ميزة "الإكمال التلقائي (جديد)"

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

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

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

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

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

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

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

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

• إذا كنت بحاجة فقط إلى خط العرض وخط الطول أو عنوان المكان الذي اختاره المستخدم، توفّر Geocoding API هذه المعلومات بتكلفة أقل من طلب تفاصيل المكان (الإصدار الجديد).
• إذا اختار المستخدمون عبارة بحث مقترحة ضمن متوسط أربعة طلبات أو أقل من طلبات عبارات البحث المقترحة (الجديدة)، يمكن أن يكون السعر لكل طلب أقل تكلفة من السعر لكل جلسة.

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

للعثور على متوسط عدد الطلبات للجدول، حلِّل عدد الأحرف التي يكتبها المستخدم في المتوسط قبل اختيار عبارة مقترَحة من ميزة "الإكمال التلقائي (جديد)" في تطبيقك.

الإكمال التلقائي المستنِد إلى الجلسة (جديد) مع تفاصيل المكان (جديد)

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

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

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

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

ميزة "الإكمال التلقائي" (الجديدة) لكل طلب مع Geocoding API

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

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

ميزة "الإكمال التلقائي (جديد)" المستندة إلى الجلسة للتطبيقات التي تستخدم العناوين فقط

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

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

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

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

ننصحك بتأخير طلبات "الإكمال التلقائي (جديد)"
يمكنك استخدام استراتيجيات مثل تأخير طلب "الإكمال التلقائي (جديد)" إلى أن يكتب المستخدم الأحرف الثلاثة أو الأربعة الأولى لكي يرسل تطبيقك عددًا أقل من الطلبات. على سبيل المثال، إذا أرسلت طلبات بيانات من واجهة برمجة التطبيقات "الإكمال التلقائي (جديد)" لكل حرف بعد أن يكتب المستخدم الحرف الثالث، يعني ذلك أنّه إذا كتب المستخدم سبعة أحرف ثم اختار عبارة بحث مقترَحة ترسل لها طلب بيانات من واجهة برمجة التطبيقات واحدًا من Geocoding API، ستكون التكلفة الإجمالية لـ 4 طلبات بيانات من واجهة برمجة التطبيقات "الإكمال التلقائي (جديد)" لكل طلب + الترميز الجغرافي.¹

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

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

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

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

• أضِف القيود المفروضة على البلدان والانحياز للموقع الجغرافي واللغة المفضّلة (لعمليات التنفيذ الآلية) إلى عملية تنفيذ ميزة "الإكمال التلقائي (جديد)". لا حاجة إلى تحديد اللغة المفضّلة في التطبيقات المصغّرة لأنّها تختار اللغات المفضّلة من متصفّح المستخدم أو جهازه الجوّال.
• إذا كانت ميزة "الإكمال التلقائي (جديد)" مصحوبة بخريطة، يمكنك تحديد الموقع الجغرافي حسب إطار العرض في الخريطة.
• في الحالات التي لا يختار فيها المستخدم إحدى عبارات البحث المقترَحة في ميزة "الإكمال التلقائي" (الجديدة)، لأنّ أيًا من هذه العبارات لا يمثّل العنوان المطلوب، يمكنك إعادة استخدام البيانات التي أدخلها المستخدم في الأصل لمحاولة الحصول على نتائج أكثر صلة:
  • إذا كنت تتوقّع أن يُدخل المستخدم معلومات العنوان فقط، أعِد استخدام البيانات التي أدخلها المستخدم الأصلي في طلب إلى Geocoding API.
  • إذا كنت تتوقّع أن يُدخل المستخدم طلبات بحث عن مكان معيّن حسب الاسم أو العنوان، استخدِم طلب "تفاصيل المكان (جديد)". إذا كان من المتوقّع ظهور النتائج في منطقة معيّنة فقط، استخدِم الانحياز للموقع الجغرافي.
  تشمل السيناريوهات الأخرى التي يُفضَّل فيها استخدام 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. يؤدي ذلك إلى توجيه ميزة "الإكمال التلقائي (جديد)" لعرض النتائج فقط ضمن تلك المنطقة.