این راهنما برای چه کسانی است: اگر توسعه‌دهنده تلفن همراه هستید و مسئولیت ساختن تجربه ناوبری گام‌به‌گام برای رانندگان کامیون، اتوبوس، یا دیگر وسایل نقلیه تجاری بزرگ را برعهده دارید، این راهنما را بخوانید.
موضوعات تحت پوشش این راهنما: این راهنما توضیح می‌دهد که چگونه یک مسیر مخصوص کامیون را که توسط Routes API یا Route Optimization API تولید شده است، بگیرید و از آن برای راه‌اندازی یک جلسه ناوبری گام‌به‌گام با Navigation SDK برای Android استفاده کنید.
آنچه خواهید آموخت
با نحوه انجام کارهای زیر آشنا خواهید شد:
- از
routeTokenبرای متصل کردن برنامه‌ریزی مسیر پس‌زمینه با تجربه ناوبری درون‌برنامه استفاده کنید. - کیت توسعه نرم‌افزار ناوبری را پیکربندی کنید تا از مسیر کامیون ازپیش برنامه‌ریزی‌شده استفاده کند.
- با نحوه نمایش محدودیت‌های ویژه کامیون برای راننده در رابط کاربری ناوبری آشنا شوید.
پیش‌نیازها
قبل‌از شروع، مطمئن شوید که الزامات زیر را برآورده می‌کنید:
۱. درخواست دسترسی برای پروژه
مسیریابی خودروهای بزرگ برای مجموعه محدودی از مشتریان دردسترس است. برای ابراز علاقه و درخواست دسترسی برای پروژه Google Cloud خود، فرم تماس را تکمیل کنید. نماینده Google برای مراحل بعدی با شما تماس خواهد گرفت.
وقتی Google دسترسی را اعطا کرد، مطمئن شوید پروژه Google Cloud شما برای مسیریابی خودروهای بزرگ آماده شده باشد.
اگر سازمانتان از پروژه‌های Google Cloud جداگانه برای میاناهای برنامه‌سازی کاربردی مسیریابی پس‌زمینه و Navigation SDK تلفن همراه استفاده می‌کند، با Google تماس بگیرید تا هر پروژه را تأمین کند.
۲. راه‌اندازی تولید مسیر پسین و دریافت کد مسیر
قبل‌از شروع ناوبری در دستگاه، سرور زیرینه شما باید مسیر کامیون را تولید کند و بااستفاده از یکی از میاناهای برنامه‌سازی کاربردی زیر، routeToken را دریافت کند:
- Routes API: برای محاسبه مسیرهای تک‌کامیونی بین مبدأ و مقصد توصیه می‌شود. برای دستورالعمل‌های راه‌اندازی، به تولید مسیرها و زمان‌های تقریبی ورود برای وسایل نقلیه بزرگ مراجعه کنید.
- Route Optimization API: برای بهینه‌سازی مسیرهای چندایستگاهی در ناوگان توصیه می‌شود. برای اطلاعات بیشتر، راهنمای مسیریابی خودروهای بزرگ Route Optimization API را ببینید.
درخواست باطن شما باید travelMode: TRUCK را به‌همراه ویژگی‌های فیزیکی خودرو (ارتفاع، عرض، طول، وزن، تعداد محور، و محموله خطرناک) مشخص کند. میانای برنامه‌سازی کاربردی مسیریابی در پاسخ خود routeToken را برمی‌گرداند که
سرور زیرینه شما آن را به برنامه تلفن همراهتان ارسال می‌کند.
۳. برآورده کردن حداقل ملزومات سیستم و کیت توسعه نرم‌افزار
برنامه شما باید از حداقل نسخه لازم Navigation SDK 5.2.0 یا جدیدتر استفاده کند.علاوه‌براین، پروژه شما باید از الزامات راه‌اندازی Navigation SDK استاندارد پیروی کند.
محدودیت‌ها و دستورالعمل‌های عملیاتی
قبل‌از شروع، به محدودیت‌ها و دستورالعمل‌های عملیاتی زیر توجه کنید:
- دردسترس بودن جغرافیایی: مسیریابی خودروهای بزرگ در ۴۸ ایالت به‌هم‌پیوسته ایالات متحده (به‌طور کلی دردسترس است) و ژاپن (آزمایشی) دردسترس است. این ویژگی در آلاسکا، هاوایی، یا قلمروهای ایالات متحده دردسترس نیست.
- توصیه و ایمنی راننده: رانندگان نباید صرفاً به مسیرهای برگردانده‌شده توسط Navigation SDK برای ایمن یا قانونی بودن تکیه کنند. ممکن است مسیرها در همه شرایط جاده‌ای برای خودرو مناسب نباشد و دنبال کردن آن‌ها می‌تواند رانندگان را درمعرض خطراتی مثل ارتفاع کم یا جاده‌های دارای محدودیت وزن قرار دهد. رانندگان باید همیشه هوشیار باشند و از تابلوهای جاده‌ای و مقررات محلی پیروی کنند.
- مسیرهای با بهترین تلاش: وقتی میانای برنامه‌سازی کاربردی مسیریابی نمی‌تواند مسیری پیدا کند که کاملاً با محدودیت‌های خودرو مطابقت داشته باشد، مسیری با «بهترین تلاش» برمی‌گرداند که ممکن است همچنان از بخش‌های محدودشده عبور کند. برای مثال، Routes API پرچم
routeRestrictionsPartiallyIgnoredرا در پاسخ خود تنظیم می‌کند. هنگام پیمایش این مسیرها، Navigation SDK برای برجسته کردن محدودیت‌های مربوطه، توضیحات مسیر را نمایش می‌دهد. در این موارد، مسیرها را با دقت برنامه‌ریزی کنید و از مسیر پرچم‌گذاری‌شده به‌عنوان تنها منبع حقیقت برای برنامه‌ریزی یا ناوبری استفاده نکنید. - ویژگی‌های پشتیبانی‌نشده: مسیریابی وسایل نقلیه بزرگ از ویژگی‌های زیر پشتیبانی نمی‌کند:
- قیمت عوارض کامیون
- حد سرعت ویژه کامیون یا خودرو سنگین
- مسیر مواد خطرناک رادیواکتیو
- محدودیت‌های استفاده: درخواست‌های ارسالی به «کیت توسعه نرم‌افزار ناوبری» از محدودیت‌های استفاده و سهمیه استاندارد پیروی می‌کنند. برای اطلاعات بیشتر، استفاده و صورت‌حساب را ببینید.
نمایش واسط کاربر ویژه کامیون (برون‌خط‌های مسیر)
Navigation SDK به‌طور خودکار هشدارهای تصویری، به‌نام برون‌خط‌های مسیر، را روی نقشه نمایش می‌دهد تا به رانندگان درباره محدودیت‌های پیش‌رو برای کامیون‌ها هشدار دهد. توضیحات برای محدودیت‌هایی که درطول مسیر برنامه‌ریزی‌شده وجود دارد نشان داده می‌شود، اما در جاده‌های اطراف نمایش داده نمی‌شود.
کیت توسعه نرم‌افزار پیمایش شامل فراخوان‌هایی برای محدودیت‌های زیر است:
| محدودیت | نماد و نوشتار نوشته راهنما | شرایط نمایش |
|---|---|---|
| قد |
زرد = هشدار، خودرو شما نزدیک به حداکثر ارتفاع مجاز است 
قرمز = خودرو شما بالاتر از حداکثر ارتفاع مجاز است |
وقتی ارتفاع خودرو نزدیک به محدودیت باشد، توضیحی زرد ظاهر می‌شود.
اگر مسیر غیرمنطبق باشد و محدودیت ارتفاع را نقض کند، کادر شرح قرمز نشان داده می‌شود. 
|
| وزن |
|
وقتی وزن خودرو از حد مجاز جاده بیشتر باشد،
یک بالون شرح قرمز ظاهر می‌شود.
|
| ورود کامیون ممنوع |
|
وقتی در بخشی از جاده که محدودیت کامیون تجاری دارد سفر می‌کنید،
یک کادر شرح قرمز ظاهر می‌شود.
|
| کالاهای خطرناک |
|
وقتی بار مواد خطرناک خودرو در بخشی از جاده ممنوع باشد، توضیحی به رنگ قرمز نشان داده می‌شود.
|
نحوه عملکرد نشان‌های مسیر
routeToken عکس آنی رمزگذاری‌شده‌ای از مسیری است که توسط پس‌زمینه مسیریابی Google ایجاد شده است. این درخواست هندسه مسیر برنامه‌ریزی‌شده و همچنین ابعاد فیزیکی و نمایه محدودیت خودرو را دربرمی‌گیرد.
گردش کار این مراحل را دنبال می‌کند:
- درخواست مسیر: سرور زیرینه شما مسیر کامیون را از Routes API (یا Route Optimization API) درخواست می‌کند.
- دریافت کردن کد: میانای برنامه‌سازی کاربردی مسیریابی مسیر سازگار را محاسبه می‌کند و
routeTokenرا به سرور زیرینه شما برمی‌گرداند. - ارسال کردن توکن: سرور زیرینه شما
routeTokenو مختصات مقصد را به برنامه تلفن همراه شما ارسال می‌کند. - انتقال به کیت توسعه نرم‌افزار: برنامه تلفن همراه
routeTokenرا به کیت توسعه نرم‌افزار پیمایش منتقل می‌کند. - شروع راهنمایی: کیت توسعه نرم‌افزار ناوبری همه جنبه‌های تجربه گام‌به‌گام را مدیریت می‌کند، ازجمله ارائه توضیحات مسیر و مدیریت مسیریابی مجدد پویا براساس محدودیت‌های خودرو.
محاسبه مجدد و مسیریابی مجدد پویا
درطول ناوبری فعال، شرایط ترافیک، راه‌بندان‌ها، یا پیچ‌های ازدست‌رفته ممکن است باعث شود خودرو از مسیر برنامه‌ریزی‌شده منحرف شود.
وقتی تغییر مسیر رخ می‌دهد:
- کیت توسعه نرم‌افزار پیمایش به‌طور خودکار مسیر رسیدن به مقصد را دوباره محاسبه می‌کند.
- کیت توسعه نرم‌افزار ویژگی‌ها و ابعاد خودرو را که در
routeTokenاصلی کدبندی شده است حفظ می‌کند. - مسیر جدید محاسبه‌شده از ارتفاع‌های کم، پل‌های دارای محدودیت وزن، و جاده‌های ممنوع برای کامیون‌های تجاری اجتناب می‌کند.
پیاده‌سازی: شروع سفر مختص کامیون
برای مقداردهی اولیه و شروع ناوبری گام‌به‌گام با کد مسیر خودرو بزرگ، این مراحل را دنبال کنید.
مرحله ۱: دریافت کردن کد مسیر از پسین
برنامه تلفن همراه شما رشته routeToken را به‌همراه مختصات مقصد از سرور زیرینه شما دریافت می‌کند. برای جزئیات درباره تولید این
توکن در سرور، به تولید مسیرهای وسایل نقلیه بزرگ و زمان‌های تقریبی ورود
در اسناد Routes API مراجعه کنید.
کد زیر نمونه‌ای از یک کد مسیر است:
{
"routeToken": "CqMBCjoKCJQOor5DHcwiEhBon3XpHXFnVvDeWMwd9PpAGgz6wtnFDKIBrAHTARpCApUDSggAAAAACjcrP3gBEAQaTApKChgKDQoCCAERAAAAAACAZkAR3SQGgZUXdUASEggAEAMQBhATEBIYAkIEGgIIBSIYChZ2VEJiWlBPSkk1aU5wUVRzNTV5d0FRKAEiFQBcJuds-Efh-2QZhOMTtUCCxEVL_g"
}
مرحله ۲: پیکربندی CustomRoutesOptions
کد مسیر را بااستفاده از
CustomRoutesOptions.builder به نمونه CustomRoutesOptions ارسال کنید:
- بااستفاده از
setRouteToken(routeToken)، داده‌واحد را ارسال کنید. - تنظیم حالت سفر بااستفاده از
setTravelMode(CustomRoutesOptions.TravelMode.DRIVING).
مرحله ۳: تعریف کردن نقاط‌مسیر و تنظیم کردن مقصدها
نقاط‌مسیر مقصدتان و CustomRoutesOptions را به
navigator.setDestinations ارسال کنید.
هنگام پیکربندی نقاط‌مسیر و ارسال گزینه‌های مسیر سفارشی، موارد زیر را درنظر داشته باشید:
- الزامات مطابقت مقصد: مختصات مقصد ارسال‌شده به
setDestinationsباید با مختصات مقصد استفاده‌شده هنگام تولیدrouteTokenمطابقت داشته باشد. مشخص کردن مقصد متفاوت باعث بروز خطا می‌شود. - مسیریابی کنار جاده: خودروهای تجاری بزرگ نمی‌توانند به‌راحتی در خیابان‌های باریک دور بزنند. برای اطمینان از اینکه کامیون از سمت درست جاده به مقصد نزدیک می‌شود،
setPreferSameSideOfRoad(true)را در نقاط‌مسیرتان فراخوانی کنید. - توقفگاه‌های خودرو: برای راهنمایی کامیون به مکان مناسب برای توقف یا تخلیه بار،
setVehicleStopover(true)را در نقطه‌مسیرهایتان فراخوانی کنید. - نقاط ناوبری: اگر مقصد شما ورودی باربری یا سکوی بارگیری مشخصی دارد، آن را بااستفاده از نشان نقطه ناوبری مشخص کنید.
مرحله ۴: مدیریت وضعیت مسیر و شروع راهنمایی
OnResultListener را در
ListenableResultFuture<Navigator.RouteStatus> ثبت کنید. وقتی وضعیت مسیر OK است،
navigator.startGuidance را فراخوانی کنید تا ناوبری گام‌به‌گام فعال شروع شود.
نمونه کد
از CustomRoutesOptions.builder برای تنظیم کردن کد استفاده کنید و سپس آن را به
navigator.setDestinations ارسال کنید.
// Obtain the routeToken string from your backend
val routeToken = "route token returned by Routes API"
val customRoutesOptions = CustomRoutesOptions.builder()
.setRouteToken(routeToken)
.setTravelMode(TravelMode.DRIVING)
.build()
// Specify the same destination used to create the route token
ArrayList <Waypoint> destinations = Lists.newArrayList();
val destination = Waypoint.builder()
.setLatLng(10.0, 20.0)
.setTitle("title")
.setVehicleStopover(true)
.build()
destinations.add(destination);
navigator.setDestinations(destinations, customRoutesOptions)
نمایشگرهای داخل خودرو
می‌توانید جلسه ناوبری خودرو بزرگ را بااستفاده از ناوبری برای Android Auto روی صفحه‌نمایش‌های داشبورد نمایش دهید.مراحل بعدی
- اصلاح میانای کاربر پیمایش: کنترل‌های میانای کاربر داخلی و عناصر بصری، مانند قطب‌نما، دکمه مرکز مجدد، و چشم‌انداز دوربین را سفارشی‌سازی کنید.
- گوش دادن به رویدادهای ناوبری: به‌روزرسانی‌های ناوبری و رویدادهای چرخه حیات را مدیریت کنید، مانند پیشرفت مسیر، تغییرات زمان تقریبی ورود، و تغییر مسیرها.