تخطيط مسار

في بعض الأحيان، قد تحتاج إلى تخطيط المسار الذي يوفّره تطبيقك للمستخدمين. يمكن أن يساعدك استخدام رمز مسار من Routes API أو Route Optimization API في تحديد أمرين لمسارك المخطط له:

• خطوط متعدّدة للمسار

• أهداف المسار

على سبيل المثال، إليك بعض الأمثلة على أهداف التوجيه التي قد تكون لديك:

• تقليل وقت التسليم: قد ترغب شركة توصيل الطعام في تقليل الوقت الذي يستغرقه توصيل الطعام.

• تقليل مدة الرحلة أو استهلاك الوقود: قد ترغب شركة خدمات لوجستية في تحسين كفاءة السائقين لديها وخفض تكاليف الوقود.

• تقليل الوقت المستغرَق للوصول إلى الوجهة: قد تهدف عملية إرسال الخدمة إلى تقليل الوقت المستغرَق لوصول المشغّلين إلى طلب العمل.

• خفض التكاليف وتحسين السلامة: قد ترغب شركة مشاركة الرحلات في العثور على مسار يكلّف الركاب أقل ويتجنّب مناطق معيّنة لأسباب تتعلق بالسلامة.

لمزيد من المعلومات حول تخطيط مسار باستخدام رمز مميّز للمسار، يُرجى الاطّلاع على الحصول على رمز مميّز للمسار في Routes API ونقل الخطوط المتعدّدة والرموز المميّزة للمسارات في Route Optimization API.

أهمية استخدام رمز مميّز للمسار من أجل تحقيق أهداف المسار

باستخدام رمز مسار من Routes API أو Route Optimization API، يمكنك التحكّم بشكل أكبر في المسار المقدَّم:

• خطِّط لمسار مسبقًا لتستخدمه حزمة Navigation SDK.

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

• تقدير السعر مسبقًا، بما في ذلك تقديرات الوقت المتوقّع للوصول والمسافة على الرغم من أنّ التكلفة والوقت الفعليَّين قد يختلفان، يقلّل هذا التقدير من الفجوة بين تكلفة المسار المتوقّعة والفعلية.

• تحديد أهداف أكثر تقدّمًا للمسارات، مثل المسار الصديق للبيئة أو أقصر مسار

آلية عمل رموز المسارات المميّزة

يمكنك استخدام Routes API أو Route Optimization API لتخطيط مسار باستخدام أهداف المسار. يمكنك تمرير رمز مميّز للمسار تم عرضه من أي من واجهتَي برمجة التطبيقات هاتين إلى حزمة تطوير البرامج (SDK) للتنقّل من أجل توجيه كيفية تحديد مسار مركبتك.

إليك ما يحدث عند طلب رمز مسار واستخدامه:

1. تعرض واجهة برمجة التطبيقات Routes API أو Route Optimization API رمز مسار مشفّرًا يتضمّن الخطوط المتعدّدة للمسار وأهداف المسار.

2. يتم تمرير الرمز المميّز للمسار إلى حزمة تطوير البرامج (SDK) للتنقّل.

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

4. أثناء الرحلة، إذا تغيّرت حركة المرور أو ظروف الطريق، أو إذا غادرت المركبة المسار المخطط له، تحتسب حزمة تطوير البرامج (SDK) للتنقّل مسارًا جديدًا يتّبع أهداف المسار وخيارات المسار المحدّدة في الرمز المميّز للمسار.

تساعد هذه العملية في تقريب المسار الفعلي من المسار المخطط له إلى أقصى حد.

أسباب عدم اتّباع المسار المخطَّط له بدقة

يبدأ التنقّل على مسارك المخطّط له، ولكن يمكن أن يختلف المسار الفعلي عنه في حالات مثل ما يلي:

• تبدأ المركبة بعيدًا عن نقطة البداية المخطط لها.
• تغيُّر حركة المرور أو حالة الطريق أثناء الرحلة
• تغادر المركبة المسار المخطط له.

يمكن أن تؤثر هذه الاختلافات في المسافة والوقت المقدَّر للوصول وغير ذلك من سمات الرحلة المهمة التي خطّطت لها.

التخطيط لمسار باستخدام رمز مميّز للمسار

يمكنك تخطيط مسار من خلال إنشاء رمز مميّز للمسار ثم تمريره إلى حزمة تطوير البرامج (SDK) للتنقّل، كما هو موضّح في الخطوات التالية:

الخطوة 1: إنشاء رمز مميّز للمسار باستخدام Routes API أو Route Optimization API

1. اطلب رمز مسار باستخدام إحدى الطرق التالية:

   • Routes API: computeRoutes. لمزيد من المعلومات حول طلب رمز مسار في Routes API، يُرجى الاطّلاع على احتساب مسار والحصول على رمز مسار.

   • ‫Route Optimization API: optimizeTours أو batchOptimizeTours. لمزيد من المعلومات حول طلب رمز مميّز للمسار في Route Optimization API، يُرجى الاطّلاع على الخطوط المتعدّدة للانتقال والرموز المميّزة للمسارات.

2. إعداد طلب بيانات من واجهة برمجة التطبيقات Routes API لاستيفاء متطلبات استخدام رمز مميز للمسار:

   • اضبط السمة travelMode على DRIVE أو TWO_WHEELER.
   • اضبط السمة routingPreference على TRAFFIC_AWARE أو TRAFFIC_AWARE_OPTIMAL.
   • لا تستخدِم نقاط مسار من النوع Via.

الخطوة 2: تمرير الرمز المميّز للمسار إلى حزمة تطوير البرامج (SDK) للتنقّل

1. تخزين الرمز المميّز للمسار: في حزمة تطوير البرامج (SDK) للتنقّل، عليك إعداد سلسلة لتخزين الرمز المميّز للمسار. على سبيل المثال:

   let routeToken = "route token returned by Routes API"
   

   مثال على رمز مسار تم عرضه:

   {
   // Other fields
   "routeToken": "CqMBCjoKCJQOor5DHcwiEhBon3XpHXFnVvDeWMwd9PpAGgz6wtnFDKIBrAHTARpCApUDSggAAAAACjcrP3gBEAQaTApKChgKDQoCCAERAAAAAACAZkAR3SQGgZUXdUASEggAEAMQBhATEBIYAkIEGgIIBSIYChZ2VEJiWlBPSkk1aU5wUVRzNTV5d0FRKAEiFQBcJuds-Efh-2QZhOMTtUCCxEVL_g",
   }
   

2. مرِّر الرمز المميّز للمسار إلى حزمة تطوير البرامج (SDK) للتنقّل باستخدام طريقة setDestinationsWithToken:completionHandler: في mapView.navigator. تحصل حزمة Navigation SDK على الوجهات وخيارات المسارات من الرمز المميّز للمسار، لذا لا تحتاج إلى تمرير نقاط المسار.

   يجب أن يكون وضع السفر الذي تم ضبطه في تطبيقك، مثل mapView.travelMode، إحدى القيم التالية:

   • ‫.driving (GMSNavigationTravelModeDriving): قيادة هذه هي القيمة التلقائية، لذا لا تحتاج معظم التطبيقات إلى تغييرها.
   • ‫.twoWheeler (GMSNavigationTravelModeTwoWheeler): درّاجة نارية

   يؤدي أي وضع سفر آخر إلى تعذُّر الطلب مع ظهور الخطأ .travelModeUnsupported (GMSRouteStatusTravelModeUnsupported). باستخدام أيّ من القيمتَين المسموح بهما، يستخدم المسار وضع السفر في رمز المسار المميّز. على سبيل المثال، إذا كان تطبيقك يستخدم القيادة وكان رمز المسار مخصّصًا لمسار دراجة نارية، توفّر حزمة تطوير البرامج (SDK) للتنقّل مسارًا للدراجات النارية. للتأكّد من وسيلة النقل التي يستخدمها المسار، يُرجى الاطّلاع على resolvedParameters.travelMode. لمزيد من المعلومات، يُرجى الاطّلاع على خيارات التوجيه التي تم حلّها.

