Contact Sales Console Login
Document Navigation SDK for iOS Guides Navigation Basics Basic Features

Basic Features

Initialize an AMapNaviCompositeManager instance to launch the navigation component.

// Initialize
self.compositeManager = [[AMapNaviCompositeManager alloc] init];
// Set the delegate to use AMapNaviCompositeManagerDelegate callbacks
// (e.g., custom voice, real-time location updates)
self.compositeManager.delegate = self;
// Present the route planning view controller.
// Pass nil for options when no start/destination points are provided.
[self.compositeManager presentRoutePlanViewControllerWithOptions:nil];

Start Navigation with Start and Destination Points

Set the start point, waypoints (up to three), and destination point to launch the navigation component. Each point can be described using coordinates, a name, or an AMAP POI ID. The parameter rules are as follows:

1. Coordinates are required.

2. Name is optional and used only for display. If set, the provided name is shown. If omitted, default names such as "Destination" or "Waypoint 1" are used.

3. AMAP POI ID is optional but strongly recommended, as it helps reduce detours. When a POI ID is provided, the component performs a precise POI search. The retrieved POI details are used for route calculation and override the provided coordinates and name.

4. If no start point is set, the user's current location is used as the start point, and the displayed name is "My Location".

Example: Pass Destination Coordinates and Name (No POI ID)

// Navigation component configuration class (since 5.2.0)
AMapNaviCompositeUserConfig *config = [[AMapNaviCompositeUserConfig alloc] init];
// Set the destination coordinates
[config setRoutePlanPOIType:AMapNaviRoutePlanPOITypeEnd
                  location:[AMapNaviPoint locationWithLatitude:39.918058 longitude:116.397026]
                     name:@"故宫"
                    POIId:nil];
// Launch
[self.compositeManager presentRoutePlanViewControllerWithOptions:config];

Example: Pass Start, Waypoint, and Destination Points with POI IDs

// Navigation component configuration class (since 5.2.0)
AMapNaviCompositeUserConfig *config = [[AMapNaviCompositeUserConfig alloc] init];
// Set the start point with a POI ID
[config setRoutePlanPOIType:AMapNaviRoutePlanPOITypeStart
                  location:[AMapNaviPoint locationWithLatitude:40.080525 longitude:116.603039]
                     name:@"北京首都机场"
                    POIId:@"B000A28DAE"];
// Set a waypoint with a POI ID
[config setRoutePlanPOIType:AMapNaviRoutePlanPOITypeWay
                  location:[AMapNaviPoint locationWithLatitude:39.941823 longitude:116.426319]
                     name:@"北京大学"
                    POIId:@"B000A816R6"];
// Set the destination with a POI ID
[config setRoutePlanPOIType:AMapNaviRoutePlanPOITypeEnd
                  location:[AMapNaviPoint locationWithLatitude:39.918058 longitude:116.397026]
                     name:@"故宫"
                    POIId:@"B000A8UIN8"];
// Launch
[self.compositeManager presentRoutePlanViewControllerWithOptions:config];

Dismiss the Navigation Component

After the navigation component is presented, users can tap the back button in the top-left corner of the route planning page to dismiss it. Developers can also programmatically dismiss the component using the following method.

/**
 * @brief Dismisses the navigation component page.
 *        Note: This function involves UI operations and must be called on the main thread.
 *        (since 5.5.0)
 * @param animated Whether to animate the dismissal.
 */
- (void)dismissWithAnimated:(BOOL)animated;

Callback Methods

The <AMapNaviCompositeManagerDelegate> protocol provides a set of callback methods.

/**
 * @brief Called when an error occurs.
 * @param compositeManager The navigation component manager.
 * @param error The error information.
 */
- (void)compositeManager:(AMapNaviCompositeManager *_Nonnull)compositeManager
                   error:(NSError *_Nonnull)error;

/**
 * @brief Called when route calculation succeeds. (since 5.5.0)
 * @param compositeManager The navigation component manager.
 * @param type The route planning type. See AMapNaviRoutePlanType.
 */
- (void)compositeManager:(AMapNaviCompositeManager *_Nonnull)compositeManager
 onCalculateRouteSuccessWithType:(AMapNaviRoutePlanType)type;

/**
 * @brief Called when route calculation fails.
 *        This includes failures from the route planning page and re-routing during navigation.
 * @param compositeManager The navigation component manager.
 * @param error The error information. See AMapNaviCalcRouteState for error codes.
 */
- (void)compositeManager:(AMapNaviCompositeManager *_Nonnull)compositeManager
 onCalculateRouteFailure:(NSError *_Nonnull)error;

/**
 * @brief Called when navigation starts.
 * @param compositeManager The navigation component manager.
 * @param naviMode The navigation mode. See AMapNaviMode.
 */
- (void)compositeManager:(AMapNaviCompositeManager *_Nonnull)compositeManager
             didStartNavi:(AMapNaviMode)naviMode;

/**
 * @brief Called when the current location is updated.
 *        This callback is triggered whenever the location changes, regardless of navigation state.
 * @param compositeManager The navigation component manager.
 * @param naviLocation The current location information. See AMapNaviLocation.
 */
- (void)compositeManager:(AMapNaviCompositeManager *_Nonnull)compositeManager
      updateNaviLocation:(AMapNaviLocation *_Nullable)naviLocation;

/**
 * @brief Called when the day/night mode changes on the driving navigation screen. (since 6.7.0)
 * @param compositeManager The navigation component manager.
 * @param showStandardNightType YES for night mode, NO for day mode.
 */
