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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

بالإضافة إلى ذلك، يجب أن يستوفي مشروعك متطلبات إعداد حزمة تطوير البرامج (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: ضبط إعدادات CustomRoutesOptions

مرِّر الرمز المميّز للمسار إلى مثيل CustomRoutesOptions باستخدام CustomRoutesOptions.builder:

  • مرِّر الرمز المميّز باستخدام setRouteToken(routeToken).
  • اضبط وضع السفر باستخدام setTravelMode(CustomRoutesOptions.TravelMode.DRIVING).

الخطوة 3: تحديد النقاط على المسار وضبط الوجهات

مرِّر نقاط المسار الخاصة بوجهتك وCustomRoutesOptions إلى navigator.setDestinations.

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

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

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

سجِّل OnResultListener على ListenableResultFuture<Navigator.RouteStatus>. عندما تكون حالة المسار OK، يجب استدعاء navigator.startGuidance لبدء الاتجاهات المفصّلة النشطة.

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

استخدِم CustomRoutesOptions.builder لضبط الرمز المميّز ثم مرِّره إلى navigator.setDestinations.

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

val customRoutesOptions = CustomRoutesOptions.builder()
    .setRouteToken(routeToken)
    .setTravelMode(TravelMode.DRIVING)
    .build()

// Specify the same destination used to create the route token
ArrayList <Waypoint> destinations = Lists.newArrayList();
val destination = Waypoint.builder()
    .setLatLng(10.0, 20.0)
    .setTitle("title")
    .setVehicleStopover(true)
    .build()
destinations.add(destination);

navigator.setDestinations(destinations, customRoutesOptions)

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

يمكنك عرض جلسة التنقّل في المركبات الكبيرة على شاشات لوحة القيادة باستخدام التنقّل في Android Auto.

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

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