فعال کردن فید داده گام‌به‌گام

فید داده گام‌به‌گام اطلاعات فقط ناوبری را به دستگاه‌هایی ارائه می‌دهد که برای راهنمایی ناوبری مبتنی بر نقشه طراحی نشده‌اند. این مؤلفه مانورهای پیش‌رو را با عناصری که ارائه می‌دهید فراهم می‌کند:

  • نمادها (چپ، راست، دوربرگردان)
  • دور زدن در میدان‌ها
  • نام جاده‌ها
  • مسافت و زمان تخمینی تا مرحله بعدی پیمایش یا مقصد نهایی

می‌توانید از فید گام‌به‌گام برای ایجاد تجربه‌هایی استفاده کنید که در آن‌ها رابط کاربری کامل Navigation SDK مناسب نیست، مثلاً برای Android Auto یا برای نمایشگرهای کوچک که پشته کامل Android دردسترس نیست. برای مثال، می‌توانید از این ویژگی برای رانندگان وسایل نقلیه دوچرخ استفاده کنید، جایی که می‌توانید راهنمایی‌های فقط ناوبری را نمایش دهید تا به آن‌ها کمک کنید سریع‌تر و با اطمینان بیشتر و با کمترین حواس‌پرتی به مقصد برسند.

برای استفاده از کیت توسعه نرم‌افزار، سرویسی ایجاد می‌کنید و آن را در «کیت توسعه نرم‌افزار پیمایش برای Android» ثبت می‌کنید تا بتواند اطلاعات پیمایش جدید را در زمان واقعی (تقریباً یک بار در ثانیه درطول پیمایش) دریافت کند.

این سند به شما نشان می‌دهد که چگونه یک سرویس ناوبری ایجاد و ثبت کنید که اطلاعات ناوبری را از SDK دریافت می‌کند و وضعیت ناوبری را به دستگاه گیرنده ارائه می‌دهد.

نمای کلی

این بخش جریان سطح بالا را برای فعال کردن ویژگی گام‌به‌گام خلاصه می‌کند.

استفاده از ویژگی «گام‌به‌گام»

مراحل سطح بالا برای فعال کردن ویژگی گام‌به‌گام در اینجا آمده است. بخش‌های زیر جزئیات مربوط به هر مرحله را ارائه می‌دهند.

  1. سرویسی برای دریافت به‌روزرسانی‌های پیمایش ایجاد کنید.

  2. سرویس را ثبت کنید.

  3. آشنایی با حالت‌های پیمایش.

سرویسی برای دریافت به‌روزرسانی‌های ناوبری ایجاد کنید

کیت توسعه نرم‌افزار پیمایش به سرویس «گام‌به‌گام» شما متصل می‌شود و به‌روزرسانی‌های پیمایش را ازطریق 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);

شروع و توقف سرویس

سرویس پیمایش تا زمانی فعال است که کیت توسعه نرم‌افزار پیمایش به آن متصل باشد. می‌توانید به‌صورت دستی startService() و stopService() را فراخوانی کنید تا چرخه حیات سرویس ناوبری را کنترل کنید، اما وقتی سرویس خود را با کیت توسعه نرم‌افزار ناوبری ثبت می‌کنید، سرویس شما به‌طور خودکار شروع می‌شود و تنها زمانی متوقف می‌شود که ثبت آن را لغو کنید. بسته به نحوه راه‌اندازی برنامه‌تان، ممکن است بخواهید راه‌اندازی سرویس پیش‌زمینه‌ای را که در سند Android نمای کلی سرویس‌ها شرح داده شده است درنظر بگیرید.

درحال لغو ثبت سرویس

برای توقف دریافت به‌روزرسانی‌های ناوبری، سرویس را از کیت توسعه نرم‌افزار ناوبری لغو ثبت کنید.

navigator.unregisterServiceForNavUpdates();

آشنایی با حالت‌های پیمایش

از NavInfo.getNavState() برای دریافت وضعیت فعلی پیمایش استفاده کنید که یکی از موارد زیر است:

  • در مسیر - وضعیت ENROUTE یعنی پیمایش راهنمایی‌شده فعال است و کاربر در مسیر ارائه‌شده قرار دارد. اطلاعات مربوط به مرحله مانور آتی فعلی دردسترس است.

  • درحال تغییر مسیر - REROUTING یعنی پیمایش درحال انجام است، اما ناوبر به‌دنبال مسیر جدیدی است. مرحله مانور بعدی دردسترس نیست، چون هنوز مسیر جدیدی وجود ندارد. در برنامه نمونه، پیام «درحال مسیریابی مجدد…» در نمایشگر اطلاعات ناوبری نشان داده می‌شود. وقتی مسیری پیدا شد، پیام NavInfo با وضعیت ENROUTE ارسال می‌شود.

  • متوقف شد - STOPPED یعنی ناوبری پایان یافته است. برای مثال، وقتی کاربر از پیمایش در برنامه خارج می‌شود، پیمایش متوقف می‌شود. در برنامه نمونه، وضعیت STOPPED نمایش اطلاعات پیمایش را پاک می‌کند تا از نمایش دستورالعمل‌های مرحله‌ای باقی‌مانده جلوگیری شود.

