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

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

محتوى هذا الدليل: يوضّح هذا الدليل كيفية استخدام مسار مخصّص للشاحنات تم إنشاؤه بواسطة Routes API أو Route Optimization API واستخدامه لتشغيل جلسة اتجاهات مفصّلة باستخدام حزمة تطوير البرامج Navigation 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: تمرير الرمز المميّز إلى Navigator

مرِّر routeToken والنقاط على المسار للوجهة إلى الإجراء mapView.navigator setDestinations.

عند ضبط النقاط على المسار وتمرير الرمز المميّز للمسار، يُرجى مراعاة ما يلي:

• متطلبات مطابقة الوجهة: يجب أن تتطابق إحداثيات الوجهة التي تم تمريرها إلى setDestinations مع إحداثيات الوجهة المستخدَمة عند إنشاء routeToken. يؤدي تحديد وجهة مختلفة إلى حدوث خطأ.
• التوجيه على جانب الطريق: لا يمكن للمركبات التجارية الكبيرة الالتفاف بسهولة في الشوارع الضيقة. لضمان وصول الشاحنة إلى الوجهة على الجانب الصحيح من الطريق، اضبط preferSameSideOfRoad = true على نقاط المسار.
• محطات توقّف المركبات: لتوجيه الشاحنة إلى مكان مناسب للتوقّف أو تفريغ الحمولة، اضبط السمة vehicleStopover = true في نقاط المسار.
• نقاط التنقّل: إذا كانت وجهتك تحتوي على مدخل مخصّص للشحن أو رصيف تحميل، حدِّده باستخدام رمز مميّز لنقطة التنقّل.

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

قيِّم GMSRouteStatus الذي تم عرضه في دالة الاستدعاء setDestinations. عندما تكون الحالة .OK (GMSRouteStatusOK)، اضبط isGuidanceActive = true (guidanceActive = YES) لبدء الاتجاهات المفصّلة النشطة.

مثال على الرمز البرمجي

مرِّر الرمز المميّز للمسار إلى حزمة تطوير البرامج (SDK) للتنقّل باستخدام طريقة mapView.navigator setDestinations، مع تحديد النقاط على المسار نفسها التي استخدمتها عند إنشاء الرمز المميّز للمسار:

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

mapView.navigator?.setDestinations([destination], routeToken: routeToken, callback: {...})

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

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

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