Get Started with Maps SDK for iOS | Maps SDK | iOS

This guide will walk you through installing the most recent version of the Mapbox Maps SDK for iOS, configuring your iOS app to use the Maps SDK, and initializing a Mapbox map in your iOS app.

Prerequisites

A Mapbox account: Sign up or log into a free account on Mapbox.
Xcode: Install Xcode to your device through the Macbook App Store.

Part 1: Configure your credentials

Before starting to develop your application with the Maps SDK, you'll need to create and configure your credentials.

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: Configure your public token

Follow these steps to grab a public access token from your Mapbox account and add it to your project's Info.plist.

Open your project or create a new project in Xcode.
- If creating a new project, we recommend using the App project type.
Navigate to your project's Info.plist file.
- This is located in your main project page. You can go here by double clicking the project title in the top left corner, then Info in the middle of the screen.
Hover over a key and click the plus button.
Type MBXAccessToken into the key field and hit tab to select the value field.
Grab your default public access token.
- To grab your token, open up a browser and go to your account's tokens page.
- On the top of your token list, copy your Default Public Token.
Go back to Xcode and in the value field, paste in your default public token.

Your public access token is now available for use in your iOS project and you will be able to access the Mapbox SDK.

Advanced Topics: Best Practices, Rotating Tokens & Adding Tokens at Runtime

GUIDE

Access token best practices

Learn how to keep access tokens private in mobile apps.

Adding Tokens at Runtime

You can also implement tokens at runtime, but this requires you to have a separate server to store your tokens. This is helpful if you want to rotate your tokens or add additional security by storing your tokens outside of the application, but is a much more complex method of implementation.

If you do choose to follow this method, we recommend calling MapboxOptions.accessToken = YOUR_PUBLIC_MAPBOX_ACCESS_TOKEN before inflating the MapView, to avoid errors from occurring.

Rotating Tokens

For more information on access token rotation, consult the Access Tokens Information page.

Part 2: Add the dependency

Mapbox provides the Maps SDK via Swift Package Manager, CocoaPods and direct download. You can choose whichever you prefer.

Swift Package Manager

CocoaPods

Direct download

Follow the steps below to download and install the Mapbox Maps SDK via the Swift Package Manager.

In your Xcode project or workspace, go to File > Add Packages Dependencies....
Enter the following GitHub URL into the search bar in the top right corner:


https://github.com/mapbox/mapbox-maps-ios.git

Select the Dependency Rule you want to apply to the Maps SDK
- We recommend selecting "Up to Next Major Version" for the Dependency Rule, specifying 11.0.0 as the minimum version. This allows you to select the most recently released stable minor version of the SDK.
- 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 is 11.12.1.
Hit enter or Click Add Package.
In the new window, click the dropdown under Add to Target and select your project target.
Click Add Package.
Once the SDK finishes installing, make sure you can see 4 new dependencies on the left side of the editor, under Package Dependencies:
- MapboxCommon
- MapboxCoreMaps
- MapboxMaps
- Turf
Next, click on your project's target, scroll down to Frameworks, Libraries, and Embedded Content and make sure MapboxMaps is included.
- To access your project's target, click the name of your project on the left side of your editor, then on the left side of the inner window, selecting the first name underneath the Target header.
- If the library is not added, click the + button and from the list that appears, select MapboxMaps and click Add.

Now you can use start using Mapbox in your project by adding import MapboxMaps to the top of any of your files.

Updating your packages

If you are using the Swift Package Manager and need to update your packages select File > Packages > Update To Latest Package Versions.

Part 3: Add a map

You can now add a map to your application using either UIKit or SwiftUI, by following these steps:

On the left side of the editor, select the folder with your project name.
Click on the file name YOURPROJECTNAMEApp.
Copy the code snippet below and add it to file.
Run your application and you should see an interactable map appear in the simulator.
- When running the simulator, make sure to set your build platform to a type of iOS device, for example iPhone 16. If you see My Mac or Any iOS Device at the top of Xcode, switch the type to a specific iOS device.

SwiftUI

UIKit

SwiftUI

UIKit


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()
    }
}

SwiftUI

UIKit


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)
    }
}

Troubleshooting

If the MapboxMaps library is not accessible from your code, try the following:
- Make sure the 4 libraries are listed in Frameworks, Libraries, and Embedded Content.
  - You should see the 4 libraries: MapboxCommon, MapboxCoreMaps, MapboxMaps,Turf.
  - If these are missing, click the plus button and add each of them from the list.
- Check that Embed dropdown for each library is assigned Embed & Sign in the Frameworks, Libraries, and Embedded Content section.
- Remove and re-add package if the information above is true.
If you cannot run the map in your simulator, try the following:
- Make sure your token is added to the Info.plist and is a valid token.
- Check that build platform is assigned to a specific iOS device, such as iPhone 16. If you see My Mac or Any iOS Device, this may cause issues when trying to run the simulator.