التنقّل على طرق المركبات الكبيرة

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

محتوى هذا الدليل: يوضّح هذا الدليل كيفية استخدام مسار مخصّص للشاحنات تم إنشاؤه بواسطة Routes API أو Route Optimization API واستخدامه لتشغيل جلسة اتجاهات مفصّلة باستخدام حزمة تطوير البرامج (SDK) الخاصة بالتنقّل لنظام التشغيل iOS.

أهداف الدورة التعليمية

ستتعرّف على كيفية تنفيذ المهام التالية:

• استخدِم routeToken لربط عملية تخطيط المسارات في الخلفية بتجربة التنقّل داخل التطبيق.
• اضبط حزمة تطوير البرامج (SDK) للتنقّل لاستخدام مسار شاحنة مخطَّط مسبقًا.
• التعرّف على كيفية ظهور القيود المتعلّقة بالشاحنات للسائق في واجهة المستخدم الخاصة بالتنقّل

المتطلبات الأساسية

قبل البدء، تأكَّد من استيفاء المتطلبات التالية:

1. طلب الوصول إلى مشروعك

تتوفّر ميزة "توجيه المركبات الكبيرة" لمجموعة محدودة من العملاء. لإبداء الاهتمام وطلب الوصول إلى مشروعك على Google Cloud، يُرجى ملء نموذج التواصل. سيتواصل معك ممثل عن Google لإعلامك بالخطوات التالية.

بعد أن تمنحك Google إذن الوصول، تأكَّد من إعداد مشروعك على Google Cloud لتحديد مسارات المركبات الكبيرة.

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

2. إعداد إنشاء المسارات في الخلفية والحصول على رمز مميّز للمسار

قبل بدء التنقّل على الجهاز، يجب أن ينشئ خادم الخلفية مسارًا للشاحنة ويحصل على routeToken باستخدام إحدى واجهات برمجة التطبيقات التالية:

• ‫Routes API: ننصح باستخدامها لاحتساب مسارات الشاحنات الفردية بين نقاط الانطلاق والوجهات. للحصول على تعليمات الإعداد، يُرجى الاطّلاع على إنشاء مسارات وأوقات وصول مقدّرة للمركبات الكبيرة.
• ‫Route Optimization API: يُنصح بها لتحسين المسارات المتعدّدة المحطات لأسطول من المركبات. لمزيد من المعلومات، يُرجى الاطّلاع على دليل توجيه المركبات الكبيرة في Route Optimization API.

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

3- استيفاء الحد الأدنى من متطلبات حزمة SDK والنظام

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

القيود والإرشادات التشغيلية

قبل البدء، يُرجى مراعاة القيود والإرشادات التشغيلية التالية:

• التوفّر الجغرافي: تتوفّر ميزة "توجيه المركبات الكبيرة" في الولايات الـ 48 المتجاورة في الولايات المتحدة (متوفّرة للجمهور العام) واليابان (ميزة تجريبية). ولا تتوفّر في ألاسكا أو هاواي أو الأقاليم التابعة للولايات المتحدة.
• إرشادات للسائقين والسلامة: يجب ألا يعتمد السائقون فقط على المسارات التي تعرضها حزمة تطوير البرامج (SDK) للتنقّل لضمان السلامة أو الامتثال للقوانين. قد لا تكون المسارات مناسبة للمركبة في جميع ظروف الطريق، وقد يؤدي اتّباعها إلى تعرّض السائقين لمخاطر مثل الارتفاعات المنخفضة أو الطرق ذات الوزن المحدود. يجب أن يظل السائقون متيقظين دائمًا وأن يلتزموا بإشارات الطريق واللوائح المحلية.
• المسارات التي تعتمد على أفضل الجهود: عندما لا تتمكّن واجهة برمجة التطبيقات الخاصة بالتوجيه من العثور على مسار يتوافق تمامًا مع قيود المركبات، فإنّها تعرض مسارًا يعتمد على "أفضل الجهود" قد يمرّ عبر أجزاء محظورة. على سبيل المثال، تضبط Routes API علامة routeRestrictionsPartiallyIgnored في ردّها. عند التنقّل في هذه المسارات، تعرض حزمة تطوير البرامج (SDK) الخاصة بالتنقّل وسائل شرح للمسارات من أجل تسليط الضوء على القيود ذات الصلة. خطِّط للمسارات بعناية في هذه الحالات، ولا تستخدِم مسارًا تم الإبلاغ عنه كمصدر وحيد للحقيقة عند التخطيط أو التنقّل.
• الميزات غير المتوافقة: لا تتوافق ميزة "توجيه المركبات الكبيرة" مع الميزات التالية:
  • أسعار رسوم عبور الشاحنات
  • الحدود القصوى للسرعة الخاصة بالشاحنات أو المركبات الثقيلة
  • توجيه للمواد الخطرة المشعّة
• حدود الاستخدام: تخضع الطلبات المقدَّمة إلى حزمة Navigation SDK لحدود الاستخدام والحصص العادية. لمزيد من المعلومات، يُرجى الاطّلاع على الاستخدام والفوترة.

عرض واجهة مستخدم مخصّصة للشاحنات (وسائل شرح المسار)

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

تتضمّن حزمة تطوير البرامج (SDK) للتنقّل وسائل شرح للقيود التالية:

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

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

