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

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

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

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

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

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

نظرة عامة

يصف هذا القسم كيفية إضافة مكتبة TurnByTurn إلى مشروعاتك ويلخص التدفق عالي المستوى لبناء وظيفة مفصّلة.

لاستخدام إصدار مستقل من مكتبة TurnByCurrent، اتّبِع الخطوات التالية:

  1. اضبط بيئتك للوصول إلى مستودع Maven للمضيف كما هو موضّح في بدء استخدام حزمة تطوير البرامج (SDK) لبرنامج التشغيل في مستندات الرحلات والطلبات.

  2. أضِف التبعية التالية إلى إعدادات Maven أو Gradle:

    Maven

    <dependencies>
  ...
  <dependency>
    <groupId>com.google.android.maps</groupId>
    <artifactId>google_turnbyturn</artifactId>
    <version>1.0.0</version>
  </dependency>
</dependencies>

    Gradle

    dependencies {
  ...
  implementation 'com.google.android.maps:google_turnbyturn:1.0.0'
}

إضافة مكتبة TurnByTurn إلى مشروعك باستخدام ملف JAR الذي تم تنزيله (بديل)

تتوفّر مكتبة TurnBy Turn كملف JAR في مجلد SDK هذا. إذا لم يكن لديك إذن الوصول، يُرجى التواصل مع الممثّل.

  1. نزِّل "google_turnbyturn_*.jar" وفك ضغطه.
  2. انسخ ملف JAR الذي تم تنزيله في دليل app/libs لمشروعك.

  3. أضِف ما يلي إلى build.gradle لتضمين JAR في إصدارك.

    dependencies {
   ...
   api fileTree(include: ['*.jar'], dir: 'libs')
}

استخدام مكتبة TurnByTurn

في ما يلي الخطوات رفيعة المستوى لتفعيل وظائف اتّجاهات مفصّلة. توفر الأقسام التالية تفاصيل حول كل خطوة.

  1. أنشئ خدمة لتلقي تحديثات التنقل.

  2. تسجيل الخدمة

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

  4. الاطّلاع على مثال على عرض التنقّل الذي يعرض العناصر الأساسية

إنشاء خدمة لتلقي تحديثات التنقل {#service}

ترتبط حزمة تطوير البرامج (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.

تسجيل الخدمة للحصول على تحديثات التنقل {#register}

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

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

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

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

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

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

navigator.unregisterServiceForNavUpdates();

فهم حالات التنقل {#states}

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

  • Enroute - تعني الحالة ENROUTE أن التنقل الإرشادي نشط حاليًا وأن المستخدم في المسار المقدم. تتوفر معلومات حول خطوة المناورة القادمة الحالية.

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

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

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

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

شاشة هاتف محمول تعرض انعطافًا يسريًا قادمًا على بعد 100 قدم إلى جادة W Ahwanee. في أسفل الشاشة، يبلغ الوقت المتبقي للوصول إلى الوجهة 46 دقيقة، بينما تبلغ المسافة المتبقية 39 ميلاً.

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

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

التوسيع لعرض رموز أمثلة لمناورات مختلفة

رمز النموذج مناورات حركة المرور
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

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

قائمة صغيرة بالرموز التي تم إنشاؤها والمتوفّرة من خلال حزمة SDK الخاصة بالتنقل

ولتسهيل حالات استخدام 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 بالرموز.

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