Skip to content

Latest commit

 

History

History
114 lines (81 loc) · 6.67 KB

custom-navigation.md

File metadata and controls

114 lines (81 loc) · 6.67 KB
Raw

Building your own custom navigation UI

Carthage compatible CocoaPods SPM compatible

⚠️Warning: this page is for advanced use cases only and is not necessary for most users⚠️

The Mapbox Navigation SDK is comprised of two modules:

  • MapboxCoreNavigation - responsible for rerouting, snapping, progress updates etc.
  • MapboxNavigation - responsible for everything UI related.

If the UI provided by MapboxNavigation is not something that can work for your project, it is possible to create a custom navigation experience built on top of MapboxCoreNavigation directly. Note, this is not ideal as it will be a lot of work for the developer. If there is something missing from the UI or not optimal, feel free to open a ticket instead of venturing down this path.

The installation process is very similar to installing the MapboxNavigation framework:

Using Swift Package Manager

To install the MapboxCoreNavigation framework 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.

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

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

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

To install the MapboxCoreNavigation 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(name: "MapboxCoreNavigation", url: "https://github.com/mapbox/mapbox-navigation-ios.git", from: "2.18.0")
// Latest prerelease
.package(name: "MapboxCoreNavigation", url: "https://github.com/mapbox/mapbox-navigation-ios.git", .exact("2.18.0-beta.1"))

Using CocoaPods

To install Mapbox Core Navigation using CocoaPods:

  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.

  2. Create a Podfile with the following specification:

    # Latest stable release
pod 'MapboxCoreNavigation', '~> 2.18'
# Latest prerelease
pod 'MapboxCoreNavigation', :git => 'https://github.com/mapbox/mapbox-navigation-ios.git', :tag => 'v2.18.0-beta.1'

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

Using Carthage

MapboxNavigation no longer supports Carthage as of v2.0.0-alpha.1. However, if you are building a user interface from scratch, you can install just the MapboxCoreNavigation framework using Carthage.

To install Mapbox Navigation using Carthage v0.38 or above:

  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.

  2. (Optional) Clear your Carthage caches:

    rm -rf ~/Library/Caches/carthage/ ~/Library/Caches/org.carthage.CarthageKit/binaries/{MapboxCommon-ios,MapboxNavigationNative}

  3. Create a Cartfile with the following dependency:

    # Latest stable release
github "mapbox/mapbox-navigation-ios" ~> 2.18
# Latest prerelease
github "mapbox/mapbox-navigation-ios" "v2.18.0-beta.1"

  4. Run carthage bootstrap --platform iOS --use-xcframeworks --cache-builds --use-netrc.

  5. Follow the rest of Carthage’s iOS integration instructions. Your application target’s Embed Frameworks build phase should include MapboxCoreNavigation.xcframework, MapboxNavigationNative.xcframework, MapboxCommon.xcframework, and MapboxAccounts.xcframework.

Using Xcode

To install the MapboxCoreNavigation framework using Swift Package Manager within Xcode:

  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.

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

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

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