‫routeToken هو لقطة مشفّرة لمسار أنشأته الخلفية الخاصة بتوجيه المسارات في Google. وهي تتضمّن الشكل الهندسي للمسار المخطَّط له، بالإضافة إلى الأبعاد المادية للمركبة وملفها الشخصي الخاص بالقيود.

يتّبع سير العمل الخطوات التالية:

1. طلب المسار: يطلب خادم الخلفية مسارًا للشاحنة من Routes API (أو Route Optimization API).
2. تلقّي الرمز المميّز: تحتسب واجهة برمجة التطبيقات للتوجيه المسار المتوافق وتعرض routeToken إلى خادم الخلفية.
3. إعادة توجيه الرمز المميّز: يمرّر خادم الخلفية routeToken وإحداثيات الوجهة إلى تطبيقك على الأجهزة الجوّالة.
4. التمرير إلى حزمة تطوير البرامج (SDK): يمرّر التطبيق المتوافق مع الأجهزة الجوّالة routeToken إلى حزمة تطوير البرامج للتنقّل.
5. بدء الإرشاد: تتولّى حزمة تطوير البرامج (SDK) للتنقّل جميع جوانب تجربة الاتّجاهات المفصّلة، بما في ذلك عرض وسائل الشرح للمسارات والتعامل مع إعادة التوجيه الديناميكي وفقًا لقيود المركبة.

إعادة الاحتساب وتغيير المسار بشكل ديناميكي

أثناء التنقّل النشط، قد تؤدي أحوال حركة المرور أو إغلاق الطرق أو الانعطافات الفائتة إلى انحراف المركبة عن المسار المخطط له.

عند إعادة التوجيه:

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

التنفيذ: بدء رحلة مخصّصة للشاحنات

اتّبِع الخطوات التالية لإعداد الاتجاهات المفصّلة وبدء استخدامها مع رمز مميّز لمسار مركبة كبيرة.

الخطوة 1: الحصول على رمز المسار من الخلفية

يتلقّى تطبيقك على الأجهزة الجوّالة السلسلة routeToken مع إحداثيات الوجهة من خادم الخلفية. لمزيد من المعلومات حول إنشاء هذا الرمز المميّز على خادمك، يُرجى الاطّلاع على إنشاء مسارات المركبات الكبيرة وأوقات الوصول المقدَّرة في مستندات Routes API.

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

{
  "routeToken": "CqMBCjoKCJQOor5DHcwiEhBon3XpHXFnVvDeWMwd9PpAGgz6wtnFDKIBrAHTARpCApUDSggAAAAACjcrP3gBEAQaTApKChgKDQoCCAERAAAAAACAZkAR3SQGgZUXdUASEggAEAMQBhATEBIYAkIEGgIIBSIYChZ2VEJiWlBPSkk1aU5wUVRzNTV5d0FRKAEiFQBcJuds-Efh-2QZhOMTtUCCxEVL_g"
}

الخطوة 2: ضبط الوجهات باستخدام الرمز المميّز للمسار

مرِّر routeToken إلى الإجراء mapView.navigatorsetDestinationsWithToken:completionHandler:. تحصل حزمة تطوير البرامج (SDK) للتنقّل على الوجهات من الرمز المميّز للمسار، بالإضافة إلى ملف المسار TRUCK الذي يوجّهها إلى تطبيق قيود المركبات الكبيرة. لست بحاجة إلى تمرير نقاط على المسار. يجب أن يكون وضع السفر في تطبيقك .driving (GMSNavigationTravelModeDriving)، وهو الوضع التلقائي، أو .twoWheeler (GMSNavigationTravelModeTwoWheeler).

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

• التوجيه على جانب الطريق: لا يمكن للمركبات التجارية الكبيرة الالتفاف بسهولة على شكل حرف U في الشوارع الضيقة. لضمان وصول الشاحنة إلى الوجهة على الجانب الصحيح من الطريق، اضبط sideOfRoad على true في نقطة على المسار الخاصة بالوجهة.
• محطات توقّف المركبات: لتوجيه الشاحنة إلى مكان مناسب للتوقّف أو تفريغ الحمولة، اضبط vehicleStopover على true في نقطة المسار الخاصة بالوجهة.
• نقاط التنقّل: إذا كانت وجهتك تحتوي على مدخل مخصّص للشحن أو رصيف تحميل، حدِّده باستخدام رمز مميّز لنقطة التنقّل.

الخطوة 3: التعامل مع حالة المسار وبدء الإرشاد

عندما تنتهي حزمة تطوير البرامج (SDK) للتنقّل من احتساب المسار، فإنّها تمرّر GMSNavigationRouteDescription إلى معالج الإكمال. عندما تكون قيمة routeStatus هي .OK (GMSRouteStatusOK)، اضبط isGuidanceActive = true (guidanceActive = YES) لبدء الاتجاهات المفصّلة النشطة.

للتأكّد من أنّ حزمة Navigation SDK قد طبّقت الرمز المميّز للمسار، يُرجى الاطّلاع على التحقّق مما إذا كانت حزمة Navigation SDK قد طبّقت الرمز المميّز للمسار.

مثال على الرمز

مرِّر الرمز المميّز للمسار إلى setDestinationsWithToken:completionHandler:، ثم ابدأ الإرشاد عندما تكون حالة المسار .OK.

// Obtain the routeToken string from your backend
let routeToken = "route token returned by Routes API"

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

الشاشات داخل المركبة

الخطوات التالية

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