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

اختيار النظام الأساسي: Android iOS JavaScript Web Service

المطوّرون في المنطقة الاقتصادية الأوروبية

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

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

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

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

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

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

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

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

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

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

إصدار Places Swift SDK

أنشئ طلب إكمال تلقائي من خلال استدعاء إحدى الطرق في PlacesClient. يمكنك تمرير المَعلمات في عنصر AutocompleteRequest. يقدّم الردّ اقتراحات الإكمال التلقائي ضمن AutocompletePlaceSuggestion عنصر.

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

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

Places Swift SDK

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.
}

Swift

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

Objective-C

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.
    }
  }
}];

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

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

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

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

query

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

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

sessionToken

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

يمكنك عرض رمز الجلسة الخاص بميزة "الإكمال التلقائي للأماكن" لتمريره إلى خدمات أخرى لا تشكّل جزءًا من حزمة تطوير البرامج Places SDK لنظام التشغيل iOS، مثل التحقّق من صحة العنوان:

Places Swift SDK

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

Objective-C

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:

Places Swift SDK

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

Swift

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

Objective-C

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

البلدان

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

Places Swift SDK

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

Swift

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

Objective-C

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. وفي حال عدم توفّرها، لن يعرض الطلب أي نتائج.

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

Places Swift SDK

let center = CLLocationCoordinate2DMake(40.477398, -74.259087)

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

let filter = AutocompleteFilter(coordinateRegionBias: bias)
  

Swift

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

filter.locationBias = GMSPlaceCircularLocationOption(center, radius)

Objective-C

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

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

Places Swift SDK

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

let filter = AutocompleteFilter(coordinateRegionBias: bias)
  

Swift

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

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

Objective-C

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). إذا تم حذف هذه القيمة، لن يتم عرض المسافة المستقيمة. يجب تحديدها كإحداثيات خطوط الطول والعرض:

Places Swift SDK

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

Swift

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

Objective-C

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

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

regionCode

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

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

shouldIncludePureServiceAreaBusinesses

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

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

Places Swift SDK

let filter = AutocompleteFilter()
filter.shouldIncludePureServiceAreaBusinesses = true

Swift

let filter = AutocompleteFilter()
filter.shouldIncludePureServiceAreaBusinesses = true

Objective-C

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

إضافة أداة الإكمال التلقائي للأماكن

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

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

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

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

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

مَعلمات أداة "الإكمال التلقائي للأماكن"

بالإضافة إلى المَعلمات المتاحة برمجيًا، تقدّم أداة Place Autocomplete أيضًا المَعلمات التالية.

إظهار

تحدِّد show ما إذا كان سيتم عرض الأداة.

onSelection

الدالة التي سيتم تنفيذها عند اختيار مكان.

onError

الدالة البرمجية التي سيتم تنفيذها عند حدوث خطأ. سيتم تمرير PlacesError في حال حدوث خطأ.

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

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

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

الاطّلاع على مثال للرمز الكامل

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

استخدام locationRestriction وlocationBias

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

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

Places Swift SDK

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.
}
  

Swift

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

Objective-C

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.
    }
  }
}];

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

Places Swift SDK

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.
}
  

Swift

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

Objective-C

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.
    }
  }
}];

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

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

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

Places Swift SDK

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.
}
    

Swift

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

Objective-C

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.

يضبط هذا المثال نقطة الأصل على مركز مدينة سان فرانسيسكو:

Places Swift SDK

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.
}
  

Swift

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

Objective-C

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.
      }
    }
}];

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

Swift

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

إضافة أداة الإكمال التلقائي للأماكن (الرمز الكامل)

Places Swift SDK

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

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

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

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

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

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

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

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

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

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

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

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

نعم، يجب إضافة المزيد من التفاصيل

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

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

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

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

لا، يحتاج فقط إلى العنوان والموقع الجغرافي

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

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

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

نعم

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

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

لا

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

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

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

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

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

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

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


  1. للاطّلاع على التكاليف، يُرجى الرجوع إلى قوائم أسعار "منصة خرائط Google".

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

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

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

تفضيل المواقع الجغرافية

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

تقييد الموقع الجغرافي

لحصر النتائج في منطقة محدّدة، أضِف المَعلمة locationRestriction.

يمكنك أيضًا حصر النتائج بالمنطقة المحدّدة بواسطة location والمَعلمة radius، وذلك من خلال إضافة المَعلمة locationRestriction. يوجّه هذا الإعداد ميزة &quot;الإكمال التلقائي (الجديدة)&quot; لعرض نتائج فقط ضمن تلك المنطقة.