Doku / Einrichtung / Android / Mapbox

Mapbox einrichten

Verfahren zur Verwendung des Mapbox Maps SDK für Android mit MapConductor. Mapbox wird über ein dediziertes Maven-Repository verteilt und übergibt das Zugriffstoken über das Manifest.

MODULE

com.mapconductor:for-mapbox

API KEY

Zugriffstoken

VIEW

MapboxMapView

TIME

15 Minuten

Derselbe Anbieter, andere PlattformeniOS React

Demo ansehenFilialkarte · React ↗

Bevor Sie beginnen

Android-Entwicklungsumgebung (Android Studio)

Mapbox-Konto

Öffentliches Zugriffstoken (beginnt mit pk.)

STEP 01

Zugriffstoken abrufen

Erstellen Sie ein Mapbox-Konto.
Öffnen Sie Access tokens im Account Dashboard.
Verwenden Sie das Standard-Public-Token oder erstellen Sie ein neues.

ACHTUNG

Betten Sie keine Secret-Tokens (beginnen mit sk.) in die App ein. In der App werden Public-Tokens verwendet.

STEP 02

Mapbox-Maven-Repository hinzufügen

Das Mapbox Maps SDK ist nicht im Maven Central verfügbar, sondern wird aus dem Mapbox-eigenen Repository bezogen.

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

Secrets Gradle Plugin installieren

Ein Mechanismus, um zu vermeiden, dass Schlüssel in die Quellcodeverwaltung gelangen. Das Plugin liest secrets.properties und fügt beim Build Werte in die Platzhalter in AndroidManifest.xml ein.

(root)/build.gradle.ktsKotlin

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

STEP 04

Abhängigkeiten hinzufügen

MapConductor wird für die NDK27-Variante erstellt.

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.28.0")

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

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

STEP 05

Manifest und Token konfigurieren

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

ACHTUNG

Committen Sie secrets.properties nicht in die Versionsverwaltung. Wenn Sie es zu .gitignore hinzufügen, verhindern Sie Fehler. In der CI wird es über andere sichere Wege wie Umgebungsvariablen übergeben.

PRÜFEN

Was Sie sehen sollten

Wenn die Karte mit einem Mapbox-Stil angezeigt wird und Zoomen, Schwenken und Drehen funktionieren, sind Sie fertig.

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

Fehlerbehebung

Die Karte bleibt komplett weiß

Überprüfen Sie, ob das Token in secrets.properties korrekt ist und nicht abgelaufen ist.
Überprüfen Sie, ob es sich um ein Public-Token handelt, das mit pk. beginnt.
Überprüfen Sie, ob der Umfang des Tokens maps:read enthält.

Abhängigkeiten können nicht aufgelöst werden

Überprüfen Sie, ob das Mapbox-Maven-Repository in settings.gradle.kts vorhanden ist.
Überprüfen Sie, ob die NDK27-Variante (com.mapbox.maps:android-ndk27) angegeben ist.

Der Build schlägt fehl

Überprüfen Sie, ob die Koordinaten und die Version des Map SDK mit den Angaben im Versionskatalog übereinstimmen.
Überprüfen Sie, ob die Repository-Definition in settings.gradle.kts vorhanden ist (wenn repositoriesMode auf FAIL_ON_PROJECT_REPOS eingestellt ist, werden repositories auf Modulebene ignoriert).
Wenn mehrere Karten-SDKs gleichzeitig enthalten sind, prüfen Sie mit ./gradlew :app:dependencies, ob Abhängigkeitskonflikte vorliegen.

Weiter

Wenn MapboxMapView erscheint, können Sie Overlays wie bei anderen Anbietern überlagern. Sie können auch Stile angeben, die nicht von Mapbox gehostet werden.