- (void)compositeManager:(AMapNaviCompositeManager *_Nonnull)compositeManager
   didChangeDayNightType:(BOOL)showStandardNightType;

/**
 * @brief Called when navigation reaches the destination.
 * @param compositeManager The navigation component manager.
 * @param naviMode The navigation mode. See AMapNaviMode.
 */
- (void)compositeManager:(AMapNaviCompositeManager *_Nonnull)compositeManager
   didArrivedDestination:(AMapNaviMode)naviMode;

/**
 * @brief Called when the user navigates back or dismisses the navigation component. (since 5.5.0)
 * @param compositeManager The navigation component manager.
 * @param backwardActionType The type of backward action. See AMapNaviCompositeVCBackwardActionType.
 */
- (void)compositeManager:(AMapNaviCompositeManager *_Nonnull)compositeManager
       didBackwardAction:(AMapNaviCompositeVCBackwardActionType)backwardActionType;

/**
 * @brief Called when the navigation component is entered or the driving strategy changes. (since 6.1.0)
 * @param compositeManager The navigation component manager.
 * @param driveStrategy The driving strategy. See AMapNaviDrivingStrategy.
 */
- (void)compositeManager:(AMapNaviCompositeManager *_Nonnull)compositeManager
  onDriveStrategyChanged:(AMapNaviDrivingStrategy)driveStrategy;

/**
 * @brief Called when navigation arrives at a waypoint. (since 6.1.0)
 * @param compositeManager The navigation component manager.
 * @param wayPointIndex The index of the arrived waypoint, starting from 0.
 *        Note: If the route is recalculated (e.g., due to deviation or manual refresh),
 *        the wayPointIndex resets to 0.
 */
- (void)compositeManager:(AMapNaviCompositeManager *_Nonnull)compositeManager
         onArrivedWayPoint:(int)wayPointIndex;

/**
 * @brief Called when the map view mode (day/night) setting changes on the navigation screen. (since 7.1.0)
 * @param type See AMapNaviViewMapModeType.
 */
- (void)compositeManagerDidChangeMapViewModeType:(AMapNaviViewMapModeType)type;

/**
 * @brief Called when the voice broadcast mode setting changes. (since 7.1.0)
 * @param type See AMapNaviCompositeBroadcastType.
 */
- (void)compositeManagerDidChangeBroadcastType:(AMapNaviCompositeBroadcastType)type;

/**
 * @brief Called when the tracking mode setting changes on the navigation screen. (since 7.1.0)
 * @param mode See AMapNaviViewTrackingMode.
 */
- (void)compositeManagerDidChangeTrackingMode:(AMapNaviViewTrackingMode)mode;

/**
 * @brief Called when the auto-zoom map level setting changes. (since 7.1.0)
 * @param autoZoomMapLevel Whether the map automatically zooms to anticipate the next navigation action in locked mode.
 */
- (void)compositeManagerDidChangeAutoZoomMapLevel:(BOOL)autoZoomMapLevel;

Custom Voice Synthesis Callbacks

The following three callbacks are only required if you need to implement custom voice synthesis. If you prefer to use the built-in voice synthesis (iOS system TTS), you do not need to implement them.

/**
 * @brief The SDK needs to retrieve in real time whether navigation audio broadcasting is currently
 * in progress, so that the SDK can internally control the timing of the 
 * "navigation broadcast information callback" to avoid the situation where the next 
 * sentence interrupts the previous one. If you need to customize the 
 * "navigation voice broadcast" feature, this delegate must be implemented.
 * @param compositeManager The navigation composite manager class.
 * @return Returns whether navigation audio broadcasting is currently in progress.
 * If this always returns YES, the "navigation broadcast information callback" will never
 * be triggered. If this always returns NO, sentence interruptions will occur. 
 * Please return the appropriate value based on the actual situation.
 */
- (BOOL)compositeManagerIsNaviSoundPlaying:(AMapNaviCompositeManager *_Nonnull)compositeManager;

/**
 * @brief Callback function for navigation broadcast information. This callback must be
 * used in conjunction with compositeManagerIsNaviSoundPlaying:. If you need to customize
 * the "navigation voice broadcast" feature, this delegate must be implemented.
 * @param compositeManager The navigation composite manager class.
 * @param soundString The text to be broadcast.
 * @param soundStringType The broadcast type. Refer to AMapNaviSoundType.
 * Note: Since 6.0.0, AMapNaviSoundType only returns AMapNaviSoundTypeDefault.
 */
- (void)compositeManager:(AMapNaviCompositeManager *_Nonnull)compositeManager 
      playNaviSoundString:(NSString *_Nullable)soundString 
         soundStringType:(AMapNaviSoundType)soundStringType;

/**
 * @brief Callback function for stopping navigation voice broadcast. When the navigation
 * SDK needs to stop external voice broadcasting, this method will be called. If you need
 * to customize the "navigation voice broadcast" feature, this delegate must be implemented.
 * @param compositeManager The navigation composite manager class.
 */
- (void)compositeManagerStopPlayNaviSound:(AMapNaviCompositeManager *_Nonnull)compositeManager;

Important: Ensure that -compositeManagerIsNaviSoundPlaying: returns the correct boolean value. If it always returns YES, the SDK assumes that external playback is ongoing, and -compositeManager:playNaviSoundString:soundStringType will not be triggered, resulting in no speech output. If it always returns NO, speech output may occur too frequently, causing sentences to be interrupted. Therefore, return the appropriate value based on the actual playback state. For detailed usage, refer to the SpeechSynthesizer.m code in the official demo.

On this page