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

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

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

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

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

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

نظرة عامة

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

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

  1. عليك إعداد بيئتك للوصول إلى مستودع Maven المضيف:

    Maven

    أضِف ما يلي إلى ملف pom.xml:

        <project>
      ...
      <repositories>
        <repository>
          <id>google-maven-repository</id>
          <url>https://maven.google.com</url>
        </repository>
      </repositories>
      ...
    </project>

    Gradle

    أضِف ما يلي إلى ملف build.gradle:

    repositories {
    ...
    google()
}
  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 تم تنزيله (كبديل)

تتوفّر مكتبة TurnByTurn كملف 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. الاطّلاع على مثال لعرض التنقّل الذي يعرض العناصر الأساسية

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

ترتبط حزمة 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.

تسجيل الخدمة للحصول على تحديثات التنقّل

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

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

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

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

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

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

navigator.unregisterServiceForNavUpdates();

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

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

  • في الطريق: تعني الحالة ENROUTE أنّ ميزة التنقّل الإرشادي مفعّلة حاليًا ويسير المستخدم على المسار المقدَّم. تتوفّر معلومات عن الخطوة الراهنة المقبلة من المناورة.

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

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

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

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

شاشة جهاز جوّال تعرض إشارة إلى أنّه عليك الانعطاف يسارًا بعد 30 مترًا على W Ahwanee Ave. في أسفل الشاشة، يظهر الوقت المتبقّي للوصول إلى الوجهة وهو 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، يتيح IDE لنظام تحديد المواقع إنشاء رموز إرشادات المناورات والممرات. تتوافق هذه الرموز مع إرشادات تحديد حجم الصور في مكتبة تطبيقات Android Auto Car App التي تنصح باستهداف مربّع حدود بحجم 500 x ‏74 dp. راجِع 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 باستخدام الرموز.

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