Skip to content
MapConductor

Mapbox Setup

This section covers the setup process for Mapbox Maps SDK integration with MapConductor.

Prerequisites

  • Android development environment
  • Mapbox account
  • Mapbox access token

Setup Steps

1. Mapbox Account Configuration

  1. Sign up for a Mapbox account
  2. Go to your Mapbox Account Dashboard
  3. Navigate to Access tokens
  4. Create a new access token or use the default public token
  5. Copy the access token for use in your app

2. Gradle Configuration

Ensure the Mapbox Maven repository is configured (this repository already has it in settings.gradle.kts):

settings.gradle.kts
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")
        }
    }
}

Add the Secrets Gradle Plugin to your project’s root build.gradle.kts or build.gradle:

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

Then, add the dependencies and apply the plugin in your app’s build.gradle.kts or build.gradle:

App/build.gradle.kts
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 for version management (v1.1.7)
    implementation(platform("com.mapconductor:mapconductor-bom:1.1.7"))


    // MapConductor modules (versions managed by BOM)
    implementation("com.mapconductor:core")
    implementation("com.mapconductor:for-mapbox")
}

The Secrets Gradle Plugin automatically reads your secrets.properties file and injects the values into your AndroidManifest.xml at build time.

3. Android Manifest Configuration

Add the Mapbox access token placeholder to your AndroidManifest.xml:

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


    <!-- 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>

4. Access Token Configuration

Add your actual access token to your secrets.properties file:

secrets.properties
MAPBOX_ACCESS_TOKEN=your_actual_mapbox_access_token_here

Important:

  • Never commit your secrets.properties file to version control. Add it to .gitignore.
  • The Secrets Gradle Plugin automatically replaces ${MAPBOX_ACCESS_TOKEN} in your AndroidManifest.xml with the actual value from this file.
  • For CI/CD builds, you can set environment variables or use other secure methods to provide these values.
.gitignore
secrets.properties

5. Style Configuration

Mapbox allows custom map styles. You can use built-in styles or create custom ones, but this configuration is done in your Composable code rather than in the basic setup described here.

Verification

To verify your Mapbox setup:

  1. Build and run your app
  2. Check that the map displays with Mapbox styling
  3. Test map interactions (zoom, pan, rotate)
@Composable
fun TestMapbox() {
    val state =
        rememberMapboxMapViewState(
            cameraPosition =
                MapCameraPosition(
                    position = GeoPoint.fromLatLong(0.0, 0.0),
                    zoom = 3.0,
                ),
        )


    MapboxMapView(
        modifier = modifier,
        state = state,
    ) {
        // If this displays correctly, your setup is working
    }
}

Troubleshooting

Common Issues

Map not displaying (blank screen)

  • Verify access token is correct in secrets.properties
  • Check that the token has not expired
  • Ensure internet connectivity for tile loading

Access token errors

  • Double-check the token value (typically starts with pk.)
  • Verify token permissions in Mapbox account dashboard
  • Check token scopes include required permissions

Build errors

  • Ensure the Mapbox SDK coordinates match your project configuration
  • Verify the NDK27 variant is used
  • Check that secrets.properties file exists and contains the token

Next Steps

Once Mapbox Maps SDK is properly configured, you can use MapConductor’s MapboxMapView component with the unified API.