اتّبِع هذا الدليل لرسم مسار داخل تطبيقك إلى وجهة واحدة باستخدام حزمة تطوير البرامج (SDK) للتنقّل على iOS.
نظرة عامة
- يمكنك دمج حزمة تطوير البرامج (SDK) للتنقّل في تطبيقك، كما هو موضّح في قسم إعداد مشروعك.
- يمكنك ضبط
GMSMapView. - يمكنك مطالبة المستخدم بقبول الأحكام والشروط، والسماح بخدمات الموقع الجغرافي والإشعارات في الخلفية.
- يمكنك إنشاء مصفوفة تحتوي على وجهة واحدة أو أكثر.
يمكنك تحديد
GMSNavigatorللتحكّم في التنقّل باتّجاهات مفصّلة.- يمكنك إضافة الوجهات باستخدام
setDestinations. - يمكنك ضبط
isGuidanceActiveعلىtrueلبدء التنقّل. - يمكنك استخدام
simulateLocationsAlongExistingRouteلمحاكاة تقدّم المركبة على طول المسار، وذلك لاختبار تطبيقك وتحديد المشاكل فيه وعرضه.
- يمكنك إضافة الوجهات باستخدام
عرض الرمز
مطالبة المستخدم بالحصول على الأذونات اللازمة
قبل استخدام حزمة تطوير البرامج (SDK) للتنقّل، يجب أن يوافق المستخدم على الأحكام والشروط، ويسمح باستخدام خدمات الموقع الجغرافي المطلوبة للتنقّل. إذا كان تطبيقك سيعمل في الخلفية، يجب أيضًا أن يطلب من المستخدم السماح بالإشعارات التنبيهية للإرشادات. يوضّح هذا القسم كيفية عرض طلبات الحصول على الأذونات المطلوبة.
السماح بخدمات الموقع الجغرافي
تستخدِم حزمة تطوير البرامج (SDK) للتنقّل خدمات الموقع الجغرافي، ما يتطلّب الحصول على إذن من المستخدم. لتفعيل خدمات الموقع الجغرافي وعرض مربّع حوار السماح، اتّبِع الخطوات التالية:
فعِّل إمكانات الموقع الجغرافي والخلفية في Xcode:
- افتح هدفك في Xcode وانتقِل إلى علامة التبويب التوقيع والإمكانات (Signing &Capabilities). لمزيد من التفاصيل، يُرجى الاطّلاع على دليل Apple بشأن إضافة إمكانات إلى تطبيقك.
- أضِف إمكانات الموقع الجغرافي (دائمًا) (Location (Always)) والموقع الجغرافي (أثناء الاستخدام) (Location (When In Use)). في حقل النص لكلّ منهما، أضِف شرحًا موجزًا عن سبب حاجة تطبيقك إلى خدمات الموقع الجغرافي (على سبيل المثال: "يحتاج هذا التطبيق إلى إذن لاستخدام خدمات الموقع الجغرافي للتنقّل باتّجاهات مفصّلة").
- أضِف إمكانية أوضاع الخلفية (Background Modes) ، ثم ضَع علامة في مربّع الاختيار تعديلات الموقع الجغرافي (Location updates). بدون هذه الإمكانية، يتعطّل التطبيق عند بدء التنقّل. لمزيد من التفاصيل، يُرجى الاطّلاع على دليل Apple بشأن معالجة تعديلات الموقع الجغرافي في الخلفية.
لعرض مربّع حوار السماح، استخدِم الـ
requestAlwaysAuthorization()لمثيل مدير الموقع الجغرافي.
Swift
self.locationManager.requestAlwaysAuthorization()
Objective-C
[_locationManager requestAlwaysAuthorization];
يمكنك الاطّلاع على مستندات Apple الكاملة بشأن السماح بخدمات الموقع الجغرافي.
السماح بالإشعارات التنبيهية للإرشادات في الخلفية
تحتاج حزمة تطوير البرامج (SDK) للتنقّل إلى إذن المستخدم لتقديم إشعارات تنبيهية عندما يكون التطبيق قيد التشغيل في الخلفية. أضِف الرمز التالي لمطالبة المستخدم بالإذن بعرض هذه الإشعارات:
Swift
UNUserNotificationCenter.current().requestAuthorization(options: [.alert]) {
granted, error in
// Handle denied authorization to display notifications.
if !granted || error != nil {
print("User rejected request to display notifications.")
}
}
Objective-C
// Request authorization for alert notifications.
UNUserNotificationCenter *center = [UNUserNotificationCenter currentNotificationCenter];
UNAuthorizationOptions options = UNAuthorizationOptionAlert;
[center requestAuthorizationWithOptions:options
completionHandler:
^(
BOOL granted,
NSError *_Nullable error) {
if (!error && granted) {
NSLog(@"iOS Notification Permission: newly Granted");
} else {
NSLog(@"iOS Notification Permission: Failed or Denied");
}
}];
السماح باستخدام أدوات استشعار الحركة
في إصدار رئيسي مستقبلي، ستجمع حزمة تطوير البرامج (SDK) للتنقّل على iOS بيانات الموقع الجغرافي الأساسية مع أدوات استشعار حركة الجهاز (CMAltimeter) لحساب ارتفاع التوجيه. عندما تصل حزمة تطوير البرامج (SDK) إلى مقياس الارتفاع، يستخدم نظام التشغيل iOS تلقائيًا هذا السلسلة النصية لمطالبة المستخدم بالإذن.
لن يؤثّر إضافة هذا المفتاح الآن في السلوك الحالي، ولكنّه سيمنع حدوث أعطال في عملية الإعداد عند ترقية حزمة تطوير البرامج (SDK) لاحقًا.
للاستعداد لعمليات الترقية المستقبلية لحزمة تطوير البرامج (SDK)، اضبط أذونات أدوات استشعار الحركة على النحو التالي:
افتح هدفك في Xcode وانتقِل إلى علامة التبويب معلومات (Info) ، أو افتح ملف
Info.plist.أضِف مفتاحًا جديدًا: الخصوصية - وصف استخدام الحركة (Privacy - Motion Usage Description) (
NSMotionUsageDescription).أضِف شرحًا موجزًا للمستخدم. على سبيل المثال: "يحتاج هذا التطبيق إلى الوصول إلى أدوات استشعار الحركة لحساب الارتفاع وتحسين دقة توجيه الخريطة".
قبول الأحكام والشروط
استخدِم الرمز التالي لعرض مربّع حوار الأحكام والشروط، وفعِّل التنقّل عندما يقبل المستخدم الأحكام. يُرجى العِلم أنّ هذا المثال يتضمّن رمز خدمات الموقع الجغرافي والإشعارات التنبيهية للإرشادات (الموضّحة سابقًا).
Swift
let termsAndConditionsOptions = GMSNavigationTermsAndConditionsOptions(companyName: "Ride Sharing Co.")
GMSNavigationServices.showTermsAndConditionsDialogIfNeeded(
with: termsAndConditionsOptions) { termsAccepted in
if termsAccepted {
// Enable navigation if the user accepts the terms.
self.mapView.isNavigationEnabled = true
self.mapView.settings.compassButton = true
// Request authorization to use location services.
self.locationManager.requestAlwaysAuthorization()
// Request authorization for alert notifications which deliver guidance instructions
// in the background.
UNUserNotificationCenter.current().requestAuthorization(options: [.alert]) {
granted, error in
// Handle rejection of notification authorization.
if !granted || error != nil {
print("Authorization to deliver notifications was rejected.")
}
}
} else {
// Handle rejection of terms and conditions.
}
}
Objective-C
GMSNavigationTermsAndConditionsOptions *termsAndConditionsOptions = [[GMSNavigationTermsAndConditionsOptions alloc] initWithCompanyName:@"Ride Sharing Co."];
[GMSNavigationServices
showTermsAndConditionsDialogIfNeededWithOptions:termsAndConditionsOptions
callback:^(BOOL termsAccepted) {
if (termsAccepted) {
// Enable navigation if the user accepts the terms.
_mapView.navigationEnabled = YES;
_mapView.settings.compassButton = YES;
// Request authorization to use the current device location.
[_locationManager requestAlwaysAuthorization];
// Request authorization for alert notifications which deliver guidance instructions
// in the background.
UNUserNotificationCenter *center = [UNUserNotificationCenter currentNotificationCenter];
UNAuthorizationOptions options = UNAuthorizationOptionAlert;
[center requestAuthorizationWithOptions:options
completionHandler:
^(
BOOL granted,
NSError *_Nullable error) {
if (!error && granted) {
NSLog(@"iOS Notification Permission: newly Granted");
} else {
NSLog(@"iOS Notification Permission: Failed or Denied");
}
}];
} else {
// Handle rejection of the terms and conditions.
}
}];
إنشاء مسار وبدء الإرشادات
لرسم مسار، استخدِم طريقة setDestinations في أداة التنقّل مع مصفوفة تحتوي على
وجهة واحدة أو أكثر من
GMSNavigationWaypoint
الوجهات. إذا تم حساب المسار بنجاح، سيظهر على الخريطة. لبدء الإرشادات على طول المسار، اضبط isGuidanceActive على true في معاودة الاتصال.
يوضّح المثال التالي:
- إنشاء مسار جديد يتضمّن وجهة واحدة
- بدء الإرشادات
- تفعيل إشعارات الإرشادات في الخلفية
- محاكاة السفر على طول المسار (اختياري)
- ضبط وضع الكاميرا على "تتبُّع" (اختياري)
Swift
func startNav() {
var destinations = [GMSNavigationWaypoint]()
destinations.append(GMSNavigationWaypoint.init(placeID: "ChIJnUYTpNASkFQR_gSty5kyoUk",
title: "PCC Natural Market")!)
mapView.navigator?.setDestinations(destinations) { routeStatus in
self.mapView.navigator?.isGuidanceActive = true
self.mapView.locationSimulator?.simulateLocationsAlongExistingRoute()
self.mapView.cameraMode = .following
}
}
Objective-C
- (void)startNav {
NSArray<GMSNavigationWaypoint *> *destinations =
@[[[GMSNavigationWaypoint alloc] initWithPlaceID:@"ChIJnUYTpNASkFQR_gSty5kyoUk"
title:@"PCC Natural Market"]];
[_mapView.navigator setDestinations:destinations
callback:^(GMSRouteStatus routeStatus){
[_mapView.locationSimulator simulateLocationsAlongExistingRoute];
_mapView.navigator.guidanceActive = YES;
_mapView.cameraMode = GMSNavigationCameraModeFollowing;
}];
}
للتعرّف على معرّفات الأماكن، يُرجى الرجوع إلى معرّفات الأماكن.
سيناريوهات متعدّدة المحطات
يمكنك ضبط ما يصل إلى 25 نقطة مرور.
لا تتيح طريقة setDestinations الرحلات المتعدّدة المحطات. استخدِم
continueToNextDestinationWithCompletion()
لنقل نقطة المرور إلى المرحلة التالية من الرحلة.
تحديد وضع السفر
يحدّد وضع السفر نوع المسار الذي سيتم جلبه وكيفية تحديد مسار المستخدم. يمكنك ضبط أحد أوضاع السفر الأربعة لمسار معيّن: القيادة وركوب الدراجات والمشي وسيارات الأجرة. في وضعَي القيادة وسيارات الأجرة، يستند مسار المستخدم إلى اتجاه السفر، بينما في وضعَي ركوب الدراجات والمشي، يتم تمثيل المسار بالاتجاه الذي يشير إليه الجهاز (نحو أعلى الجهاز في الوضع الأفقي).
اضبط السمة
travelMode
لعرض الخريطة، كما هو موضّح في المثال التالي:
Swift
self.mapView.travelMode = .cycling
Objective-C
_mapView.travelMode = GMSNavigationTravelModeCycling;
تحديد الطرق التي يجب تجنُّبها
استخدِم سمتَي BOOL avoidsHighways وavoidsTolls لتجنُّب الطرق السريعة أو الطرق التي يتم تحصيل رسوم مرور فيها أو كليهما على طول مسار معيّن.
Swift
self.mapView.navigator?.avoidsTolls = true
Objective-C
_mapView.navigator.avoidsTolls = YES;
ضبط مستوى صوت الإرشادات الصوتية
لضبط مستوى صوت الإرشادات الصوتية، اضبط السمة volumeLevel في أداة التنقّل على منخفض أو عادي أو مرتفع. تستخدِم أداة التنقّل آخر مستوى صوت تم حفظه، أو يتم ضبطه تلقائيًا على عادي.
Swift
self.mapView.navigator?.volumeLevel = .low
Objective-C
_mapView.navigator.volumeLevel = GMSNavigationVolumeLevelLow;
أداة البحث عن معرّف المكان
يمكنك استخدام أداة البحث عن معرّف المكان
للعثور على معرّفات الأماكن لاستخدامها في وجهات المسار. أضِف وجهة من
placeID باستخدام GMSNavigationWaypoint.
نص عائم
يمكنك إضافة نص عائم في أي مكان في تطبيقك، طالما لم يتم حجب بيان تحديد المصدر من Google. لا تتيح حزمة تطوير البرامج (SDK) للتنقّل تثبيت النص بإحداثيات معيّنة (خط العرض وخط الطول) على الخريطة أو على تصنيف. لمزيد من المعلومات، يُرجى الاطّلاع على النوافذ المنبثقة.