گاهی اوقات ممکن است بخواهید مسیری را که برنامه‌تان به کاربران ارائه می‌دهد برنامه‌ریزی کنید. استفاده از یک کد مسیر از Routes API، Routes Preferred API، یا Route Optimization API می‌تواند به شما کمک کند دو چیز را برای مسیر برنامه‌ریزی‌شده خود مشخص کنید:
چندخطی برای مسیر
اهداف مسیر شما
برای مثال، در اینجا چند نمونه از اهداف مسیریابی که ممکن است داشته باشید آورده شده است:
به‌حداقل رساندن زمان تحویل: کسب‌وکاری که غذا تحویل می‌دهد ممکن است بخواهد زمان لازم برای تحویل غذا را به‌حداقل برساند.
به‌حداقل رساندن مدت سفر یا مصرف سوخت: یک کسب‌وکار تدارکات ممکن است بخواهد کارایی رانندگان خود را بهبود بخشد و هزینه‌های سوخت خود را کاهش دهد.
کمینه کردن زمان رسیدن به مقصد: عملیات اعزام خدمات ممکن است بخواهد زمان لازم برای رساندن اپراتورها به درخواست کار را کمینه کند.
کاهش هزینه‌ها و بهبود ایمنی: یک کسب‌وکار هم‌پیمایی ممکن است بخواهد مسیری را پیدا کند که هزینه کمتری برای مسافران داشته باشد و به‌دلایل ایمنی از مناطق خاصی اجتناب کند.
برای کسب اطلاعات بیشتر درباره برنامه‌ریزی مسیر بااستفاده از یک کد مسیر، به دریافت یک کد مسیر در Routes API و چندخطی‌های انتقال و کدهای مسیر در Route Optimization API مراجعه کنید.
چرا باید از کد مسیر برای اهداف مسیر استفاده کرد
بااستفاده از کد مسیر از Routes API، Routes Preferred API، یا Route Optimization API، کنترل بیشتری بر مسیر ارائه‌شده دارید:
مسیری را ازقبل برنامه‌ریزی کنید تا Navigation SDK از آن استفاده کند.
بهترین مسیر را برای استفاده Navigation SDK انتخاب کنید. اگر هنگام تولید مسیرها در Routes API، توکن‌های مسیر را درخواست کنید، برای هر مسیر تولیدشده یک توکن مسیر دریافت می‌کنید. سپس می‌توانید هنگام ارسال به Navigation SDK، نشان را برای مسیری که می‌خواهید استفاده کنید انتخاب کنید.
قیمت را ازقبل تخمین بزنید، ازجمله تخمین زمان تخمینی رسیدن و مسافت. اگرچه هزینه و زمان واقعی ممکن است متفاوت باشد، این تخمین فاصله بین هزینه مسیر موردانتظار و واقعی را کاهش می‌دهد.
اهداف پیشرفته‌تری برای مسیر مشخص کنید، مانند مسیریابی سازگار با محیط‌زیست یا کوتاه‌ترین مسیر.
نحوه عملکرد توکن‌های مسیر
می‌توانید از Routes API، Routes Preferred API، یا Route Optimization API برای برنامه‌ریزی مسیر بااستفاده از اهداف مسیر استفاده کنید. می‌توانید یک کد مسیر برگشتی از هرکدام از این میاناهای برنامه‌سازی کاربردی را به کیت توسعه نرم‌افزار ناوبری ارسال کنید تا نحوه مسیریابی خودرو شما را راهنمایی کند.
وقتی که یک توکن مسیر درخواست و استفاده می‌کنید، این اتفاق می‌افتد:
Routes API، Routes Preferred API، یا Route Optimization API یک کد مسیر رمزگذاری‌شده برمی‌گرداند که شامل چندخطی مسیر و اهداف مسیر است.
شما توکن مسیر را به کیت توسعه نرم‌افزار پیمایش ارسال می‌کنید.
کیت توسعه نرم‌افزار ناوبری، ناوبری را در مسیر برنامه‌ریزی‌شده شما شروع می‌کند، حتی اگر مسیر سریع‌تری دردسترس باشد.
درطول سفر، اگر ترافیک یا شرایط جاده تغییر کند، یا اگر خودرو از مسیر برنامه‌ریزی‌شده خارج شود، Navigation SDK مسیر جدیدی را محاسبه می‌کند که از اهداف مسیر و گزینه‌های مسیریابی تنظیم‌شده در کلید مسیر شما پیروی می‌کند.
این فرایند باعث می‌شود مسیر واقعی تا حد امکان به مسیر برنامه‌ریزی‌شده شما نزدیک باشد.
چرا ممکن است مسیر برنامه‌ریزی‌شده دقیقاً دنبال نشود
ناوبری در مسیر برنامه‌ریزی‌شده شما شروع می‌شود، اما مسیر واقعی می‌تواند در شرایطی مانند موارد زیر با آن متفاوت باشد:
- وسیله نقلیه از نقطه شروع برنامه‌ریزی‌شده فاصله می‌گیرد.
- ترافیک یا شرایط جاده درطول سفر تغییر کند.
- خودرو از مسیر برنامه‌ریزی‌شده خارج شود.
این تفاوت‌ها می‌تواند بر مسافت، زمان تخمینی رسیدن، و دیگر ویژگی‌های مهم سفر که برای آن برنامه‌ریزی کرده‌اید تأثیر بگذارد.
برنامه‌ریزی مسیر بااستفاده از کد مسیر
می‌توانید با ایجاد یک توکن مسیر و سپس ارسال آن به Navigation SDK، مسیری را برنامه‌ریزی کنید، همان‌طور که در مراحل زیر توضیح داده شده است:
مرحله ۱: بااستفاده از Routes API، Routes Preferred API، یا Route Optimization API، یک توکن مسیر ایجاد کنید
با یکی از روش‌های زیر یک توکن مسیر درخواست کنید:
Routes API:
computeRoutes. برای اطلاعات بیشتر درباره درخواست کردن توکن مسیر در Routes API، به محاسبه کردن مسیر و دریافت کردن توکن مسیر مراجعه کنید.Routes Preferred API:
computeCustomRoutes. برای اطلاعات بیشتر درباره درخواست کردن توکن مسیر در Routes Preferred API، به برنامه‌ریزی مسیر مراجعه کنید.Route Optimization API:
optimizeToursیاbatchOptimizeTours. برای اطلاعات بیشتر درباره درخواست کردن یک توکن مسیر در Route Optimization API، به چندخطی‌های انتقال و توکن‌های مسیر مراجعه کنید.
درخواست Routes API یا Routes Preferred API خود را راه‌اندازی کنید تا الزامات استفاده از کد مسیر را برآورده کنید:
travelModeرا رویDRIVEیاTWO_WHEELERتنظیم کنید.routingPreferenceرا رویTRAFFIC_AWAREیاTRAFFIC_AWARE_OPTIMALتنظیم کنید.- از
Viaنقطه‌مسیر استفاده نکنید.
مرحله ۲: ارسال کردن توکن مسیر به Navigation SDK
ذخیره کردن کد مسیر: در «کیت توسعه نرم‌افزار پیمایش»، رشته‌ای را برای ذخیره کردن کد مسیر راه‌اندازی کنید. برای مثال:
let routeToken = "route token returned by Routes API"نمونه‌ای از کد مسیر برگردانده‌شده:
{ // Other fields "routeToken": "CqMBCjoKCJQOor5DHcwiEhBon3XpHXFnVvDeWMwd9PpAGgz6wtnFDKIBrAHTARpCApUDSggAAAAACjcrP3gBEAQaTApKChgKDQoCCAERAAAAAACAZkAR3SQGgZUXdUASEggAEAMQBhATEBIYAkIEGgIIBSIYChZ2VEJiWlBPSkk1aU5wUVRzNTV5d0FRKAEiFQBcJuds-Efh-2QZhOMTtUCCxEVL_g", }ژتون مسیر را بااستفاده از روش
setDestinationsWithToken:completionHandler:mapView.navigatorبه «کیت توسعه نرم‌افزار ناوبری» ارسال کنید. «کیت توسعه نرم‌افزار پیمایش» مقصدها و گزینه‌های مسیریابی را از نشانه مسیر دریافت می‌کند، بنابراین نیازی نیست نقاط‌مسیر را ارسال کنید.حالت سفر تنظیم‌شده در برنامه‌تان، مثل
mapView.travelMode، باید یکی از مقادیر زیر باشد:.driving(GMSNavigationTravelModeDriving): رانندگی. این مقدار پیش‌فرض است، بنابراین اکثر برنامه‌ها نیازی به تغییر آن ندارند.-
.twoWheeler(GMSNavigationTravelModeTwoWheeler): موتورسیکلت.
هر حالت سفر دیگری باعث می‌شود درخواست با
.travelModeUnsupported(GMSRouteStatusTravelModeUnsupported) ناموفق شود. با هریک از مقادیر پشتیبانی‌شده، مسیر از حالت سفر در کد مسیر شما استفاده می‌کند. برای مثال، اگر برنامه شما از رانندگی استفاده می‌کند و کد مسیر شما برای مسیر موتورسیکلت است، Navigation SDK مسیر موتورسیکلت را ارائه می‌دهد. برای تأیید اینکه مسیر از کدام حالت سفر استفاده می‌کند،resolvedParameters.travelModeرا بررسی کنید. برای اطلاعات بیشتر، به گزینه‌های مسیریابی حل‌شده مراجعه کنید.وضعیت مسیر را در گرداننده تکمیل بررسی کنید. وقتی کیت توسعه نرم‌افزار ناوبری محاسبه مسیر را به‌پایان می‌رساند،
GMSNavigationRouteDescriptionرا به گرداننده تکمیل شما ارسال می‌کند. اگر مسیری از مکان خودرو به مقصدهای موجود در کد مسیر شما پیدا کند،routeStatusشرح مسیر.OK(GMSRouteStatusOK) است و می‌توانید راهنمایی را شروع کنید. درغیراین‌صورت، گرداننده تکمیل شما نیزNSErrorدریافت می‌کند که شکست را شرح می‌دهد. برای مثال:mapView.navigator?.setDestinationsWithToken(routeToken) { [weak self] routeDescription, error in if routeDescription?.routeStatus == .OK { self?.mapView.navigator?.isGuidanceActive = true } }
بررسی کنید که آیا Navigation SDK کد مسیر شما را اعمال کرده است یا نه
وضعیت مسیر .OK یعنی Navigation SDK مسیری پیدا کرده است،
اما لزوماً مسیر برنامه‌ریزی‌شده شما نیست. برای بررسی اینکه آیا مسیر با مسیر برنامه‌ریزی‌شده شما مطابقت دارد یا نه، این مراحل را در گرداننده تکمیل دنبال کنید:
تأیید کنید که
routeStatusشرح مسیر.OKاست. «کیت توسعه نرم‌افزار ناوبری» جزئیات کد مسیر را فقط زمانی ارائه می‌دهد که مسیری پیدا کند. برای اطلاعات بیشتر، به مرحله ۲ مراجعه کنید.routeTokenExecutionDetailsشرح مسیر را دریافت کنید، شیئی که با پروتکلGMSNavigationRouteTokenExecutionDetailsمطابقت دارد. اگر سرور جزئیات توکن مسیر را ارائه ندهد، این ویژگیnilاست.ویژگی
tokenExecutionStatusجزئیات اجرا را بررسی کنید. اگر.tokenSuccessfullyAppliedباشد، مسیر با مسیر برنامه‌ریزی‌شده شما مطابقت دارد. هر وضعیت دیگری به این معنی است که مسیر ممکن است با مسیر برنامه‌ریزی‌شده شما متفاوت باشد. برای اطلاعات بیشتر درباره هر وضعیت، به مقادیر وضعیت اجرای توکن مراجعه کنید.اختیاری: اگر وضعیت
.tokenSuccessfullyAppliedاست، ویژگیresolvedParametersهمان جزئیات اجرا را بررسی کنید تا ببینید مسیر از کدام گزینه‌های مسیریابی استفاده می‌کند، مثلاً اینکه آیا از عوارض اجتناب می‌کند یا نه. برای اطلاعات بیشتر، به گزینه‌های مسیریابی حل‌شده مراجعه کنید.
مقادیر وضعیت اجرای کد
اگر routeStatus .OK باشد، می‌توانید راهنمایی را با هر وضعیت اجرای توکنی شروع کنید. وضعیت به شما می‌گوید که آیا مسیر از مسیر برنامه‌ریزی‌شده شما پیروی می‌کند یا نه.
| وضعیت | مسیر برنامه‌ریزی‌شده شما را دنبال می‌کند | شرح |
|---|---|---|
.tokenSuccessfullyApplied |
بله | کیت توسعه نرم‌افزار پیمایش، کد مسیر شما را اعمال کرد. |
.tokenAppliedWithLocationMismatch |
نه لزوماً | «کیت توسعه نرم‌افزار ناوبری» نتوانست مسیر برنامه‌ریزی‌شده شما را بازسازی کند و دستگاه بیش‌از ۲۵ متر از مبدأ در کد مسیر شما فاصله داشت. مسیر همچنان از مقصدها و گزینه‌های مسیریابی از کد مسیر شما استفاده می‌کند. |
.tokenIgnoredOther |
نه لزوماً | کیت توسعه نرم‌افزار ناوبری به‌دلیل دیگری نتوانست مسیر برنامه‌ریزی‌شده شما را بازسازی کند، مثلاً به‌دلیل بسته بودن جاده‌ای در مسیر برنامه‌ریزی‌شده شما. مسیر همچنان از مقصدها و گزینه‌های مسیریابی از کد مسیر شما استفاده می‌کند. |
.noTokenProvided |
نامربوط | درخواست مسیر شامل کد مسیر نبود. |
.unknown |
نامشخص | وضعیت نامشخص است. |
اگر مسیر لزوماً از مسیر برنامه‌ریزی‌شده شما پیروی نمی‌کند و مسیر دقیق اهمیت دارد، برای مثال، چون از آن برای محاسبه قیمت استفاده کرده‌اید، وضعیت را ثبت کنید یا از مکان فعلی خودرو درخواست یک توکن مسیر جدید کنید.
گزینه‌های مسیریابی حل‌شده
resolvedParameters شیئی است که با پروتکل
GMSNavigationRouteTokenResolvedParameters
مطابقت دارد، یا اگر گزینه‌های مسیریابی دردسترس نباشد، nil است. این ویژگی‌ها را دارد:
travelMode: حالت سفری که مسیر استفاده می‌کند، مثل.driving(GMSNavigationTravelModeDriving). «کیت توسعه نرم‌افزار ناوبری» همچنین.drivingرا زمانی گزارش می‌کند که مسیر از حالت سفری استفاده می‌کند که مقدار منطبقی ندارد، یا زمانی که حالت سفر دردسترس نیست.avoidTolls: اینکه مسیر از عوارضی‌ها اجتناب می‌کند یا نه.avoidHighways: اینکه مسیر از بزرگراه‌ها اجتناب می‌کند یا نه.avoidFerries: اینکه مسیر از کشتی اجتناب می‌کند یا نه.avoidTunnels: اینکه آیا مسیر به‌گونه‌ای محاسبه شده است که درصورت امکان از تونل‌ها اجتناب شود.avoidVignettes: کشورهایی که مسیر برای اجتناب از برچسب عوارض درصورت امکان محاسبه شده است، به‌صورت کدهای منطقه دوحرفی Unicode CLDR، مانندCHبرای سوئیس.rerouteStrategy: استراتژی‌ای که پسایان مسیریابی برای محاسبه مسیرهای جدید درطول سفر استفاده می‌کند. استراتژی‌ها شامل.bestBasedOnTokenParameters(GMSNavigationRerouteStrategyBestBasedOnTokenParameters) است که از پارامترهای مسیریابی در توکن مسیر شما برای محاسبه مسیرهای جدید استفاده می‌کند.
اگر وضعیت اجرای کد .tokenSuccessfullyApplied نباشد،
«کیت توسعه نرم‌افزار ناوبری» فقط travelMode، avoidTolls،
avoidHighways، و avoidFerries را گزارش می‌کند. سایر ویژگی‌ها مقادیر پیش‌فرض خود را دارند، حتی اگر هنگام درخواست کردن توکن مسیر، خواسته باشید از تونل‌ها یا برچسب‌های عوارض اجتناب شود: avoidTunnels برابر با false (NO) است، avoidVignettes خالی است، و rerouteStrategy برابر با .unknown (GMSNavigationRerouteStrategyUnknown) است.
مثال
نمونه کد زیر نشان می‌دهد که چگونه بااستفاده از یک کد مسیر، مسیری را برنامه‌ریزی کنید، بررسی کنید که آیا Navigation SDK کد را اعمال کرده است یا نه، و راهنمایی را شروع کنید.
Swift
let routeToken = "route token returned by Routes API"
mapView.navigator?.setDestinationsWithToken(routeToken) { [weak self] routeDescription, error in
// Check whether the Navigation SDK found a route.
guard routeDescription?.routeStatus == .OK else {
print("Route error: \(error?.localizedDescription ?? "unknown")")
return
}
// Check whether the Navigation SDK applied the route token.
if let executionDetails = routeDescription?.routeTokenExecutionDetails {
if executionDetails.tokenExecutionStatus != .tokenSuccessfullyApplied {
print("The route might differ from your planned route.")
}
} else {
print("Route token details aren't available.")
}
self?.mapView.navigator?.isGuidanceActive = true
}
آبجکتیو-سی
NSString *routeToken = @"route token returned by Routes API";
[mapView.navigator setDestinationsWithToken:routeToken
completionHandler:^(id<GMSNavigationRouteDescription> _Nullable routeDescription,
NSError *_Nullable error) {
// Check whether the Navigation SDK found a route.
if (routeDescription.routeStatus != GMSRouteStatusOK) {
NSLog(@"Route error: %@", error.localizedDescription);
return;
}
// Check whether the Navigation SDK applied the route token.
id<GMSNavigationRouteTokenExecutionDetails> executionDetails =
routeDescription.routeTokenExecutionDetails;
if (executionDetails == nil) {
NSLog(@"Route token details aren't available.");
} else if (executionDetails.tokenExecutionStatus !=
GMSNavigationRouteTokenExecutionStatusTokenSuccessfullyApplied) {
NSLog(@"The route might differ from your planned route.");
}
mapView.navigator.guidanceActive = YES;
}];
سناریوهای چندایستگاهی
می‌توانید حداکثر ۲۵ نقطه‌مسیر پیکربندی کنید.
کیت توسعه نرم‌افزار پیمایش به‌طور خودکار به مقصد بعدی نمی‌رود. وقتی خودرو به نقطه‌مسیر رسید،
continueToNextDestinationWithCompletion:
را فراخوانی کنید تا بخش بعدی سفر شروع شود. این امر برای توکن‌های مسیر که نقطه‌مسیرهای میانی دارند نیز اعمال می‌شود. وقتی به مقصد بعدی می‌روید،
Navigation SDK به‌جای برنامه‌ریزی مسیر جدید،
همچنان مسیر را از توکن مسیر شما دنبال می‌کند.
نحوه تعامل نشان‌های مسیر و کیت توسعه نرم‌افزار پیمایش
نحوه مدیریت مسیر برنامه‌ریزی‌شده شما توسط Navigation SDK در اینجا توضیح داده شده است:
هر مقصد تنظیم‌شده قبلی را لغو می‌کند.
از مکان شروع خودرو استفاده می‌کند.
با شرایط جاده و ترافیک تنظیم می‌شود. ببینید چرا ممکن است مسیر برنامه‌ریزی‌شده دقیقاً دنبال نشود.
از گزینه‌های مسیریابی تنظیم‌شده در کد مسیر شما استفاده می‌کند و از تنظیمات زیر در برنامه‌تان استفاده نمی‌کند، ازجمله وقتی که مسیر جدیدی را درطول سفر محاسبه می‌کند:
avoidsHighwaysavoidsTollsavoidsFerrieslicensePlateRestriction- حالت سفر تنظیم‌شده در برنامه‌تان
هنگام محاسبه یا تنظیم مسیر، از این تنظیمات پیروی می‌کند:
- اهداف مسیر از توکن مسیر شما، مانند مسیریابی بوم‌سازگار یا کوتاه‌ترین مسیر. اگر «کیت توسعه نرم‌افزار ناوبری» مجبور به تنظیم مسیر باشد، از اهداف مسیری که هنگام درخواست کردن توکن مسیر مشخص کرده‌اید استفاده می‌کند.
- گزینه‌های مربوط به نقطه‌مسیر از شناسه مسیر شما، مانند اولویت کنار جاده.