Docs / Setup / Android / Mapbox

Mapbox setup

How to drive the Mapbox Maps SDK for Android through MapConductor. Mapbox ships from its own Maven repository, and the access token is passed in through the manifest.

MODULE

com.mapconductor:for-mapbox

API KEY

Access token

VIEW

MapboxMapView

TIME

15 min

Same provider, other platformsiOS React

View demoStore Map · React ↗

Before you start

An Android development environment (Android Studio)

A Mapbox account

A public access token (it starts with pk.)

STEP 01

Get an access token

Create a Mapbox account.
Open Access tokens in the Account Dashboard.
Use the default public token, or create a new one.

CAUTION

Never ship a secret token (the ones starting with sk.) inside an app. Apps use the public token.

STEP 02

Add the Mapbox Maven repository

The Mapbox Maps SDK is not on Maven Central; it comes from Mapbox's own repository.

settings.gradle.ktsKotlin

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()

        // Mapbox Maven repository
        maven {
            url = uri("https://api.mapbox.com/downloads/v2/releases/maven")
        }
    }
}

STEP 03

Add the Secrets Gradle Plugin

This is how the key stays out of source control: the plugin reads secrets.properties and substitutes the value into the AndroidManifest.xml placeholder at build time.

(root)/build.gradle.ktsKotlin

plugins {
    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") version "2.0.1" apply false
}

STEP 04

Add the dependencies

MapConductor builds against the NDK27 variant.

app/build.gradle.ktsKotlin

plugins {
    // ... other plugins
    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
}

dependencies {
    // Mapbox Maps SDK (NDK27 variant)
    implementation("com.mapbox.maps:android-ndk27:11.24.3")

    // MapConductor BOM pins every module below
    implementation(platform("com.mapconductor:mapconductor-bom:1.2.0"))

    implementation("com.mapconductor:core")
    implementation("com.mapconductor:for-mapbox")
}

STEP 05

Wire the manifest and the token

AndroidManifest.xmlXML

<manifest>
    <!-- Add internet and location permissions -->
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

    <application>
        <!-- Mapbox Access Token -->
        <meta-data
            android:name="MAPBOX_ACCESS_TOKEN"
            android:value="${MAPBOX_ACCESS_TOKEN}" />
    </application>
</manifest>

secrets.propertiesProperties

MAPBOX_ACCESS_TOKEN=your_actual_access_token

CAUTION

Never commit secrets.properties. Add it to .gitignore so it cannot slip in, and feed the value through environment variables (or another secure channel) in CI.

VERIFY

What you should see

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

TestMapbox.ktJetpack Compose

@Composable
fun TestMapbox(modifier: Modifier = Modifier) {
    val mapState = rememberMapboxMapViewState(
        cameraPosition = MapCameraPosition(
            position = GeoPoint(35.6762, 139.6503),
            zoom = 12.0,
        ),
    )

    // If the map appears, the setup is correct.
    MapboxMapView(modifier = modifier, state = mapState)
}

Troubleshooting

The map stays blank

Check the token in secrets.properties is correct and has not been revoked.
Confirm it is a public token — it should start with pk.
Verify the token scope includes maps:read.

The dependency cannot be resolved

Check the Mapbox Maven repository is declared in settings.gradle.kts.
Make sure you are asking for the NDK27 variant (com.mapbox.maps:android-ndk27).

The build fails

Check that the map SDK coordinates and version match what your version catalog declares.
Make sure the repository is declared in settings.gradle.kts — with repositoriesMode set to FAIL_ON_PROJECT_REPOS, per-module repositories blocks are ignored.
If several map SDKs are present at once, look for dependency clashes with ./gradlew :app:dependencies.

With MapboxMapView on screen, overlays are written exactly as on any other provider — and you can point it at non-Mapbox styles too.