mapbox / mapbox-navigation-ios

Turn-by-turn navigation logic and UI in Swift on iOS

Mapbox Navigation SDK for iOS

Mapbox Navigation gives you all the tools you need to add turn-by-turn navigation to your iOS application.

Get up and running in a few minutes with our drop-in turn-by-turn navigation NavigationViewController, or build a completely custom turn-by-turn navigation app with our core components for routing and navigation.

Features

• A full-fledged turn-by-turn navigation UI for iPhone, iPad, and CarPlay that’s ready to drop into your application
• Professionally designed map styles for daytime and nighttime driving
• Worldwide driving, cycling, and walking directions powered by open data and user feedback
• Traffic avoidance and proactive rerouting based on current conditions in over 55 countries
• Natural-sounding turn instructions
• Support for over two dozen languages

Documentation

Requirements

The Mapbox Navigation SDK and Core Navigation are compatible with applications written in Swift 5.9 in Xcode 15.0 and above. The Mapbox Navigation and Mapbox Core Navigation frameworks run on iOS 14.0 and above.

The Mapbox Navigation SDK is also available for Android.

Installation

Private token configuration

To install the SDK in an application using Swift Package Manager:

1. Go to your Mapbox account dashboard and create an access token that has the DOWNLOADS:READ scope. PLEASE NOTE: This is not the same as your production Mapbox API token. Make sure to keep it private and do not insert it into any Info.plist file. Create a file named .netrc in your home directory if it doesn’t already exist, then add the following lines to the end of the file:

   machine api.mapbox.com
     login mapbox
     password PRIVATE_MAPBOX_API_TOKEN
   

   where PRIVATE_MAPBOX_API_TOKEN is your Mapbox API token with the DOWNLOADS:READ scope.

Using Swift Package Manager

1. In Xcode, go to File ‣ Swift Packages ‣ Add Package Dependency.

2. Enter https://github.com/mapbox/mapbox-navigation-ios.git as the package repository and click Next.

3. Set Rules to Version, Up to Next Major, and enter 3.1.0 as the minimum version requirement. Click Next.

To install the MapboxNavigation framework in another package rather than an application, run swift package init to create a Package.swift, then add the following dependency:

// Latest stable release
.package(url: "https://github.com/mapbox/mapbox-navigation-ios.git", from: "3.1.0")

Project configuration

1. Mapbox APIs and vector tiles require a Mapbox account and API access token. In the project editor, select the application target, then go to the Info tab. Under the “Custom iOS Target Properties” section, set MBXAccessToken to your access token. You can obtain an access token from the Mapbox account page.

2. In order for the SDK to track the user’s location as they move along the route, set NSLocationWhenInUseUsageDescription to:

   Shows your location on the map and helps improve the map.

3. 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. Go to the Signing & Capabilities tab. Under the Background Modes section, enable “Audio, AirPlay, and Picture in Picture” and “Location updates”. (Alternatively, add the audio and location values to the UIBackgroundModes array in the Info tab.)

Now import the relevant modules and present a new NavigationViewController. You can also push to a navigation view controller from within a storyboard if your application’s UI is laid out in Interface Builder.

Examples

This repository contains a testbed application that exercises a variety of navigation SDK features. Configure Private and Public tokens to run this application.

import MapboxDirections
import MapboxNavigationCore
import MapboxNavigationUIKit
import UIKit
import CoreLocation

// Define the Mapbox Navigation entry point.
let mapboxNavigationProvider = MapboxNavigationProvider(coreConfig: .init())
lazy var mapboxNavigation = mapboxNavigationProvider.mapboxNavigation

// 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 options = NavigationRouteOptions(waypoints: [origin, destination])

// Request a route using RoutingProvider
let request = mapboxNavigation.routingProvider().calculateRoutes(options: options)   
Task {
    switch await request.result {
    case .failure(let error):
        print(error.localizedDescription)
    case .success(let navigationRoutes):
        // Pass the generated navigation routes to the the NavigationViewController
        let navigationOptions = NavigationOptions(mapboxNavigation: mapboxNavigation,
                                                  voiceController: mapboxNavigationProvider.routeVoiceController,
                                                  eventsManager: mapboxNavigationProvider.eventsManager())
        let navigationViewController = NavigationViewController(navigationRoutes: navigationRoutes,
                                                                navigationOptions: navigationOptions)
        navigationViewController.modalPresentationStyle = .fullScreen

        present(navigationViewController, animated: true, completion: nil)
    }
}

