تفعيل اتّجاهات مفصّلة للبيانات

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

• رموز (يسار، يمين، انعطاف للخلف)
• أرقام المنعطفات في الدوارات
• أسماء الطرق
• المسافات والوقت المقدَّر للوصول إلى خطوة التنقّل التالية أو الوجهة النهائية

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

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

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

نظرة عامة

يلخّص هذا القسم المسار العام لتفعيل ميزة الاتجاهات المفصّلة.

استخدام ميزة TurnByTurn

في ما يلي الخطوات العامة لتفعيل ميزة الاتجاهات المفصّلة. وتقدّم الأقسام التالية تفاصيل حول كل خطوة.

1. أنشئ خدمة لتلقّي تعديلات التنقّل.

2. سجِّل الخدمة.

3. فهم حالات التنقّل

إنشاء خدمة لتلقّي آخر الأخبار حول التنقّل

ترتبط حزمة تطوير البرامج (SDK) للتنقّل بخدمة TurnByTurn وترسل إليها تحديثات التنقّل من خلال Android Messenger. يمكنك إنشاء خدمة تنقّل جديدة لهذه التعديلات أو استخدام خدمة حالية.

تتمثل فائدة استخدام خدمة لتلقي تحديثات التنقل في أن الخدمة يمكن أن تعمل في عملية في الخلفية منفصلة.

تتلقّى الخدمة في المثال التالي معلومات التنقّل وتستخدم TurnByTurnManager لتحويل البيانات إلى عنصر NavInfo يحتوي على تفاصيل التنقّل.

/**
 *   Receives turn-by-turn navigation information forwarded from NavSDK.
 */
public class NavInfoReceivingService extends Service {
  /** The messenger used by the service to receive nav step updates. */
  private Messenger incomingMessenger;
  private TurnByTurnManager turnByTurnManager;

  private final class IncomingNavStepHandler extends Handler {
    public IncomingNavStepHandler(Looper looper) {
      super(looper);
    }

    @Override
    public void handleMessage(Message msg) {
      // Identify the message through the msg.what field.
      if (TurnByTurnManager.MSG_NAV_INFO == msg.what) {
        // Extract the NavInfo object using the TurnByTurnManager.
        NavInfo navInfo = turnByTurnManager
          .readNavInfoFromBundle(msg.getData()));
      // Do something with the NavInfo
    }
  }
}

@Nullable
@Override
public IBinder onBind(Intent intent) {
  return incomingMessenger.getBinder();
}

@Override
public void onCreate() {
  turnByTurnManager = TurnByTurnManager.createInstance();
  HandlerThread thread =
    new HandlerThread("NavInfoReceivingService",
      Process.THREAD_PRIORITY_DEFAULT);
  thread.start();
  incomingMessenger = new Messenger(
    new IncomingNavStepHandler(thread.getLooper()));
}

رموز الرسائل

يمكن تحديد رسائل NavInfo من خلال حقل Message.what في فئة Message، والذي يتم ضبطه على قيمة TurnByTurnManager.MSG_NAV_INFO.

ملاحظة: تأكَّد من تخصيص نطاق القيم 7200-7299 لرموز الرسائل، لأنّ حزمة تطوير البرامج (SDK) للتنقّل قد تستخدم رموز الرسائل في هذا النطاق في المستقبل.

جارٍ تسجيل الخدمة لتلقّي تحديثات التنقّل

تسجّل مقتطفات الرمز التالية خدمة التنقّل.

boolean isNavInfoReceivingServiceRegistered =
          navigator.registerServiceForNavUpdates(
              getPackageName(), NavInfoReceivingService.class.getName(), numNextStepsToPreview);

بدء الخدمة وإيقافها

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

إلغاء تسجيل الخدمة

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

navigator.unregisterServiceForNavUpdates();

فهم حالات التنقّل

استخدِم NavInfo.getNavState() للحصول على الحالة الحالية للتنقّل، وهي إحدى الحالات التالية:

• Enroute: تعني الحالة ENROUTE أنّ ميزة التنقّل الموجَّه مفعَّلة وأنّ المستخدم يسلك المسار المقدَّم. تتوفّر معلومات عن خطوة المناورة القادمة الحالية.