3. تحقَّق من حالة المسار في معالج الإكمال. عندما تنتهي حزمة تطوير البرامج (SDK) للتنقّل من احتساب المسار، فإنّها تمرّر GMSNavigationRouteDescription إلى معالج الإكمال. إذا عثر على مسار من الموقع الجغرافي للمركبة إلى الوجهات في رمز المسار المميّز، تكون قيمة routeStatus لوصف المسار هي .OK (GMSRouteStatusOK)، ويمكنك بدء الإرشاد. وإلا، سيتلقّى معالج الإكمال أيضًا NSError يصف الخطأ. على سبيل المثال:

   mapView.navigator?.setDestinationsWithToken(routeToken) { [weak self] routeDescription, error in
     if routeDescription?.routeStatus == .OK {
       self?.mapView.navigator?.isGuidanceActive = true
     }
   }
   

التحقّق مما إذا كانت حزمة تطوير البرامج (SDK) للتنقّل قد طبّقت الرمز المميّز للمسار

تشير حالة المسار .OK إلى أنّ حزمة تطوير البرامج (SDK) للتنقّل عثرت على مسار، ولكن ليس بالضرورة المسار الذي خطّطت له. للتحقّق مما إذا كان المسار يتطابق مع المسار المخطط له، اتّبِع الخطوات التالية في معالج الإكمال:

1. يُرجى التأكّد من أنّ قيمة "routeStatus" في وصف المسار هي ".OK". لا توفّر حزمة تطوير البرامج (SDK) الخاصة بالتنقّل تفاصيل الرمز المميّز للمسار إلا عندما تعثر على مسار. لمزيد من المعلومات، يُرجى الاطّلاع على الخطوة 2.

2. يمكنك الحصول على routeTokenExecutionDetails لوصف المسار، وهو عنصر يتوافق مع بروتوكول GMSNavigationRouteTokenExecutionDetails. إذا لم يوفّر الخادم تفاصيل رمز المسار المميّز، تكون هذه السمة nil.

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

4. اختياري: إذا كانت الحالة .tokenSuccessfullyApplied، تحقَّق من السمة resolvedParameters لتفاصيل التنفيذ نفسها لمعرفة خيارات المسار التي يستخدمها المسار، مثل ما إذا كان يتجنّب رسوم العبور. لمزيد من المعلومات، يُرجى الاطّلاع على خيارات التوجيه التي تم حلّها.

قيم حالة تنفيذ الرمز المميّز

إذا كانت قيمة routeStatus هي .OK، يمكنك بدء الإرشادات باستخدام أي حالة تنفيذ للرمز المميّز. تُعلمك الحالة بما إذا كان المسار يتّبع المسار المخطّط له.

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

خيارات التوجيه التي تم حلّها

‫resolvedParameters هو عنصر يتوافق مع بروتوكول GMSNavigationRouteTokenResolvedParameters أو nil إذا لم تكن خيارات المسار متاحة. وله الخصائص التالية:

• ‫travelMode: وضع السفر الذي يستخدمه المسار، مثل .driving (GMSNavigationTravelModeDriving). تُبلغ حزمة تطوير البرامج (SDK) للتنقّل أيضًا عن .driving عندما يستخدم المسار وضع سفر ليس له قيمة مطابقة، أو عندما لا يكون وضع السفر متاحًا.
• ‫avoidTolls: تشير إلى ما إذا كان المسار يتجنّب رسوم العبور.
• ‫avoidHighways: يشير إلى ما إذا كان المسار يتجنّب الطرق السريعة.
• ‫avoidFerries: لتحديد ما إذا كان المسار يتجنّب العبّارات
• ‫avoidTunnels: تشير إلى ما إذا تم احتساب المسار لتجنُّب الأنفاق عندما يكون ذلك ممكنًا.
• ‫avoidVignettes: البلدان التي تم احتساب المسار فيها لتجنّب قسائم الرسوم عند الإمكان، كرموز مناطق Unicode CLDR المكوّنة من حرفَين، مثل CH لسويسرا.
• ‫rerouteStrategy: الاستراتيجية التي تستخدمها الخلفية الخاصة بالتوجيه لاحتساب مسارات جديدة أثناء الرحلة تشمل الاستراتيجيات .bestBasedOnTokenParameters (GMSNavigationRerouteStrategyBestBasedOnTokenParameters)، التي تستخدم مَعلمات المسار في الرمز المميّز للمسار من أجل احتساب مسارات جديدة.