Consult the API reference for further details.

Customization

Styling

You can customize the appearance in order to blend in with the rest of your app.

class CustomStandardDayStyle: StandardDayStyle {
    required init() {
        super.init()
        mapStyleURL = URL(string: "mapbox://styles/mapbox/satellite-streets-v9")!
        styleType = .night
    }

    override func apply() {
        super.apply()
        BottomBannerView.appearance(for: UITraitCollection(userInterfaceIdiom: .phone)).backgroundColor = .orange
        BottomBannerView.appearance(for: UITraitCollection(userInterfaceIdiom: .pad)).backgroundColor = .orange
    }
}

then initialize NavigationViewController with your style or styles:

let navigationOptions = NavigationOptions(
            mapboxNavigation: navigationProvider.mapboxNavigation,
            voiceController: navigationProvider.routeVoiceController,
            eventsManager: navigationProvider.eventsManager(),
            styles: [CustomStandardDayStyle()]
        )
NavigationViewController(navigationRoutes: navigationRoutes, navigationOptions: navigationOptions)

License

The Mapbox Navigation SDK for iOS is released under the Mapbox Terms of Service. See LICENSE.md for details.

mapbox-navigation-ios's Issues

Standardize/audit NSNotification keys

They're a little all over the place right now. I think a few can be removed.

Don't anticipate 90 degree turns

The user is going straight, not left.

Alert notifications do not bridge to Objective-C

Move the global variables into classes or find another solution so we can respond to these notifications in Objective-C.

https://developer.apple.com/library/content/documentation/Swift/Conceptual/BuildingCocoaApps/MixandMatch.html

Rerouted path not rendered under labels

Only the initial route is.

Carthage

This library should support distribution via Carthage. This will require splitting the demo projects into a separate Xcode workspace, as in mapbox/mapbox-directions-swift#100, so that Carthage doesn’t end up trying to build projects that depend on CocoaPods.

/cc @bsudekum @frederoni

Remove MapboxGeocoder.swift dependency

This library shouldn’t depend on MapboxGeocoder.swift. The Cartfile shouldn’t specify it as a dependency, and MGLMapView.swift shouldn’t import the module. (It doesn’t appear to use the module in any way.) If an example application needs MapboxGeocoder.swift, it should be specified as a development dependency in Cartfile.private, not Cartfile.

/cc @bsudekum @frederoni

Deal with GPS noise

#57 is a good first step but we need to think more about cleaning out bad GPS noise. Not only should we be snapping locations harder, bearings should be snapped if they are within x degrees of the expected heading.

/cc @frederoni @1ec5

Unable to build OSRMTextInstructions using Carthage due to binary attached to MapboxDirections.swift release

*** Building scheme "OSRMTextInstructions" in OSRMTextInstructions.xcodeproj
Build Failed
Task failed with exit code 65:
/usr/bin/xcrun xcodebuild -project /Users/baidu/Desktop/Playground/MapboxNavigation.swift/Carthage/Checkouts/osrm-text-instructions.swift/OSRMTextInstructions.xcodeproj -scheme OSRMTextInstructions -configuration Release -derivedDataPath /Users/baidu/Library/Caches/org.carthage.CarthageKit/DerivedData/osrm-text-instructions.swift/bdd962bf5593f951bbbbd26435f732a829dacda7 -sdk iphoneos ONLY_ACTIVE_ARCH=NO BITCODE_GENERATION_MODE=bitcode CODE_SIGNING_REQUIRED=NO CODE_SIGN_IDENTITY= CARTHAGE=YES clean build

Interpolate between points on route

Lots of functionality relies on closestCoordinate(on:to:includeDistanceToNextCoordinate:) interpolating between points along the line, which is the documented behavior of that function. But the function doesn’t actually interpolate, and neither does the point-on-line function in Turf that it’s based on.

/cc @bsudekum @cammace

Optimize thresholds for cycling and walking

it should be easy to use MapboxNavigation.swift for bicycle or pedestrian navigation.
instead of hardcoding values that optimize for car routing, it should be possible to change such values.

Problem when installing trough cocoapods or carthage

When i install this library with both dependency managers it always fails when it's checking out osrm-text-instructions.

cocoapods:
[!] Unable to find a specification for OSRMTextInstructions depended upon by MapboxNavigationUI.swift

Does anybody have the same behavior?