• جارٍ تغيير المسار: تشير الحالة REROUTING إلى أنّ التنقّل جارٍ، ولكنّ المتصفّح يبحث عن مسار جديد. خطوة المناورة القادمة غير متاحة، لأنّه ما مِن مسار جديد بعد. في نموذج التطبيق، تظهر رسالة "جارٍ إعادة التوجيه..." في شاشة عرض معلومات التنقّل. بعد العثور على مسار، يتم إرسال رسالة NavInfo بالحالة ENROUTE.

• متوقّف: يشير الرمز STOPPED إلى انتهاء التنقّل. على سبيل المثال، يتوقف التنقّل عندما يخرج المستخدم من التنقّل في التطبيق. في نموذج التطبيق، تؤدي حالة STOPPED إلى محو عرض معلومات التنقّل لمنع عرض تعليمات الخطوات المتبقية.

تعبئة عرض الخلاصة

بعد إعداد خدمة الاتّجاهات المفصّلة، يتناول هذا القسم العناصر المرئية والعناصر النصية التي يمكنك استخدامها لتعبئة بطاقات الإرشاد في خلاصة الاتّجاهات المفصّلة.

حقول معلومات بطاقة التنقّل

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

يعرض هذا الجدول حقول معلومات التنقّل ومكان العثور عليها.

حقول لكل خطوة تنقّل	حقول الرحلة بأكملها
تم العثور على المصادر في StepInfo	تم العثور على المصادر في NavInfo
اسم الطريق الكامل	الوقت المتبقي
رمز المناورة	المسافة إلى الوجهة
المسافة إلى الخطوة التالية
حقول توجيه خط السير

توجيه خط السير

تمثّل حزمة تطوير البرامج (SDK) للتنقّل المسارات في بطاقة التنقّل عند المنعطفات على أنّها عناصر بيانات Lane وLaneDirection. يمثّل عنصر Lane مسارًا معيّنًا أثناء التنقّل، ويحتوي على قائمة بعناصر LaneDirection التي تصف جميع الانعطافات التي يمكن إجراؤها من هذا المسار.

يتم تحديد الاتجاه المقترَح الذي يجب أن يسلكه المستخدم في مسار معيّن من خلال الحقل isRecommended.

مثال على توجيه خط السير

يوضّح المقتطف التالي تمثيل البيانات للمسارات المعروضة أعلاه.

// Lane 1
LaneDirections = [{/*laneShape=*/ STRAIGHT, /*isRecommended=*/ false},
                  {/*laneShape=*/ SLIGHT_LEFT, /*isRecommended=*/ true}]

// Lane 2
LaneDirections = [{/*laneShape=*/ STRAIGHT, /*isRecommended=*/ false}]

إنشاء رموز للمناورات

يحدّد التعداد Maneuver كل مناورة محتملة يمكن أن تحدث أثناء التنقّل، ويمكنك الحصول على المناورة لخطوة معيّنة من خلال طريقة StepInfo.getManeuver().

يجب إنشاء رموز المناورات وإقرانها بالمناورات المرتبطة بها. بالنسبة إلى بعض المناورات، يمكنك إعداد ربط فردي برمز، مثل DESTINATION_LEFT وDESTINATION_RIGHT. ومع ذلك، نظرًا لأن بعض المناورات متشابهة، فقد ترغب في تعيين أكثر من مناورة لأيقونة واحدة. على سبيل المثال، يمكن أن يشير كل من TURN_LEFT وON_RAMP_LEFT إلى رمز الانعطاف لليسار.

مناورات Android Auto: المناورات في حزمة تطوير البرامج للتنقّل لها ربط واحد بواحد مع Android Auto، ولكن يجب تحويل الأنواع إلى التنسيق الصحيح لـ Android Auto. يُرجى الاطّلاع على التحقّق من أنواع المناورات الصحيحة في تفعيل ميزة التنقّل في Android Auto.

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

توسيع القائمة للاطّلاع على أمثلة على رموز المناورات المختلفة

