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

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

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

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

برای استفاده از SDK، یک سرویس ایجاد می‌کنید و آن را در Navigation SDK برای Android ثبت می‌کنید تا بتواند اطلاعات ناوبری جدید را در زمان واقعی (حدود یک بار در ثانیه در طول مسیریابی) دریافت کند.

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

بررسی اجمالی

این بخش نحوه افزودن کتابخانه TurnByTurn به پروژه های خود را شرح می دهد و جریان سطح بالا را برای ساختن عملکردهای نوبت به نوبه خلاصه می کند.

کتابخانه TurnByTurn را با استفاده از Maven به پروژه خود اضافه کنید (توصیه می شود)

توجه: اگر قبلاً برنامه خود را با Navigation SDK که خود حاوی کتابخانه TurnByTurn است تنظیم کرده اید، می توانید از این مرحله صرف نظر کنید.

برای استفاده از یک نسخه مستقل از کتابخانه TurnByTurn، این مراحل را دنبال کنید:

1. محیط خود را برای دسترسی به مخزن میزبان Maven تنظیم کنید همانطور که در شروع با Driver SDK در مستندات سفر و سفارش توضیح داده شده است.

2. وابستگی زیر را به پیکربندی Maven یا Gradle خود اضافه کنید:

   ماون

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

   گریدل

   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. نمونه صفحه نمایش پیمایش را ببینید که عناصر ضروری را نشان می دهد .

یک سرویس برای دریافت به‌روزرسانی‌های ناوبری ایجاد کنید {#service}

Navigation 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 پیمایش ممکن است در آینده از کدهای پیام در آن محدوده استفاده کند.

ثبت سرویس برای به‌روزرسانی‌های ناوبری {#register}

قطعه کد زیر سرویس ناوبری را ثبت می کند.

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

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

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

لغو ثبت سرویس

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

navigator.unregisterServiceForNavUpdates();

درک وضعیت های ناوبری {#states}

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

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

• تغییر مسیر - REROUTING به این معنی است که ناوبری در حال انجام است، اما ناوبر به دنبال یک مسیر جدید است. مرحله مانور آینده در دسترس نیست، زیرا هنوز مسیر جدیدی وجود ندارد. در برنامه نمونه ، یک پیام "Rrouting..." در صفحه نمایش اطلاعات ناوبری ظاهر می شود. هنگامی که یک مسیر پیدا شد، یک پیام NavInfo با وضعیت ENROUTE ارسال می شود.

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

صفحه نمایش فید را پر کنید

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

فیلدهای اطلاعات کارت ناوبری

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

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

فیلدها برای هر مرحله ناوبری	زمینه برای سفر کلی
در 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 هر دو می‌توانند به نماد گردش به چپ نگاشت شوند.

مانورهای Android Auto : مانورهای موجود در Navigation SDK دارای نگاشت یک به یک به Android Auto هستند، اما باید انواع را به فرمت صحیح Android Auto تبدیل کنید. به اطمینان از انواع مانور صحیح در فعال کردن پیمایش برای Android Auto مراجعه کنید.

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

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

نماد نمونه	مانورهای TurnByTurn
	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، Navigation SDK از تولید نمادهای مانور و هدایت مسیر پشتیبانی می‌کند. این نمادها با راهنمای اندازه‌گیری تصویر کتابخانه 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 را با نمادها پر می کند.

بعدش چی

• برای برنامه‌های Android Auto :
  • نقشه را بکشید و ناوبری را فعال کنید .