تخطيط مسار

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

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

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

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

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

    String routeToken = "route token returned by Routes API";

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

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

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

    setDestinationsWithToken(String routeToken, RouteDescriptionLoadCallback callback);
setDestinationsWithToken(String routeToken, DisplayOptions displayOptions, RouteDescriptionLoadCallback callback);

  3. تحقَّق من حالة المسار في دالة الاستدعاء. عندما تنتهي حزمة تطوير البرامج (SDK) للتنقّل من احتساب المسار، فإنّها تمرّر RouteDescription إلى دالة الاستدعاء. إذا عثر على مسار من الموقع الجغرافي للمركبة إلى الوجهات في الرمز المميّز للمسار، يعرض RouteDescription.getRouteStatus Navigator.RouteStatus.OK، ويمكنك بدء الإرشاد. على سبيل المثال:

    navigator.setDestinationsWithToken(
    routeToken,
    routeDescription -> {
      if (routeDescription.getRouteStatus() == Navigator.RouteStatus.OK) {
        navigator.startGuidance();
      }
    });

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

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

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

  2. يمكنك الاتصال بالرقم RouteDescription.getRouteTokenExecutionDetails للحصول على RouteTokenExecutionDetails. إذا لم يوفّر الخادم تفاصيل رمز المسار المميّز، ستعرض هذه الطريقة null.

  3. استدعِ getTokenExecutionStatus على الكائن RouteTokenExecutionDetails. إذا كانت النتيجة TOKEN_SUCCESSFULLY_APPLIED، يتطابق المسار مع المسار المخطط له. وتعني أي حالة أخرى أنّ المسار قد يختلف عن المسار المخطط له. لمزيد من المعلومات عن كل حالة، يُرجى الاطّلاع على قيم حالة تنفيذ الرمز المميّز.

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

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

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

الحالة يتّبع مسارك المخطَّط له الوصف
TOKEN_SUCCESSFULLY_APPLIED نعم طبّقت حزمة تطوير البرامج (SDK) للتنقّل الرمز المميّز للمسار.
TOKEN_APPLIED_WITH_LOCATION_MISMATCH ليس بالضرورة تعذّر على حزمة Navigation SDK إعادة إنشاء مسارك المخطّط له لأنّ أحد المواقع الجغرافية في طلب المسار كان يبعد أكثر من 25 مترًا عن الموقع الجغرافي المطابق في رمز المسار المميّز. في حال ظهور الرمز setDestinationsWithToken، يعني ذلك أنّ الجهاز كان على بُعد أكثر من 25 مترًا من نقطة الانطلاق في الرمز المميّز للمسار. سيظل المسار يؤدي إلى وجهاتك، ولكن لا يمكن لحزمة Navigation SDK تأكيد أنّه يستخدم خيارات المسار من الرمز المميّز للمسار، مثل تجنُّب رسوم العبور.
TOKEN_IGNORED_OTHER ليس بالضرورة تعذّر على حزمة تطوير البرامج (SDK) الخاصة بالتنقّل إعادة إنشاء مسارك المخطّط له لسبب آخر، مثلاً بسبب إغلاق طريق في مسارك المخطّط له. سيظل المسار يؤدي إلى وجهاتك، ولكن لا يمكن لحزمة Navigation SDK تأكيد أنّه يستخدم خيارات المسار من الرمز المميّز للمسار، مثل تجنُّب رسوم العبور.
NO_TOKEN_PROVIDED لا ينطبق لم يتضمّن طلب المسار رمزًا مميزًا للمسار.
UNKNOWN غير معروف الحالة غير معروفة.

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

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

تعرض الدالة getResolvedParameters عنصر RouteTokenResolvedParameters، أو null إذا لم تكن خيارات المسار متاحة. يحتوي RouteTokenResolvedParameters على الطرق التالية:

  • ‫getTravelMode: وسيلة النقل التي يستخدمها المسار، مثل RoutingOptions.TravelMode.DRIVING. وتُبلغ حزمة Navigation SDK أيضًا عن RoutingOptions.TravelMode.DRIVING عندما يستخدم المسار وسيلة نقل لا تتضمّن قيمة مطابقة، أو عندما لا تكون وسيلة النقل متاحة.
  • ‫getAvoidTolls: تشير إلى ما إذا كان المسار يتجنّب رسوم العبور.
  • ‫getAvoidHighways: يشير إلى ما إذا كان المسار يتجنّب الطرق السريعة.
  • ‫getAvoidFerries: لتحديد ما إذا كان المسار يتجنّب العبّارات

مثال

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

String routeToken = "route token returned by Routes API";

// Existing flow to get a Navigator.
NavigationApi.getNavigator(...);

// Handle the result of the route calculation.
RouteDescriptionLoadCallback callback =
    routeDescription -> {
      // Check whether the Navigation SDK found a route.
      if (routeDescription.getRouteStatus() != Navigator.RouteStatus.OK) {
        Log.w(TAG, "Route status: " + routeDescription.getRouteStatus());
        return;
      }

      // Check whether the Navigation SDK applied the route token.
      RouteTokenExecutionDetails executionDetails =
          routeDescription.getRouteTokenExecutionDetails();
      if (executionDetails == null) {
        Log.i(TAG, "Route token details aren't available.");
      } else if (executionDetails.getTokenExecutionStatus()
          != RouteTokenExecutionDetails.TokenExecutionStatus.TOKEN_SUCCESSFULLY_APPLIED) {
        Log.w(TAG, "The route might differ from your planned route.");
      }

      navigator.startGuidance();
    };

// Set destinations using the route token.
navigator.setDestinationsWithToken(routeToken, callback);

// Or with display options.
DisplayOptions displayOptions = new DisplayOptions();
navigator.setDestinationsWithToken(routeToken, displayOptions, callback);

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

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

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

    • RoutingOptions.avoidHighways
    • RoutingOptions.avoidTolls
    • RoutingOptions.avoidFerries
    • Navigator.setLicensePlateRestrictionInfo
    • وضع السفر الذي تم ضبطه في تطبيقك

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

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