Doku / Einrichtung / Android / MapLibre

MapLibre einrichten

Anleitung zur Verwendung von MapLibre Native Android mit MapConductor. MapLibre selbst hat keinen API-Schlüssel; das Erscheinungsbild der Karte wird vom Ursprung des Styles-JSON bestimmt. Dies ist der Anbieter, der mit den kürzesten Schritten zum Laufen gebracht werden kann.

MODULE

com.mapconductor:for-maplibre

API KEY

Nicht erforderlich

VIEW

MapLibreMapView

TIME

5 Minuten

Derselbe Anbieter, andere PlattformeniOS React

Demo ansehenFilialkarte · React ↗

Bevor Sie beginnen

Android-Entwicklungsumgebung (Android Studio)

URL des Styles-JSON (Demo-Tiles, kommerzieller Service oder Self-Hosting)

STEP 01

Tiles-Herkunft festlegen

MapLibre ist ein Renderer und kein Anbieter von Tiles. Für einen reinen Funktionstest reicht der Demo-Style von MapLibreDesign, aber in der Produktion müssen Sie den Anbieter explizit auswählen.

Kostenlos / Community: OpenStreetMap-basierte Tiles, Protomaps (Self-Hosting möglich)
Kommerziell: MapTiler Cloud, Stadia Maps (beide mit kostenlosem Kontingent)
Self-Hosting: Eigene Auslieferung z. B. mit tileserver-gl

ACHTUNG

Demo-Tiles sind nur zur Funktionsprüfung gedacht. Leiten Sie darauf keine Produktions-Traffic. Außerdem verlangen die meisten Tile-Anbieter eine Namensnennung (z. B. © OpenStreetMap contributors). Prüfen Sie die Nutzungsbedingungen und zeigen Sie sie in der UI an.

STEP 02

Abhängigkeiten hinzufügen

Da das MapLibre SDK aus Maven Central bezogen werden kann, sind keine zusätzlichen Repository-Konfigurationen erforderlich.

settings.gradle.ktsKotlin

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

app/build.gradle.ktsKotlin

dependencies {
    // MapLibre Native Android SDK
    implementation("org.maplibre.gl:android-sdk:13.4.1")

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

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

STEP 03

Berechtigungen zum Manifest hinzufügen

Da kein Schlüssel injiziert wird, sind nur Berechtigungen erforderlich.

AndroidManifest.xmlXML

<manifest>
    <!-- Add internet permission for tile loading -->
    <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>
        <!-- no key to inject for MapLibre -->
    </application>
</manifest>

In Apps ohne Standortnutzung sind ACCESS_*_LOCATION-Berechtigungen nicht erforderlich. Für das Laden von Tiles ist nur INTERNET erforderlich.

PRÜFEN

Was Sie sehen sollten

Zeigt die Karte unter Angabe eines Styles an. Wenn die Tiles geladen werden und Zoomen, Schwenken und Drehen funktionieren, sind Sie fertig.

TestMapLibre.ktJetpack Compose

@Composable
fun TestMapLibre(modifier: Modifier = Modifier) {
    val mapState = rememberMapLibreMapViewState(
        cameraPosition = MapCameraPosition(
            position = GeoPoint(35.6762, 139.6503),
            zoom = 12.0,
        ),
        mapDesign = MapLibreDesign.OpenMapTiles,
    )

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

Kartendesigns

MapLibreDesign ist eine Konstante, die die URL des Styles-JSON umschließt. Wenn Sie einen eigenen Style verwenden, erstellen Sie einen Wert desselben Typs und übergeben ihn.

MapLibreDesign

Notes

DemoTiles

Offizielle Demo-Tiles von MapLibre. Funktionieren am schnellsten ohne Schlüssel.

OsmBright / OsmBrightEn / OsmBrightJa

OSM Bright. Andere Sprachen für Beschriftungen.

MapTilerTonerEn / MapTilerTonerJa

Toner-Stil mit hohem Kontrast

MapTilerBasicEn / MapTilerBasicJa

Basic-Stil mit reduzierter Informationsmenge

OpenMapTiles

Allgemeiner OpenMapTiles-Stil

Fehlerbehebung

Karte bleibt komplett weiß

Prüft, ob die Style-URL erreichbar ist und ob das JSON gültig ist.
Prüft, ob die INTERNET-Berechtigung erteilt ist.
Prüft in Logcat, ob Netzwerk- oder Parser-Fehler auftreten.

Nur Tiles werden nicht geladen

URL des Tile-Servers überprüfen.
Prüft, ob Sie gegen die Ratenbegrenzung des kostenlosen Dienstes verstoßen.
Wenn Sie einen kommerziellen Anbieter verwenden, prüft, ob der in die Style-URL eingebettete Schlüssel gültig ist.

Build schlägt fehl

Stellen Sie sicher, dass die Koordinaten und die Version des Map SDK mit den Angaben im Versionenkatalog übereinstimmen.
Stellen Sie sicher, dass die Repository-Definitionen in settings.gradle.kts vorhanden sind (wenn repositoriesMode auf FAIL_ON_PROJECT_REPOS gesetzt ist, werden die repositories des Moduls ignoriert).
Wenn mehrere Map SDKs gleichzeitig installiert sind, überprüfen Sie mit ./gradlew :app:dependencies, ob Abhängigkeitskonflikte vorliegen.

Weiter

Vektorkacheln sind leichter als Raster und rendern schneller. Wenn eine Offline-Nutzung erforderlich ist, erwägen Sie das Caching von Kacheln.