إذا لم تكن حالة تنفيذ الرمز المميّز هي .tokenSuccessfullyApplied، ستُبلغ حزمة تطوير البرامج (SDK) الخاصة بالتنقّل عن travelMode وavoidTolls وavoidHighways وavoidFerries فقط. تحتوي السمات الأخرى على قيمها التلقائية، حتى إذا طلبت تجنُّب الأنفاق أو قسائم رسوم العبور عند طلب رمز المسار: avoidTunnels هي false (NO)، وavoidVignettes فارغة، وrerouteStrategy هي .unknown (GMSNavigationRerouteStrategyUnknown).

مثال

يوضّح مثال الرمز البرمجي التالي كيفية تخطيط مسار باستخدام رمز مميّز للمسار، والتحقّق مما إذا كانت حزمة تطوير البرامج (SDK) للتنقّل قد طبّقت الرمز المميّز، وبدء الإرشاد.

let routeToken = "route token returned by Routes API"

mapView.navigator?.setDestinationsWithToken(routeToken) { [weak self] routeDescription, error in
  // Check whether the Navigation SDK found a route.
  guard routeDescription?.routeStatus == .OK else {
    print("Route error: \(error?.localizedDescription ?? "unknown")")
    return
  }

  // Check whether the Navigation SDK applied the route token.
  if let executionDetails = routeDescription?.routeTokenExecutionDetails {
    if executionDetails.tokenExecutionStatus != .tokenSuccessfullyApplied {
      print("The route might differ from your planned route.")
    }
  } else {
    print("Route token details aren't available.")
  }

  self?.mapView.navigator?.isGuidanceActive = true
}

NSString *routeToken = @"route token returned by Routes API";

[mapView.navigator setDestinationsWithToken:routeToken
                          completionHandler:^(id<GMSNavigationRouteDescription> _Nullable routeDescription,
                                              NSError *_Nullable error) {
  // Check whether the Navigation SDK found a route.
  if (routeDescription.routeStatus != GMSRouteStatusOK) {
    NSLog(@"Route error: %@", error.localizedDescription);
    return;
  }

  // Check whether the Navigation SDK applied the route token.
  id<GMSNavigationRouteTokenExecutionDetails> executionDetails =
      routeDescription.routeTokenExecutionDetails;
  if (executionDetails == nil) {
    NSLog(@"Route token details aren't available.");
  } else if (executionDetails.tokenExecutionStatus !=
             GMSNavigationRouteTokenExecutionStatusTokenSuccessfullyApplied) {
    NSLog(@"The route might differ from your planned route.");
  }

  mapView.navigator.guidanceActive = YES;
}];

سيناريوهات الرحلات المتعددة المحطات

يمكنك ضبط 25 نقطة على المسار كحدّ أقصى.

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

كيفية تفاعل رموز المسارات المميّزة مع حزمة تطوير البرامج (SDK) للتنقّل

في ما يلي كيفية تعامل حزمة تطوير البرامج (SDK) للتنقّل مع مسارك المخطّط له:

• تلغي أي وجهات تم ضبطها سابقًا.

• يستخدم الموقع الجغرافي لبدء المركبة.

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

• يستخدم خيارات المسار المحدّدة في الرمز المميّز للمسار بدلاً من الإعدادات التالية في تطبيقك، بما في ذلك عند احتساب مسار جديد أثناء الرحلة:

  • avoidsHighways
  • avoidsTolls
  • avoidsFerries
  • licensePlateRestriction
  • وضع السفر الذي تم ضبطه في تطبيقك

• يتّبع هذه الإعدادات عند احتساب المسار أو تعديله:

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