Docs / Setup / iOS / Mapbox

Mapbox setup

How to drive the Mapbox Maps SDK for iOS through MapConductor. Pick it when your app already depends on Mapbox, or when you need Mapbox style URLs.

PACKAGE

ios-for-mapbox

API KEY

Access token

MIN iOS

17.0

VIEW

MapboxMapView

Same provider, other platformsAndroid React

View demoStore Map · React ↗

Before you start

Xcode 15 or newer

A Mapbox account (free or paid)

A public access token with the maps:read scope

A deployment target of iOS 17.0 or later

STEP 01

Get an access token

Create a Mapbox account or sign in.
Copy the default public token under Tokens.
Or create a new token carrying the maps:read scope.

CAUTION

Never embed a secret token in an app — apps use the public token.

STEP 02

Add it with Swift Package Manager

Use File > Add Package Dependencies in Xcode and paste the package URL. The Mapbox Maps SDK comes in automatically as a dependency.

Package URLSwift Package Manager

https://github.com/MapConductor/ios-for-mapbox

Package.swiftSwift

dependencies: [
    .package(url: "https://github.com/MapConductor/ios-sdk-core", from: "1.1.4"),
    .package(url: "https://github.com/MapConductor/ios-for-mapbox", from: "1.0.0"),
],
targets: [
    .target(
        name: "YourApp",
        dependencies: [
            .product(name: "MapConductorCore", package: "ios-sdk-core"),
            .product(name: "MapConductorForMapbox", package: "ios-for-mapbox"),
        ]
    ),
]

STEP 03

Initialise the SDK

Call initializeMapbox(accessToken:) exactly once, before any map view is created.

MyApp.swiftSwift

import SwiftUI
import MapConductorForMapbox

@main
struct MyApp: App {
    init() {
        initializeMapbox(accessToken: "YOUR_MAPBOX_PUBLIC_TOKEN")
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

ContentView.swiftSwift

// Alternative: call it from the view's sdkInitialize closure
MapboxMapView(state: mapState, sdkInitialize: {
    initializeMapbox(accessToken: "YOUR_MAPBOX_PUBLIC_TOKEN")
})

STEP 04

Add the location permission (if needed)

If you use location, declare the purpose in Info.plist.

Info.plistXML

<key>NSLocationWhenInUseUsageDescription</key>
<string>We need your location to display on the map</string>

LocationManager.swiftSwift

import CoreLocation

final class LocationManager: NSObject, ObservableObject, CLLocationManagerDelegate {
    private let manager = CLLocationManager()

    override init() {
        super.init()
        manager.delegate = self
    }

    func requestPermission() {
        manager.requestWhenInUseAuthorization()
    }
}

VERIFY

What you should see

You are done when the map renders in a Mapbox style and zoom and pan work.

ContentView.swiftSwiftUI

import SwiftUI
import MapConductorCore
import MapConductorForMapbox

struct ContentView: View {
    @StateObject var mapState = MapboxViewState(
        mapDesignType: MapboxMapDesign.Standard,
        cameraPosition: MapCameraPosition(
            position: GeoPoint(latitude: 35.6812, longitude: 139.7671),
            zoom: 12.0
        )
    )

    var body: some View {
        MapboxMapView(state: mapState)
            .ignoresSafeArea()
    }
}

Map designs

MapboxMapDesign covers Mapbox's standard styles; point it at your own with MapboxMapDesign.custom(styleURI:).

MapboxMapDesign

Notes

Standard

The default standard style

Streets

The streets style

SatelliteStreets

Satellite imagery with roads and labels

Dark

The dark style

Troubleshooting

The map stays blank

Confirm initializeMapbox(accessToken:) runs before the map view is created.
Check the token carries the maps:read scope.
Check the deployment target is iOS 17.0 or later.

“Invalid access token” appears

Re-check the token value and that it has not been revoked.
Make sure you are using the public token, not a secret one.

The build fails

Clean the build folder (Cmd+Shift+K).
Delete ~/Library/Developer/Xcode/DerivedData and rebuild.
Refresh the Swift Package Manager dependencies, and avoid mixing in CocoaPods.

With MapboxMapView on screen, overlays go on through the same shared API as every other provider.