Make distance more prominent in turn banner

#56 stuffed the distance under the maneuver icon and gave the road name top billing in the turn banner, like Google Maps and unlike Apple Maps. This is a usability regression: a driver glances periodically at their phone primarily to gauge the ever-changing distance. It’s less urgent to inform the driver that the upcoming road still has the same name as it did a moment ago. After all, if you know what maneuver to perform (based on the icon) and when to perform it (based on the distance), the road name becomes inessential, mostly there for reassurance.

We should reconsider the layout of the turn banner. The distance should be a the heading (larger, bolder) and the road name should be a subheading (smaller, fainter). By setting the road name in a somewhat smaller font, we’d also have more room for longer street names without resorting to autoshrinking. We’d also be able to enlarge the maneuver icon.

As an additional optimization, we could shrink the distance and enlarge the road name as the user approaches the junction. At that point (and no sooner), the distance becomes unimportant and it often becomes more important to distinguish between multiple streets meeting at the junction.

/cc @katmeng @bsudekum @frederoni @cammace

pod spec lint error

bobby MapboxNavigation.swift (master) $ pod spec lint

 -> MapboxNavigation.swift (0.0.1)
    - ERROR | [iOS] unknown: Encountered an unknown error (Unable to find a specification for `MapboxDirections.swift` depended upon by `MapboxNavigation.swift`) during validation.

Analyzed 1 podspec.

[!] The spec did not pass validation, due to 1 error.

/cc @frederoni @1ec5

Cancel button should look like a button

Nothing about the Cancel button’s style makes it look like a button. Black text isn’t supposed to be tappable on iOS. Either the button text should match the application’s tint color, or it should be red (as a destructive action).

/cc @bsudekum @mayagao

bike routing?

has this been tested with bike routing? things like when you provide guidance messages might have to be adjusted - is this possible?

Some of the contents of the document are out of date.

MapboxNavigation and MapboxCoreNavigation should be subspecs

There should only be one podspec in this repository, not two, and it should contain two subspecs – one for the UI stuff and one for the non-UI stuff. That’ll makes it more efficient to install the entire navigation SDK via CocoaPods. Not clear whether both subspecs should be included by default.

I’d consider this a blocker for publishing the podspecs on CocoaPods.org, because there isn’t a real way to remove a pod once it’s up there.

/ref Project-OSRM/osrm-text-instructions.swift#15
/cc @bsudekum @frederoni

Error installing via Carthage

#50 introduced CocoaPods-specific build phases into the Xcode project, so anyone trying to install either framework via Carthage will get this error:

The sandbox is not in sync with the Podfile.lock

Our options are to revert #50 and find another way to develop both frameworks in tandem; or split the UI framework into a separate Xcode project in a different folder and stop claiming to support Carthage for that framework; or stop claiming to support Carthage for either framework.

/cc @bsudekum @frederoni

Error instilling via cocoa pods

Pre-downloading: `MapboxNavigationUI.swift` from `https://github.com/mapbox/MapboxNavigation.swift.git`, tag `v0.0.4`
[!] Unable to find a specification for 'MapboxNavigationUI.swift'.

pod repo remove master
pod setup
pod update

^Doesn't help

Destination pin should match style

We’re currently using the map SDK’s default annotation icon for the destination pin. The red has good contrast with the default navigation style, but maybe we could be using a different color and different shape that more closely matches the style.

Down the line, we might also want to make it easier for the developer to customize the annotation to match the annotation they’re using to represent the destination on a preview map or some other map. But matching the style would be a good start.

/cc @aparlato @pveugen @bsudekum

Better state restoration

We should be able to restore views/settings better

Prevent manual editing after pod update

After this SDK has been installed with pod update you have to edit "Use Legacy Swift Version". There should be ways to avoid that by using .swift-version file or a podspec setting.

Resume navigation after map move?

I might have missed it in the source, but is there any way to determine the navigation state after the user moves the mapView? The userlocation marker changes back to a default location marker, so I would want to simultaneously change the button label to "Resume".

After rerouting an announcement should be given automatically

In the demo app after rerouting, no announcement is given. This is due to the RouteControllerAlertLevelDidChange notification not firing.

handle multiple waypoints

Allow setting access token programmatically

As of 892f1e5 for #3, this library uses Directions.shared, which automatically reads the access token from the Info.plist. But if the developer needs to specify the access token programmatically, they’re out of luck. Plus, now everyone with access to this repository knows your access token.

