Get Started
This guide will help you add the Maps SDK for iOS to your project and add a map to your iOS application.
Part 1: Create and configure your credentials
To download and install the 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
Login to your Mapbox account at https://account.mapbox.com. If you don't have an account, sign up for free here.
Your account includes a default public access token, and allows you to create a secret access token for use in the installation of the SDK.
Step 2: Create a secret token
A secret access 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:
- From your account's tokens page, click the Create a token button.
- From the token creation page, give your token a name and make sure the box next to the
Downloads:Read
scope is checked. - Click the Create token button at the bottom of the page to create your token.
- The token you've created is a secret token, which means you will only have one opportunity to copy it somewhere secure.
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
Your secret access token is used only when downloading the SDK binaries for use in your project.
To use your secret token, you must 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.
- In a terminal, go to your home directory.
$ cd ~
- Run
file .netrc
to check whether a.netrc
file already exists. You will see the following message if there is no.netrc
file:
$ file .netrc
.netrc: cannot open `.netrc' (No such file or directory)
- If you already have a
.netrc
file, skip the next step.
Step 3-2: Create the .netrc
file.
- From the same terminal, run
touch .netrc
.
Step 3-3: Open the .netrc
file.
- From the same terminal, run
open .netrc
.
Step 3-4: Add Mapbox credentials to the .netrc
file
Add the following lines of text to your .netrc
file, replacing <INSERT SECRET ACCESS TOKEN>
with the secret access token you created in step 2:
machine api.mapbox.com
login mapbox
password <INSERT SECRET ACCESS TOKEN>
Step 3-5: Set .netrc
file permissions to Read & Write for the current user
- Go to your home directory:
/Users/[CurrentUser]
.
- If you do not see the
.netrc
file, pressCommand
+Shift
+.
(the period key).
- Right click on the
.netrc
. - Click
Get Info
. - Scroll down to
Sharing & Permissions
. - Under your current username, make sure to set
Privilege
toRead & Write
.
From the same terminal, run chmod -R 0600 .netrc
Step 4: Configure your public token
Your public access token is used in your application code when requesting Mapbox resources.
To configure your public access token, follow these steps:
- Open your project's
Info.plist
file - Hover over a key and click the plus button
- Type
MBXAccessToken
into the key field - Click the value field and paste in your public access token.
When you need to rotate your access token, you will need to update the token value in your Info.plist
file.
Learn how to keep access tokens private in mobile apps.
Part 2: Add the dependency
Mapbox provides the Maps SDK via Swift Package Manager, CocoaPods and direct download. You can choose whichever you prefer.
The Mapbox Maps SDK can be installed via Swift Package Manager (SPM) by configuring your environment to download it from Mapbox with a secret token in your .netrc.
- Open your Xcode project or workspace, then go to File > Add Packages Dependencies....
- Enter
https://github.com/mapbox/mapbox-maps-ios.git
into the search bar in the top right corner. - Select the Dependency Rule you want to apply to the Maps SDK
- A common choice for Dependency Rule is "Up to Next Major Version", specifying
11.0.0
as the minimum version. To instead install a specific version set the Dependency Rule field to "Exact Version" and insert the desired version. The latest stable version of the Maps SDK is11.7.1
.
- A common choice for Dependency Rule is "Up to Next Major Version", specifying
- Hit enter or Click Add Package.
- In the new window select the
MapboxMaps
library and click Add Package. Once SPM finishes installing the SDK you will see 4 new dependencies under Package Dependencies:MapboxCommon
,MapboxCoreMaps
,MapboxMaps
, andTurf
. - Click on your project's target, scroll down to
Frameworks, Libraries, and Embedded Content
and click the plus button. - From the list select
MapboxMaps
and click add.
Now you can use start using Mapbox in your project by calling import MapboxMaps
in any of your scripts.
Troubleshooting and Updates
- If you need to update your packages select File > Packages > Update To Latest Package Versions
- If you receive
invalid archive
errors try the following fix:- Step 1: Reset your Package cache in Xcode by clicking File > Packages > Reset Package Cache
- Step 2: Delete
org.swift.swiftpm
- Go to your home directory:
/Users/[CurrentUser]
- Press Command + Shift + .(the period key) in the finder window
- Go to
Library/Caches
- Delete the
org.swift.swiftpm
file - Try install again
- Go to your home directory:
- Step 3: Check that the following is true for your
.netrc
file:- The
.netrc
file is correctly named.netrc
and there is nothing before the period. - The
.netrc
file is not a text file. - The login name is
mapbox
and not your personal account name - The
.netrc
file specifiesRead & Write
permissions. Check with these steps:- Go to your home directory:
/Users/[CurrentUser]
- Right click on the .netrc
- If you do not see the .netrc file, press
Command
+Shift
+.
(the period key)
- If you do not see the .netrc file, press
- Click
Get Info
- Scroll down to
Sharing & Permissions
- Under your current username, make sure that to set
Privilege
toRead & Write
- Go to your home directory:
- The
Learn how to keep access tokens private in mobile apps.
Part 3: Add a map
You can add a map to your application using either UIKit or SwiftUI. Add the proper snippet and then run your application to see the map.
import SwiftUI
import MapboxMaps
struct ContentView: View {
var body: some View {
let center = CLLocationCoordinate2D(latitude: 39.5, longitude: -98.0)
Map(initialViewport: .camera(center: center, zoom: 2, bearing: 0, pitch: 0))
.ignoresSafeArea()
}
}
import UIKit
import MapboxMaps
class ViewController: UIViewController {
override func viewDidLoad() {
super.viewDidLoad()
let mapView = MapView(frame: view.bounds)
let cameraOptions = CameraOptions(center:
CLLocationCoordinate2D(latitude: 39.5, longitude: -98.0),
zoom: 2, bearing: 0, pitch: 0)
mapView.mapboxMap.setCamera(to: cameraOptions)
mapView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
view.addSubview(mapView)
}
}
If you experience any issues while following the Get Started guide, try these fixes here:
Cannot find your .netrc file in your directory
Your finder window will hide the .netrc
when it's created. To view the file in your directory, follow these steps:
- Go to your home directory:
/Users/[CurrentUser]
. - Press
Command
+Shift
+.
(the period key). - Now your
.netrc
file should appear.
Updating Packages
If you need to update your packages select File > Packages > Update To Latest Package Versions
Invalid Archive Errors with Swift Package Manager
If you receive invalid archive
errors try the following fix:
Step 1: Reset your Package cache in Xcode by clicking File > Packages > Reset Package Cache
Step 2: Delete org.swift.swiftpm
- Go to your home directory:
/Users/[CurrentUser]
- Press
Command
+Shift
+.
(the period key) in the finder window - Go to
Library/Caches
- Delete the
org.swift.swiftpm
file - Try installing the package again
Step 3: Check that the following is true for your .netrc
file:
- The
.netrc
file is just named.netrc
and there is nothing before the period. - The
.netrc
file is not a text file. - The login name is
mapbox
and not your personal account name - Set
.netrc
file permissions toRead & Write
if they aren't already. Check with these steps:- Go to your home directory:
/Users/[CurrentUser]
- Right click on the
.netrc
- If you do not see the .netrc file, press
Command
+Shift
+.
(the period key)
- If you do not see the .netrc file, press
- Click
Get Info
- Scroll down to
Sharing & Permissions
- Under your current username, set
Privilege
is toRead & Write
, if it isn't already.
- Go to your home directory: