توفير اتّجاهات مفصّلة للمركبات الكبيرة

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

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

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

ستتعرَّف على كيفية إجراء ما يلي:

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

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

قبل البدء، يجب استيفاء المتطلبات التالية.

إعداد المشروع

يجب توفير مشروعك على السحابة الإلكترونية على Google Cloud لخدمة "تحديد مسارات المركبات الكبيرة". إذا كنت تستخدم مشاريع منفصلة لكل من Routes API وNavigation SDK، يجب توفير كليهما وفقًا لذلك.

إنشاء رمز مميّز للمسار

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

الحد الأدنى من المتطلبات

يجب أن يستخدم تطبيقك الحدّ الأدنى المطلوب لإصدار حزمة Navigation SDK:

  • ‫Android: الإصدار 5.2.0 أو إصدار أحدث
  • ‫iOS: الإصدار 5.4.0 أو إصدار أحدث

بالإضافة إلى ذلك، تنطبق جميع متطلبات استخدام حزمة Navigation SDK:

القيود

قبل البدء، يجب أن تكون على دراية بالقيود والمتطلبات التالية.

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

عرض واجهة مستخدم خاصة بالشاحنات

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

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

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

سير عمل رمز المسار

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

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

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

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

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

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

لبدء جلسة تنقّل باستخدام مسار الشاحنة، عليك تمرير الرمز المميز للمسار إلى Navigator.

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

يتلقّى تطبيقك السلسلة routeToken من خادم الخلفية.

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

CqMBCjoKCJQOor5DHcwiEhBon3XpHXFnVvDeWMwd9PpAGgz6wtnFDKIBrAHTARpCApUDSggAAAAACjcrP3gBEAQaTApKChgKDQoCCAERAAAAAACAZkAR3SQGgZUXdUASEggAEAMQBhATEBIYAkIEGgIIBSIYChZ2VEJiWlBPSkk1aU5wUVRzNTV5d0FRKAEiFQBcJuds-Efh-2QZhOMTtUCCxEVL_g

الخطوة 2: تمرير الرمز المميّز إلى Navigator

قدِّم routeToken إلى Navigator عند ضبط وجهة الرحلة. تستخدم حزمة تطوير البرامج (SDK) الخاصة بخدمة Navigation بعد ذلك هذا الرمز المميز في جميع عمليات احتساب المسارات للرحلة.

يُرجى العِلم أنّ حزمة تطوير البرامج (SDK) الخاصة بخدمة Navigation تتضمّن إعداد TravelMode، ويجب ضبطه على TravelMode.DRIVING. يختلف ذلك عن إعدادات travelMode في واجهة برمجة التطبيقات Routes API، والتي يجب ضبطها على TRUCK. يتم ترميز إعدادات Routes API travelMode في routeToken، ويتم إرسال إشارات إلى Navigation SDK لعرض التجربة والمسار الخاصَّين بالشاحنة.

Android

استخدِم 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)

iOS

مرِّر رمز المسار إلى حزمة تطوير البرامج (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: {...})

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