Instead, NavigationController’s initializer should accept an access token as an optional argument. In the example application, use a placeholder token, which looks like this inside Xcode:

If the developer doesn’t specify an access token, NavigationController can create Directions with a nil access token, which will cause Directions to automatically look in the Info.plist.

/cc @bsudekum

Progress bar never reaches the end

Remove dependency on UIKit

This SDK doesn't have any UI elements so we can safely remove the dependency on UIKit.

Remove `isFirstAlertForStep`

This is unused.

Missing podfile file

Carthage installation is always a lack of MapboxGeocoder dependencies, can your provide CocoaPods installation?

Make annotate function public/overridable

This should be configurable: https://github.com/mapbox/MapboxNavigation.swift/blob/master/MapboxNavigationUI/MGLMapView.swift#L15

Make polly request as user enters maneuver zone

Since they will most likely complete this maneuver. The goal here is to reduce latency.

RouteStepFormatter.swift missing

RouteStepFormatter.swift seems to be missing from MapboxNavigationUI in the recent commits which causes an error when building the framework. Am I missing something?

Should this handle voice announcements?

Still conflicted on this

Carthage problem

I'm not totally proficient with carthage but when I add the repo to m Cartfile like listed it takes down the Podfiles as well and prevents carthage from building with the Podfile.lock sync error. I had to go into the project directory that carthage pulled down and do pod install there before I could build the framework from my project directory.

Carthage must be pinned to master branch

I have the same problem as this user building the project using Carthage. They used Cocoapods as a workaround to solve their issue. Unfortunately, Cocoapods is not available to our team.

UPDATE: Tried a workaround that did not work previously, (last week).

If the Cartfile reads:

github "SwiftyBeaver/SwiftyBeaver"
github "aws/aws-sdk-ios"
github "mapbox/MapboxNavigation.swift"

Then the error is

$ carthage update --platform ios MapboxNavigation.swift
*** Fetching aws-sdk-ios
*** Fetching SwiftyBeaver
*** Fetching MapboxNavigation.swift
*** Checking out MapboxNavigation.swift at "v0.0.4"
*** xcodebuild output can be found in /var/folders/b7/pzkvpztn745_zj_bgsrtzpqw0000gq/T/carthage-xcodebuild.SOgltt.log
*** Building scheme "MapboxNavigation" in MapboxNavigation.xcodeproj
Build Failed
        Task failed with exit code 65:
        /usr/bin/xcrun xcodebuild -project /Users/benjaminespey/Documents/gForce/Carthage/Checkouts/MapboxNavigation.swift/MapboxNavigation.xcodeproj -scheme MapboxNavigation -configuration Release -derivedDataPath /Users/benjaminespey/Library/Caches/org.carthage.CarthageKit/DerivedData/MapboxNavigation.swift/v0.0.4 -sdk iphoneos ONLY_ACTIVE_ARCH=NO BITCODE_GENERATION_MODE=bitcode CODE_SIGNING_REQUIRED=NO CODE_SIGN_IDENTITY= CARTHAGE=YES clean build

This usually indicates that project itself failed to compile. Please check the xcodebuild log for more details: /var/folders/b7/pzkvpztn745_zj_bgsrtzpqw0000gq/T/carthage-xcodebuild.SOgltt.log

If instead "master" is appended as the target branch

github "SwiftyBeaver/SwiftyBeaver"
github "aws/aws-sdk-ios"
github "mapbox/MapboxNavigation.swift" "master"

Then carthage builds successfully

