Installation

Join the Mapbox Developers Discord Communityarrow-right

A newer version of the Navigation SDK is available

This page uses v1.4.2 of the Mapbox Navigation SDK. A newer version of the SDK is available. Learn about the latest version, v2.18.1, in the Navigation SDK documentation.

Before starting to develop your application with the Navigation SDK, you'll need to configure your credentials and add the SDK as a dependency.

Configure credentials

To download and install the iOS SDK, follow the steps below. Start by logging into your Mapbox account, then create and configure a secret access token, and lastly add your public access token to your Info.plist.

Step 1: Log in/Sign up for a Mapbox account

If you haven't done so already, sign up for a Mapbox account and log into it.

You can sign up or sign in by clicking the buttons in the top right corner of your browser.

This account will allow you to create tokens and will create a default public token for you upon creation.

Step 2: Create a secret token

A secret token can enable access to various products/services at Mapbox, including the ability to download an SDK. To allow download access to an SDK, follow these steps:

1. From your account's tokens page, click the Create a token button.
2. From the token creation page, give your token a name and make sure the box next to the Downloads:Read scope is checked.
3. Click the Create token button at the bottom of the page to create your token.
4. The token you've created is a secret token, which means you will only have one opportunity to copy it somewhere secure.

Protect secret access tokens

Store secret tokens in secure a location, outside of your project folder to make sure unauthorized users cannot find it.

Step 3: Configure your secret token

To use your secret token, you will need to store it in a .netrc file in your home directory (not your project folder). This approach helps avoid accidentally exposing your secret token by keeping it out of your application's source code.

To create a .netrc file follow these steps:

Step 3-1: Check if you have already created a .netrc file on your computer.

1. Go to your home directory.
2. Type file .netrc into your terminal and see if anything returns.
3. If you have a .netrc file already, skip step 3-2.

Step 3-2: Create the .netrc file.

1. Open up your terminal in your home directory.
2. Type touch .netrc.

Step 3-3: Open the .netrc file.

• Type open .netrc from the same terminal window from Step 3-2

Step 3-4: Add login instructions to the .netrc

To set up the credentials required to download the SDK, add the following entry to your .netrc file:

machine api.mapbox.com
login mapbox
password <INSERT SECRET ACCESS TOKEN>

Step 3-5: Set .netrc file permissions

1. Go to your home directory: /Users/[CurrentUser].
   • If you do not see the .netrc file, press Command + Shift + .(the period key).
2. Right click on the .netrc.
3. Click Get Info.
4. Scroll down to Sharing & Permissions.
5. Under your current username, make sure to set Privilege to Read & Write.

Step 4: Configure your public token

To configure your public access token, follow these steps:

1. Open your project's Info.plist file
2. Hover over a key and click the plus button
3. Type MBXAccessToken into the key field
4. Click the value field and paste in your public access token.

Rotating Tokens

When you need to rotate your access token, you will need to update the token value in your Info.plist file.

Users expect the SDK to continue to track the user’s location and deliver audible instructions even while a different application is visible or the device is locked. To do this, go to the Signing & Capabilities tab. Under the Background Modes section, enable “Audio, AirPlay, and Picture in Picture” and “Location updates”. (Or, add the audio and location values to the UIBackgroundModes array in the Info tab.)

Add the dependency

Installing MapboxNavigation versus MapboxCoreNavigation

MapboxCoreNavigation is a dependency of MapboxNavigation. If you install MapboxNavigation you will also have access to all MapboxCoreNavigation's classes and methods. If you do not plan to use the drop-in UI, you can replace MapboxNavigation with MapboxCoreNavigation in the Podfile code snippet below.

Mapbox provides the Navigation SDK via CocoaPods and Carthage. You can choose whichever you prefer.

CocoaPods

Carthage

To add the Mapbox Navigation SDK dependency with CocoaPods, you will need to configure your build to download the Navigation SDK from Mapbox directly. This requires a valid username and an access token with the Downloads: Read scope. In a previous step, you added these items to your .netrc file.

1. Create a Podfile with the following specification:

use_frameworks!
target 'TargetNameForYourApp' do
  pod 'MapboxNavigation', '~> 1.4'
end

2. Run pod repo update && pod install and open the resulting Xcode workspace.

Request a route

Request your first route and simulate a navigation experience using our drop-in UI.

Insert the following code snippets into your ViewController.

 
import MapboxDirections
 
import MapboxCoreNavigation
 
import MapboxNavigation
 

 
class ViewController: UIViewController {
 
    override func viewDidLoad() {
 
        super.viewDidLoad()
 
 
        // Define two waypoints to travel between
 
        let origin = Waypoint(coordinate: CLLocationCoordinate2D(latitude: 38.9131752, longitude: -77.0324047), name: "Mapbox")
 
        let destination = Waypoint(coordinate: CLLocationCoordinate2D(latitude: 38.8977, longitude: -77.0365), name: "White House")
 

 
        // Set options
 
        let routeOptions = NavigationRouteOptions(waypoints: [origin, destination])
 

 
        // Request a route using MapboxDirections.swift
 
        Directions.shared.calculate(routeOptions) { [weak self] (session, result) in
 
            switch result {
 
            case .failure(let error):
 
                print(error.localizedDescription)
 
            case .success(let response):
 
                guard let strongSelf = self else {
 
                    return
 
                }
 
                // Pass the first generated route to the the NavigationViewController
 
                let viewController = NavigationViewController(for: response, routeIndex: 0, routeOptions: routeOptions)
 
                viewController.modalPresentationStyle = .fullScreen
 
                strongSelf.present(viewController, animated: true, completion: nil)
 
            }
 
        }
 
    }
 
}
 

Run the application and you will see a simulated navigation experience along a route.

GUIDE

Access token best practices

Learn how to keep access tokens private in mobile apps.

Testing and development

Simulate a route

Use MapboxNavigationService(simulating:.always) to simulate progress along a route. This simulation mode is different from the simulation features built into both the Simulator and Xcode. The simulation mode built into the Navigation SDK never deviates from the current route, but it does behave more realistically by accounting for the expected travel speed and course at any given time. While navigating, you can double-tap the left or right side of the “Simulating” banner to adjust the playback speed.

let navigationService = MapboxNavigationService(route: route, routeOptions: routeOptions, simulating: .always)
let navigationOptions = NavigationOptions(navigationService: navigationService)
let viewController = NavigationViewController(for: route, routeOptions: routeOptions, navigationOptions: navigationOptions)

Join the Mapbox Developers Discord Communityarrow-right