پر کردن نمایش فید

اکنون که سرویس گام‌به‌گام خود را راه‌اندازی کرده‌اید، این بخش عناصر دیداری و نوشتاری را پوشش می‌دهد که می‌توانید برای پر کردن کارت‌های راهنمایی برای فید گام‌به‌گام استفاده کنید.

صفحه تلفن همراهی که پیچیدن به چپ در ۱۰۰ فوت جلوتر به خیابان «دبلیو آهوانی» را نشان می‌دهد. در پایین صفحه، زمان باقی‌مانده تا مقصد ۴۶ دقیقه و فاصله باقی‌مانده ۳۹ مایل است.

وقتی کاربر وارد ناوبری راهنمایی‌شده می‌شود، کارت ناوبری در بالا ظاهر می‌شود، که حاوی داده‌های ناوبری است که از کیت توسعه نرم‌افزار Navigation پر شده است. تصویر مرتبط نمونه‌ای از این عناصر ضروری پیمایش را نشان می‌دهد.

این جدول فیلدهای اطلاعات پیمایش و جایی را که می‌توانید آن‌ها را پیدا کنید نشان می‌دهد.

فیلدهای مربوط به هر مرحله پیمایش فیلدهای کل سفر
در StepInfo پیدا شد در NavInfo پیدا شد
نام کامل جاده زمان باقی‌مانده
نماد مانور فاصله تا مقصد
فاصله تا مرحله بعدی
فیلدهای راهنمای باند

راهنمای خطوط

‫Navigation 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 enum هر مانور احتمالی را که ممکن است هنگام پیمایش رخ دهد تعریف می‌کند و شما می‌توانید مانور را برای یک مرحله معین از روش StepInfo.getManeuver() دریافت کنید.

باید نمادهای مانور ایجاد کنید و آن‌ها را با مانورهای مرتبطشان جفت کنید. برای برخی‌از مانورها، می‌توانید نگاشت یک‌به‌یک به نماد تنظیم کنید، مثل DESTINATION_LEFT و DESTINATION_RIGHT. بااین‌حال، چون برخی‌از مانورها مشابه هستند، شاید بخواهید بیش‌از یک مانور را به یک نماد نگاشت کنید. برای مثال، TURN_LEFT و ON_RAMP_LEFT هر دو می‌توانند به نماد گردش به چپ نگاشت شوند.

برخی‌از مانورها حاوی برچسب clockwise یا counterclockwise اضافی هستند، که کیت توسعه نرم‌افزار آن را براساس جهت رانندگی در کشور تعیین می‌کند. برای مثال، در کشورهایی که رانندگی در سمت چپ جاده است، رانندگان در جهت ساعت‌گرد وارد میدان می‌شوند یا دور کامل می‌زنند، درحالی‌که در کشورهایی که رانندگی در سمت راست جاده است، رانندگان در جهت ساعت‌گرد حرکت می‌کنند. کیت توسعه نرم‌افزار Navigation تشخیص می‌دهد که آیا مانور در ترافیک سمت چپ یا راست رخ می‌دهد و مانور مناسب را خروجی می‌دهد. بنابراین، نماد مانور شما ممکن است برای مانور ساعت‌گرد درمقایسه با پادساعت‌گرد متفاوت باشد.

برای دیدن نمادهای نمونه برای مانورهای مختلف، ازهم باز کنید

نماد نمونه مانورهای گام‌به‌گام
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

استفاده از نمادهای تولیدشده

فهرست کوچکی از نمادهای تولیدشده که Navigation SDK ارائه کرده است.

برای تسهیل موارد استفاده Android Auto، Navigation SDK از تولید نمادهای راهنمای مانور و لاین پشتیبانی می‌کند. این نمادها با راهنمای اندازه تصویر کتابخانه برنامه خودرو Android Auto مطابقت دارند که هدف‌یابی جعبه مرزی ۵۰۰ × ۷۴ 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 را با نمادها پر می‌کند.

قدم بعدی چیست