از این راهنما برای فعال کردن برنامه خود جهت گوش دادن و پاسخ دادن به رویدادهای متنوعی که هنگام پیمایش کاربر در طول یک مسیر تغییر میکنند، استفاده کنید. این راهنما تعریف یک مسیر را پوشش نمیدهد، و فقط به رویدادهایی که در طول یک مسیر رخ میدهند، پاسخ میدهد.
نمای کلی
 کیت توسعه نرمافزار ناوبری (Navigation SDK) برای iOS، شنوندههایی (listeners) مرتبط با موقعیت مکانی کاربر و شرایط مسیر و دادههای مهم زمان و مسافت را در اختیار شما قرار میدهد. در کنترلر نمای نقشه، برنامه شما باید پروتکلهای مربوط به این شنوندهها را اتخاذ کند: GMSRoadSnappedLocationProviderListener و GMSNavigatorListener .
این لیست متدهای شنونده (listener) موجود برای رویدادهای ناوبری (navigation events) را نشان میدهد:
-  
GMSNavigatorListener.didArriveAtWaypoint، زمانی که به مقصد رسیده میشود، فعال میشود. -  
GMSNavigatorListener.navigatorDidChangeRoute، زمانی که مسیر تغییر کند، فعال میشود. -  
GMSNavigatorListener.didUpdateRemainingTime، با تغییر زمان تا مقصد بعدی، در حالی که راهنمایی فعال است، مکرراً فراخوانی میشود. -  
GMSNavigatorListener.didUpdateRemainingDistance، که به طور مکرر با تغییر فاصله تا مقصد بعدی فراخوانی میشود، در حالی که راهنمایی فعال است. -  
GMSNavigatorListener.didUpdateDelayCategory، زمانی فراخوانی میشود که دستهبندی تأخیر به مقصد بعدی تغییر کند، در حالی که راهنمایی فعال است. -  
GMSNavigatorListener.didChangeSuggestedLightingMode، زمانی فعال میشود که شرایط نوری تخمینی بهروزرسانی شوند. برای مثال، وقتی شب در مکان فعلی کاربر فرا میرسد، نور تغییر میکند. -  
GMSNavigatorListener.didUpdateSpeedingPercentage، زمانی فعال میشود که راننده از سرعت مجاز تجاوز کند. -  
GMSRoadSnappedLocationProviderListener.didUpdateLocation، با تغییر موقعیت مکانی کاربر، مکرراً فراخوانی میشود. 
کد را ببینید
اعلام انطباق با پروتکلهای مورد نیاز
قبل از پیادهسازی متدهای ناوبری، view controller باید پروتکلهای زیر را بپذیرد:
سویفت
class ViewController: UIViewController, GMSNavigatorListener,
GMSRoadSnappedLocationProviderListener {
هدف-سی
@interface ViewController () <GMSNavigatorListener,
GMSRoadSnappedLocationProviderListener>
@end
 پس از تطبیق پروتکلهای ناوبری، شنوندهها را برای کنترلر نما تنظیم کنید. برای مثال، میتوانید کد زیر را به متد viewDidLoad() اضافه کنید. 
سویفت
mapView.navigator?.add(self) mapView.roadSnappedLocationProvider?.add(self)
هدف-سی
[_mapView.navigator addListener:self]; [_mapView.roadSnappedLocationProvider
addListener:self];
دریافت یا متوقف کردن بهروزرسانیهای موقعیت مکانی
بهروزرسانیهای موقعیت مکانی برای نمایش پیشرفت کاربر روی نقشه ضروری هستند.
 نمونه location ، ویژگیهای زیر را در معرض نمایش قرار میدهد:
| ملک موقعیت مکانی | توضیحات | 
|---|---|
| ارتفاع | ارتفاع فعلی. | 
| مختصات.عرض جغرافیایی | مختصات عرض جغرافیایی فعلی ثبت شده توسط جاده. | 
| مختصات.طول جغرافیایی | مختصات طول جغرافیایی فعلی که توسط جاده ثبت شده است. | 
| دوره | تحمل جریان بر حسب درجه. | 
| سرعت | سرعت فعلی. | 
| مهر زمانی | تاریخ/زمان مطالعهی فعلی. | 
 برای دریافت بهروزرسانیهای مداوم موقعیت مکانی، mapView.roadSnappedLocationProvider.startUpdatingLocation را فراخوانی کنید و GMSRoadSnappedLocationProviderListener برای مدیریت رویداد didUpdateLocation استفاده کنید.
 مثال زیر فراخوانی startUpdatingLocation را نشان میدهد: 
سویفت
mapView.roadSnappedLocationProvider.startUpdatingLocation()
هدف-سی
[_mapView.roadSnappedLocationProvider startUpdatingLocation];
 کد زیر یک GMSRoadSnappedLocationProviderListener ایجاد میکند که رویداد didUpdateLocation را مدیریت میکند. 
سویفت
func locationProvider(_ locationProvider: GMSRoadSnappedLocationProvider,
didUpdate location: CLLocation) { print("Location: \(location.description)") }
هدف-سی
-   (void)locationProvider:(GMSRoadSnappedLocationProvider *)locationProvider
    didUpdateLocation:(CLLocation *)location { NSLog(@"Location: %@",
    location.description); }
 برای دریافت بهروزرسانیهای موقعیت مکانی هنگامی که برنامه در پسزمینه است، allowsBackgroundLocationUpdates روی true تنظیم کنید: 
سویفت
mapView.roadSnappedLocationProvider.allowsBackgroundLocationUpdates = true
هدف-سی
 _mapView.roadSnappedLocationProvider.allowsBackgroundLocationUpdates = YES;
تشخیص رویدادهای ورود
 برنامه شما از رویداد didArriveAtWaypoint برای تشخیص زمان رسیدن به مقصد استفاده میکند. میتوانید با فراخوانی continueToNextDestination() و سپس فعال کردن مجدد راهنمایی، راهنمایی را از سر بگیرید و به نقطه مسیر بعدی بروید. برنامه شما باید پس از فراخوانی continueToNextDestination() راهنمایی را دوباره فعال کند.
 پس از اینکه برنامه تابع continueToNextDestination فراخوانی میکند، ناوبر دیگر اطلاعاتی در مورد مقصد قبلی ندارد. اگر میخواهید اطلاعات مربوط به یک بخش از مسیر را تجزیه و تحلیل کنید، باید قبل از فراخوانی continueToNextDestination() این اطلاعات را از ناوبر بازیابی کنید.
 مثال کد زیر روشی را برای مدیریت رویداد didArriveAtWaypoint نشان میدهد: 
سویفت
func navigator(_ navigator: GMSNavigator, didArriveAt waypoint:
GMSNavigationWaypoint) { print("You have arrived at: \(waypoint.title)")
mapView.navigator?.continueToNextDestination()
mapView.navigator?.isGuidanceActive = true }
هدف-سی
-   (void)navigator:(GMSNavigator *)navigator
    didArriveAtWaypoint:(GMSNavigationWaypoint *)waypoint { NSLog(@"You have
    arrived at: %@", waypoint.title); [_mapView.navigator
    continueToNextDestination]; _mapView.navigator.guidanceActive = YES; }
دریافت بهروزرسانیهای تغییر مسیر
 برای دریافت اعلان هنگام تغییر مسیر، متدی برای مدیریت رویداد navigatorDidChangeRoute ایجاد کنید. میتوانید با استفاده از ویژگیهای routeLegs و currentRouteLeg از GMSNavigator به مسیر جدید دسترسی پیدا کنید. 
سویفت
func navigatorDidChangeRoute(_ navigator: GMSNavigator) { print("The route has
changed.") }
هدف-سی
-   (void)navigatorDidChangeRoute:(GMSNavigator *)navigator { NSLog(@"The route
    has changed."); }
دریافت بهروزرسانیهای زمان رسیدن به مقصد
 برای دریافت مداوم زمان تا بهروزرسانیهای مقصد، متدی برای مدیریت رویداد didUpdateRemainingTime ایجاد کنید. پارامتر time ، زمان تخمینی تا رسیدن به مقصد بعدی را بر حسب ثانیه ارائه میدهد. 
سویفت
func navigator(_ navigator: GMSNavigator, didUpdateRemainingTime time:
TimeInterval) { print("Time to next destination: \(time)") }
هدف-سی
-   (void)navigator:(GMSNavigator *)navigator
    didUpdateRemainingTime:(NSTimeInterval)time { NSLog(@"Time to next
    destination: %f", time); }
 برای تنظیم حداقل تغییر در زمان تخمینی تا مقصد بعدی، ویژگی timeUpdateThreshold را در GMSNavigator تنظیم کنید. مقدار آن بر حسب ثانیه تعیین میشود. اگر این ویژگی تنظیم نشود، سرویسها از مقدار پیشفرض یک ثانیه استفاده میکنند. 
سویفت
navigator?.timeUpdateThreshold = 10
هدف-سی
navigator.timeUpdateThreshold = 10;
دریافت بهروزرسانیهای فاصله تا مقصد
 برای دریافت بهروزرسانیهای مداوم فاصله تا مقصد، متدی برای مدیریت رویداد didUpdateRemainingDistance ایجاد کنید. پارامتر distance ، فاصله تخمینی تا مقصد بعدی را بر حسب متر ارائه میدهد. 
سویفت
func navigator(_ navigator: GMSNavigator, didUpdateRemainingDistance distance:
CLLocationDistance) { let miles = distance * 0.00062137 print("Distance to next
destination: \(miles) miles.") }
هدف-سی
-   (void)navigator:(GMSNavigator *)navigator
    didUpdateRemainingDistance:(CLLocationDistance)distance { double miles =
    distance * 0.00062137; NSLog(@"%@", [NSString stringWithFormat:@"Distance to
    next destination: %.2f.", miles]); }
 برای تنظیم حداقل تغییر در فاصله تخمینی تا مقصد بعدی، ویژگی distanceUpdateThreshold را در GMSNavigator تنظیم کنید (مقدار بر حسب متر مشخص شده است). اگر این ویژگی تنظیم نشود، سرویسها از مقدار پیشفرض یک متر استفاده میکنند. 
سویفت
navigator?.distanceUpdateThreshold = 100
هدف-سی
navigator.distanceUpdateThreshold = 100;
دریافت بهروزرسانیهای ترافیک
 برای دریافت بهروزرسانیهای مداوم جریان ترافیک برای مسیر باقیمانده، متدی برای مدیریت رویداد didUpdateDelayCategory ایجاد کنید. فراخوانی delayCategoryToNextDestination GMSNavigationDelayCategory را برمیگرداند که مقداری از 0 تا 3 را ارائه میدهد. بهروزرسانیهای دستهبندی بر اساس موقعیت فعلی کاربر برنامه انجام میشود. اگر دادههای ترافیک در دسترس نباشد، GMSNavigationDelayCategory مقدار 0 را برمیگرداند. اعداد 1 تا 3 نشاندهنده افزایش جریان از سبک به سنگین هستند. 
سویفت
func navigator(_ navigator: GMSNavigator, didUpdate delayCategory:
GMSNavigationDelayCategory) { print("Traffic flow to next destination:
\(delayCategory)") }
هدف-سی
-   (void)navigator:(GMSNavigator *)navigator
    didUpdateDelayCategory:(GMSNavigationDelayCategory)delayCategory {
    NSLog(@"Traffic flow to next destination: %ld", (long)delayCategory); }
 ویژگی GMSNavigationDelayCategory سطوح تأخیر زیر را نشان میدهد:
| دسته بندی تاخیر | توضیحات | 
|---|---|
| GMSNavigationDelayدستهبندیNoData | ۰ - در دسترس نیست، دادهای برای ترافیک وجود ندارد یا: | 
| مسیر. | |
| GMSNavigationDelayدستهبندیHeavy | ۱ - سنگین. | 
| GMSناوبریتاخیررده متوسط | ۲ - متوسط. | 
| GMSNavigationDelayCategoryLight | ۳ - نور. | 
دریافت بهروزرسانیهای سرعت
 برای دریافت بهروزرسانیها هنگامی که یک راننده از حد مجاز سرعت عبور میکند، متدی برای مدیریت رویداد didUpdateSpeedingPercentage ایجاد کنید. 
سویفت
// Listener to handle speeding events. func navigator( _ navigator:
GMSNavigator, didUpdateSpeedingPercentage percentageAboveLimit: CGFloat ) {
print("Speed is \(percentageAboveLimit) above the limit.") }
هدف-سی
// Listener to handle speeding events. - (void)navigator:(GMSNavigator
*)navigator didUpdateSpeedingPercentage:(CGFloat)percentageAboveLimit {
NSLog(@"Speed is %f percent above the limit.", percentageAboveLimit); }
تغییر حالت روشنایی پیشنهادی
 برای دریافت بهروزرسانیها برای تغییرات تخمینی در روشنایی، متدی برای مدیریت رویداد didChangeSuggestedLightingMode ایجاد کنید. 
سویفت
// Define a listener for suggested changes to lighting mode. func navigator(_
navigator: GMSNavigator, didChangeSuggestedLightingMode lightingMode:
GMSNavigationLightingMode) { print("Suggested lighting mode has changed:
\(String(describing: lightingMode))")
 // Make the suggested change. mapView.lightingMode = lightingMode }
هدف-سی
// Define a listener for suggested changes to lighting mode.
-(void)navigator:(GMSNavigator *)navigator didChangeSuggestedLightingMode:
(GMSNavigationLightingMode)lightingMode { NSLog(@"Suggested lighting mode has
changed: %ld", (long)lightingMode);
 // Make the suggested change. _mapView.lightingMode = lightingMode; }