Configuración de MapLibre

En esta sección se explica cómo configurar MapLibre Native Android junto con MapConductor.

Requisitos previos

Entorno de desarrollo Android
URL del servidor de teselas (por ejemplo, OpenStreetMap, Maptiler o un servidor auto-hospedado)
URL o configuración del estilo JSON

Pasos de configuración

1. Selección del servidor de teselas

MapLibre es una biblioteca de mapas de código abierto que requiere un servidor de teselas. Algunas opciones:

Opciones gratuitas / comunitarias:

Teselas de OpenStreetMap: gratis, pero requiere atribución.
Protomaps: datos abiertos con opciones de auto-hospedado.

Proveedores comerciales:

Maptiler: ofrece nivel gratuito.
Stadia Maps: ofrece nivel gratuito.
MapTiler Cloud: nivel gratuito generoso.

Auto-hospedado:

Ejecuta tu propio servidor de teselas con herramientas como tileserver-gl.

2. Configuración de Gradle

Añade las dependencias en el build.gradle.kts o build.gradle de tu app:

Kotlin (build.gradle.kts)
Groovy (build.gradle)

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

    // BOM de MapConductor para la gestión de versiones (v1.1.3)
    implementation(platform("com.mapconductor:mapconductor-bom:1.1.3"))

    // Módulos de MapConductor (versiones gestionadas por el BOM)
    implementation("com.mapconductor:core")
    implementation("com.mapconductor:for-maplibre")
}

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

    // BOM de MapConductor para la gestión de versiones (v1.1.3)
    implementation platform("com.mapconductor:mapconductor-bom:1.1.3")

    // Módulos de MapConductor (versiones gestionadas por el BOM)
    implementation "com.mapconductor:core"
    implementation "com.mapconductor:for-maplibre"
}

El SDK de MapLibre está disponible en Maven Central, que debería estar configurado ya en tu settings.gradle.kts o settings.gradle:

Kotlin (settings.gradle.kts)
Groovy (settings.gradle)

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

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

3. Configuración de AndroidManifest

Añade los permisos necesarios en tu AndroidManifest.xml:

<application>


    <!-- Añade permiso de internet para la carga de teselas -->
    <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. Configuración de estilo

MapLibre requiere un JSON de estilo para definir cómo se ve el mapa. Puedes usar un estilo alojado o uno personalizado.

Estilo de demostración

val mapDesign = MapLibreDesignType.DemoTiles

Uso de estilo alojado

val mapDesign = MapLibreDesignType(
    "basic map",
    "https://api.maptiler.com/maps/base-v4/style.json?key=YOUR_API_KEY",
)

Uso de estilo OpenStreetMap

// Ejemplo usando el estilo OSM Liberty
val mapDesign = MapLibreDesignType(
    "OpenStreetMap",
    "https://tiles.openfreemap.org/styles/liberty",
)

Verificación

Para verificar la configuración de MapLibre:

Compila y ejecuta la app.
Comprueba que las teselas del mapa se cargan correctamente.
Prueba las interacciones de mapa (zoom, desplazamiento, rotación).
Verifica que se muestre la atribución si tu proveedor de teselas lo requiere.

@Composable
fun TestMapLibre() {
    val state = rememberMapLibreMapViewState(
        cameraPosition =
            MapCameraPosition(
                position = GeoPoint.fromLatLong(0.0, 0.0),
                zoom = 3.0,
            ),
        mapDesign = MapLibreDesignType(
            "basic map",
            "https://api.maptiler.com/maps/base-v4/style.json?key=API_KEY_FOR_MAPTILER",
        ),
    )

    MapLibreMapView(
        modifier = modifier,
        state = state,
    ) {
        // Si esta pantalla se muestra correctamente, tu configuración es válida
    }
}

Resultado de TestMapLibre

Solución de problemas

Problemas comunes

El mapa no se muestra (pantalla en blanco)

Verifica que la URL del estilo sea accesible y correcta.
Comprueba la conectividad a internet para la carga de teselas.
Asegúrate de que el JSON de estilo sea válido.
Revisa Logcat en busca de errores de red o de análisis.

Las teselas no se cargan

Verifica que la URL del servidor de teselas sea correcta.
Comprueba los límites de tasa de servicios de teselas gratuitos.
Si usas proveedores comerciales, asegúrate de que el API key sea válido.
Revisa que los permisos de red estén concedidos.

Atribución ausente

La mayoría de los proveedores de teselas requieren que se muestre atribución.
Revisa los términos de servicio de tu proveedor.
Añade el texto de atribución correspondiente en la interfaz de tu aplicación.

Errores de compilación

Verifica que la versión del SDK de MapLibre sea compatible.
Asegúrate de que el repositorio Maven Central esté configurado.
Comprueba posibles conflictos de dependencias con otros SDKs de mapas.

Requisitos de atribución

Muchos servidores de teselas requieren atribución. Ejemplos comunes:

Stadia Maps: revisa sus requisitos específicos.

Asegúrate de mostrar las atribuciones requeridas en la interfaz de tu aplicación según los términos de tu proveedor de teselas.

Consejos de rendimiento

Utiliza teselas vectoriales siempre que sea posible para mejorar el rendimiento y reducir el tamaño de las descargas.
Considera el uso de caché de teselas para escenarios sin conexión.
Usa niveles de zoom adecuados para tu caso de uso.
Supervisa el uso de red si utilizas conexiones de datos de pago.

Próximos pasos

Una vez configurado correctamente MapLibre, puedes utilizar el componente MapLibreMapView de MapConductor con la API unificada.