رمز العيّنة	TurnByTurn Maneuvers
	DEPART UNKNOWN
	STRAIGHT ON_RAMP_UNSPECIFIED OFF_RAMP_UNSPECIFIED NAME_CHANGE
	TURN_RIGHT ON_RAMP_RIGHT
	TURN_LEFT ON_RAMP_LEFT
	TURN_SLIGHT_RIGHT ON_RAMP_SLIGHT_RIGHT OFF_RAMP_SLIGHT_RIGHT
	TURN_SLIGHT_LEFT ON_RAMP_SLIGHT_LEFT OFF_RAMP_SLIGHT_LEFT
	TURN_SHARP_RIGHT ON_RAMP_SHARP_RIGHT OFF_RAMP_SHARP_RIGHT
	TURN_SHARP_LEFT ON_RAMP_SHARP_LEFT OFF_RAMP_SHARP_LEFT
	TURN_U_TURN_COUNTERCLOCKWISE ON_RAMP_U_TURN_COUNTERCLOCKWISE OFF_RAMP_U_TURN_COUNTERCLOCKWISE
	TURN_U_TURN_CLOCKWISE ON_RAMP_U_TURN_CLOCKWISE OFF_RAMP_U_TURN_CLOCKWISE
	ROUNDABOUT_SHARP_RIGHT_COUNTERCLOCKWISE
	ROUNDABOUT_SHARP_RIGHT_CLOCKWISE
	ROUNDABOUT_RIGHT_COUNTERCLOCKWISE
	ROUNDABOUT_RIGHT_CLOCKWISE
	ROUNDABOUT_SLIGHT_RIGHT_COUNTERCLOCKWISE
	ROUNDABOUT_SLIGHT_RIGHT_CLOCKWISE
	ROUNDABOUT_STRAIGHT_COUNTERCLOCKWISE
	ROUNDABOUT_STRAIGHT_CLOCKWISE
	ROUNDABOUT_SLIGHT_LEFT_COUNTERCLOCKWISE
	ROUNDABOUT_SLIGHT_LEFT_CLOCKWISE
	ROUNDABOUT_LEFT_COUNTERCLOCKWISE
	ROUNDABOUT_LEFT_CLOCKWISE
	ROUNDABOUT_SHARP_LEFT_COUNTERCLOCKWISE
	ROUNDABOUT_SHARP_LEFT_CLOCKWISE
	ROUNDABOUT_U_TURN_COUNTERCLOCKWISE
	ROUNDABOUT_U_TURN_CLOCKWISE
	ROUNDABOUT_COUNTERCLOCKWISE
	ROUNDABOUT_CLOCKWISE
	ROUNDABOUT_EXIT_COUNTERCLOCKWISE
	ROUNDABOUT_EXIT_CLOCKWISE
	MERGE_RIGHT OFF_RAMP_RIGHT
	MERGE_LEFT OFF_RAMP_LEFT
	FORK_RIGHT TURN_KEEP_RIGHT ON_RAMP_KEEP_RIGHT OFF_RAMP_KEEP_RIGHT
	FORK_LEFT TURN_KEEP_LEFT ON_RAMP_KEEP_LEFT OFF_RAMP_KEEP_LEFT
	MERGE_UNSPECIFIED
	DESTINATION
	DESTINATION_RIGHT
	DESTINATION_LEFT
	FERRY_BOAT
	FERRY_TRAIN

استخدام الرموز التي تم إنشاؤها

لتسهيل حالات استخدام Android Auto، تتيح حزمة تطوير البرامج (SDK) للتنقّل إنشاء رموز إرشادية للمناورات والمسارات. تتوافق هذه الرموز مع إرشادات حجم الصور في مكتبة تطبيقات السيارات في Android Auto التي تنصح باستهداف مربّع محيطي بحجم 500 × 74 بكسل مستقل الكثافة. لمزيد من التفاصيل، يُرجى الاطّلاع على setsLaneImage و CarIcon في مستندات Android المرجعية.

ملاحظة: تكون ميزة إنشاء الرموز غير مفعَّلة تلقائيًا.

مثال على إنشاء الرموز

NavigationUpdatesOptions options =
  NavigationUpdatesOptions.builder()
             .setNumNextStepsToPreview(numNextStepsToPreview)
             .setGeneratedStepImagesType(GeneratedStepImagesType.BITMAP)
             .setDisplayMetrics(getResources().getDisplayMetrics())
             .build();
boolean isRegistered =
          navigator.registerServiceForNavUpdates(
              getPackageName(),
              NavInfoReceivingService.class.getName(),
              options);

بعد تفعيل إنشاء الرموز، يملأ عنصر TurnbyTurn StepInfo الحقلَين maneuverBitmap وlanesBitmap بالرموز.

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

• بالنسبة إلى تطبيقات Android Auto:
  • رسم الخريطة وتفعيل التنقّل