MapLibre Navigation SDK for iOS
The Maplibre Navigation SDK for iOS is built on a fork of the Mapbox Navigation SDK v0.21 which is build on top of the Mapbox Directions API (v0.23.0) and contains logic needed to get timed navigation instructions.
With this SDK you can implement turn by turn navigation in your own iOS app while hosting your own Map tiles and Directions API.
Why have we forked
- Mapbox decided to put a closed source component to their navigation SDK and introduced a non open source license. Maplibre wants an open source solution.
- Mapbox decided to put telemetry in their SDK. We couldn’t turn this off without adjusting the source.
- We want to use the SDK without paying Mapbox for each MAU and without Mapbox API keys.
All issues are covered with this SDK.
What have we changed
- Removed EventManager and all its references, this manager collected telemetry data which we don’t want to send
- Transitioned from the Mapbox SDK (version 4.3) to Maplibre Maps SDK (version 5.12.2)
- Added optional config parameter in NavigationMapView constructor to customize certain properties like route line color
Getting Started
If you are looking to include this inside your project, you have to follow the the following steps:
- Install Carthage
- Open terminal
- [optional] On M1 Mac change terminal to bash:
chsh -s /bin/bash
- Install Homebrew:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
- Install Carthage:
brew install carthage
- Create a new XCode project
- Create Cartfile
- Open terminal
- Change location to root of XCode project:
cd path/to/Project
- Create the Cartfile:
touch Cartfile
- New file will be added:
Cartfile
- Add Maplibre Maps SPM (Swift Package Manager) depedency by going to your app’s project file -> Package Dependencies -> Press the ‘+’ -> https://github.com/maplibre/maplibre-gl-native-distribution -> ‘Exact’ 5.12.2
- Add dependencies to Cartfile
github "maplibre/maplibre-navigation-ios" ~> 1.0.6
- Build the frameworks
- Open terminal
- Change location to root of XCode project:
cd path/to/Project
- Run:
carthage bootstrap --platform iOS --use-xcframeworks
- New files will be added
- Cartfile.resolved = Indicates which frameworks have been fetched/built
- Carthage folder = Contains all builded frameworks
- Drag frameworks into project:
TARGETS -> General -> Frameworks, Libraries..
- All xcframeworks
- Add properties to
Info.plist
- MGLMapboxAccessToken / String / Leave empty = Ensures that the SDK doesn’t crash
- MGLMapboxAPIBaseURL / String / Add url = Url that is being used to GET the navigation JSON
- NSLocationWhenInUseUsageDescription / String / Add a description = Needed for the location permission
- [optional] When app is running on device and you’re having problems: Add
arm64
toPROJECT -> <Project naam> -> Build Settings -> Excluded Architecture Only
- Use the sample code as inspiration
Getting Help
- Have a bug to report? Open an issue. If possible, include the version of Maplibre Services, a full log, and a project that shows the issue.
- Have a feature request? Open an issue. Tell us what the feature should do and why you want the feature.
Sample code
A demo app is currently not available. Please check the Mapbox repository or documentation for examples, especially on the forked version. You can try the provided demo app, which you need to first run carthage update --platform iOS --use-xc-frameworks
for in the root of this project.
In order to see the map or calculate a route you need your own Maptile and Direction services.
Use the following code as inspiration:
import Mapbox
import MapboxDirections
import MapboxCoreNavigation
import MapboxNavigation
class ViewController: UIViewController {
var navigationView: NavigationMapView?
// Keep `RouteController` in memory (class scope),
// otherwise location updates won't be triggered
public var mapboxRouteController: RouteController?
override func viewDidLoad() {
super.viewDidLoad()
let navigationView = NavigationMapView(
frame: .zero,
// Tile loading can take a while
styleURL: URL(string: "your style URL here"),
config: MNConfig())
self.navigationView = navigationView
view.addSubview(navigationView)
navigationView.translatesAutoresizingMaskIntoConstraints = false
navigationView.topAnchor.constraint(equalTo: view.topAnchor).isActive = true
navigationView.bottomAnchor.constraint(equalTo: view.bottomAnchor).isActive = true
navigationView.leadingAnchor.constraint(equalTo: view.leadingAnchor).isActive = true
navigationView.trailingAnchor.constraint(equalTo: view.trailingAnchor).isActive = true
let waypoints = [
CLLocation(latitude: 52.032407, longitude: 5.580310),
CLLocation(latitude: 51.768686, longitude: 4.6827956)
].map { Waypoint(location: $0) }
let options = NavigationRouteOptions(waypoints: waypoints, profileIdentifier: .automobileAvoidingTraffic)
options.shapeFormat = .polyline6
options.distanceMeasurementSystem = .metric
options.attributeOptions = []
print("[\(type(of:self))] Calculating routes with URL: \(Directions.shared.url(forCalculating: options))")
/// URL is based on the base URL in the Info.plist called `MGLMapboxAPIBaseURL`
/// - Note: Your routing provider could be strict about the user-agent of this app before allowing the call to work
Directions.shared.calculate(options) { (waypoints, routes, error) in
guard let route = routes?.first else { return }
let simulatedLocationManager = SimulatedLocationManager(route: route)
simulatedLocationManager.speedMultiplier = 20
let mapboxRouteController = RouteController(
along: route,
directions: Directions.shared,
locationManager: simulatedLocationManager)
self.mapboxRouteController = mapboxRouteController
mapboxRouteController.delegate = self
mapboxRouteController.resume()
NotificationCenter.default.addObserver(self, selector: #selector(self.didPassVisualInstructionPoint(notification:)), name: .routeControllerDidPassVisualInstructionPoint, object: nil)
NotificationCenter.default.addObserver(self, selector: #selector(self.didPassSpokenInstructionPoint(notification:)), name: .routeControllerDidPassSpokenInstructionPoint, object: nil)
navigationView.showRoutes([route], legIndex: 0)
}
}
}
// MARK: - RouteControllerDelegate
extension ViewController: RouteControllerDelegate {
@objc public func routeController(_ routeController: RouteController, didUpdate locations: [CLLocation]) {
let camera = MGLMapCamera(
lookingAtCenter: locations.first!.coordinate,
acrossDistance: 500,
pitch: 0,
heading: 0
)
navigationView?.setCamera(camera, animated: true)
}
@objc func didPassVisualInstructionPoint(notification: NSNotification) {
guard let currentVisualInstruction = currentStepProgress(from: notification)?.currentVisualInstruction else { return }
print(String(
format: "didPassVisualInstructionPoint primary text: %@ and secondary text: %@",
String(describing: currentVisualInstruction.primaryInstruction.text),
String(describing: currentVisualInstruction.secondaryInstruction?.text)))
}
@objc func didPassSpokenInstructionPoint(notification: NSNotification) {
guard let currentSpokenInstruction = currentStepProgress(from: notification)?.currentSpokenInstruction else { return }
print("didPassSpokenInstructionPoint text: \(currentSpokenInstruction.text)")
}
private func currentStepProgress(from notification: NSNotification) -> RouteStepProgress? {
let routeProgress = notification.userInfo?[RouteControllerNotificationUserInfoKey.routeProgressKey] as? RouteProgress
return routeProgress?.currentLegProgress.currentStepProgress
}
}
Community
Join the #maplibre-native Slack channel at OSMUS: get an invite at https://slack.openstreetmap.us/ Read the CONTRIBUTING.md guide in order to get familiar with how we do things around here.
License
Code is licensed under MIT and ISC. ISC is meant to be functionally equivalent to the MIT license.
Copyright (c) 2022 MapLibre contributors