$ carthage update --platform ios MapboxNavigation.swift
*** Fetching MapboxNavigation.swift
*** Fetching aws-sdk-ios
*** Fetching SwiftyBeaver
*** Downloading binary-only framework Mapbox-iOS-SDK at "https://www.mapbox.com/ios-sdk/Mapbox-iOS-SDK.json"
*** Fetching MapboxDirections.swift
*** Fetching Pulley
*** Fetching SDWebImage
*** Checking out aws-sdk-ios at "1a8432b03c22326fb7ed86fac978212106e2d465"
*** Checking out Polyline at "f86f34dac9aae7e027fd9f62c2e01dd77f1ee312"
*** Downloading MapboxDirections.swift.framework binary at "v0.8.0"
*** Checking out MapboxDirections.swift at "v0.8.0"
*** Checking out osrm-text-instructions.swift at "bdd962bf5593f951bbbbd26435f732a829dacda7"
*** Checking out Pulley at "1.3.1"
*** Checking out SDWebImage at "4.0.0"
*** Checking out MapboxNavigation.swift at "ca85751f7e76e793ff8d99e0993fb14b541bdf2a"
*** xcodebuild output can be found in /var/folders/b7/pzkvpztn745_zj_bgsrtzpqw0000gq/T/carthage-xcodebuild.GFfv1i.log
*** Building scheme "AWSPolly" in AWSiOSSDKv2.xcodeproj
*** Building scheme "AWSCore" in AWSiOSSDKv2.xcodeproj
*** Building scheme "Polyline" in Polyline.xcodeproj
*** Building scheme "MapboxDirections iOS" in MapboxDirections.xcodeproj
*** Building scheme "OSRMTextInstructions" in OSRMTextInstructions.xcodeproj
*** Building scheme "Pulley" in Pulley.xcodeproj
*** Building scheme "SDWebImage iOS" in SDWebImage.xcworkspace
*** Building scheme "MapboxNavigation" in MapboxNavigation.xcodeproj
*** Building scheme "MapboxNavigationUI" in MapboxNavigation.xcodeproj

Multiple notifications for the same event emmitted

I'm seeing two per RouteControllerAlertLevelDidChange

allow custom OSRM servers

many users of OSRM run their own OSRM servers. it would make MapboxNavigation.swift more useful if it's easy to connect to your own OSRM server.

a problem is that the mapbox directions API does not return raw OSRM responses, but use a node app to modify/amend it before returning it. either the expected format should be documented or the code used to modify the OSRM response should be open sourced.

Don't redraw the maneuver arrow if it's in the correct location

We don't need to redraw the maneuver arrow on each alert update.

Add tests

😐

MBRouteStep

The Property maneuverType is inaccessible from Objective C because of being optional.

MBRouteStep.swift
open let maneuverType: ManeuverType

Progress bar should animate smoothly

I-280 pronounced as "eye two hundred eighty"

This should be "eye two eighty"

Add route overview button

Should fit the bounds to the current user location + end of route (not start -> finish).

Pod error

Hello, I am adding NavigationUI, which I hadn't seen before, and looks very cool, via pods, and I am getting this error:
pod 'MapboxNavigationUI.swift', :git => 'https://github.com/mapbox/MapboxNavigation.swift.git', :tag => 'v0.0.4'
[!] Unable to find a specification for 'MapboxNavigationUI.swift'.

It says bitrise is failing
Just so you are aware of it :)
Thanks for everything!

CocoaPods preflight tests fail for third-party PRs

The CocoaPods preflight test on Bitrise is failing for PRs contributed from third-party developers on their own forks of the repository.

#54 added a CocoaPods step to the Bitrise workflow that tests whether the library can be installed via CocoaPods without errors. This step replaces BRANCH_NAME placeholders with the PR’s branch name but leaves the Git address in place, even if the branch lives on a fork.

You can see an example of this failure in #86.

/cc @frederoni @bsudekum

Refactor RouteVoiceController

If the developer buys into using UI, they should not have to also worry about voice. Let's make initialization and management controlled within NavigationUI.

/cc @frederoni

Index out of bounds when creating RouteController object

Hello, I am trying to use your SDK in my application.
I first create a route with
directions.calculate(options) { (waypoints, routes, error) in
So I have a correct Route object, but when I do
RouteController.init(route: route)
it crashes, but the only output I get is
fatal error: Index out of range 2017-01-31 12:53:51.629455 fashioncompass[1172:472618] fatal error: Index out of range
Do you know why would it be?
Is there a way to show a debug trace?

Thanks for your help :)

Documentation

The library should have a documentation comment for every public symbol. Swift uses reStructuredText format for documentation comments.

Additionally, we can look into generating HTML documentation based on these comments. The mobile team is quite happy with jazzy, which relies on the compiler for parsing, so you know it’ll work with whatever syntax you throw at it. It also generates a Dash docset for those who like their documentation that way.

/cc @bsudekum @friedbunny

Merge MapboxNavigation and MapboxNavigationUI

I think we should look into merging MapboxNavigationUI into MapboxNavigation. I think one of the big reasons against this is bloat; you'd have to use AWS polly + core even if you don't use it. If this is the only standing reason, let's investigate conditionally importing these libraries.

/cc @1ec5 @frederoni