Skip to content
MapConductor

Configuración de Mapbox

Esta sección explica el proceso de configuración del SDK de Mapbox Maps junto con MapConductor.

Requisitos previos

Section titled “Requisitos previos”
  • Entorno de desarrollo Android
  • Cuenta de Mapbox
  • Token de acceso de Mapbox

Pasos de configuración

Section titled “Pasos de configuración”

1. Configuración de la cuenta de Mapbox

Section titled “1. Configuración de la cuenta de Mapbox”
  1. Crea una cuenta en Mapbox.
  2. Accede a tu panel de cuenta de Mapbox.
  3. Navega a Access tokens.
  4. Crea un nuevo token de acceso o utiliza el token público por defecto.
  5. Copia el token de acceso para usarlo en tu aplicación.

2. Configuración de Gradle

Section titled “2. Configuración de Gradle”

Asegúrate de que el repositorio Maven de Mapbox esté configurado (este repositorio ya lo incluye en 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")
        }
    }
}

A continuación, añade el Secrets Gradle Plugin en el build.gradle.kts o build.gradle de la raíz del proyecto:

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

Después, añade las dependencias y aplica el plugin en el build.gradle.kts o build.gradle del módulo de la app:

App/build.gradle.kts
plugins {
    // ... otros plugins
    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
}


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


    // 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-mapbox")
}

El Secrets Gradle Plugin lee automáticamente el archivo secrets.properties y puede inyectar los valores en AndroidManifest.xml en tiempo de compilación.

3. Configuración de AndroidManifest

Section titled “3. Configuración de AndroidManifest”

Añade el marcador de posición del token de acceso de Mapbox en tu AndroidManifest.xml:

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


    <!-- Añade permisos de internet y ubicación -->
    <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 del token de acceso

Section titled “4. Configuración del token de acceso”

Añade el token de acceso real a tu archivo secrets.properties:

secrets.properties
MAPBOX_ACCESS_TOKEN=tu_token_real_de_acceso_de_mapbox_aquí

Importante:

  • No subas el archivo secrets.properties al control de versiones. Añádelo a .gitignore.
  • El Secrets Gradle Plugin reemplaza automáticamente ${MAPBOX_ACCESS_TOKEN} en tu AndroidManifest.xml por el valor real.
  • En entornos de CI/CD puedes utilizar variables de entorno u otros métodos seguros para proporcionar estos valores.
.gitignore
secrets.properties

5. Configuración de estilos

Section titled “5. Configuración de estilos”

Mapbox permite estilos de mapa personalizados. Puedes utilizar estilos integrados o crear los tuyos, pero esta configuración se realiza en el código de tus composables y no forma parte de la configuración básica descrita aquí.

Verificación

Section titled “Verificación”

Para verificar la configuración de Mapbox:

  1. Compila y ejecuta la app.
  2. Comprueba que el mapa se muestra con el estilo de Mapbox.
  3. Prueba las interacciones de mapa (zoom, desplazamiento, rotación).
@Composable
fun TestMapbox() {
    val state =
        rememberMapboxMapViewState(
            cameraPosition =
                MapCameraPosition(
                    position = GeoPoint.fromLatLong(0.0, 0.0),
                    zoom = 3.0,
                ),
        )


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

Resultado de TestMapbox

Solución de problemas

Section titled “Solución de problemas”

Problemas comunes

Section titled “Problemas comunes”

El mapa no se muestra (pantalla en blanco)

  • Verifica que el token de acceso en secrets.properties sea correcto.
  • Comprueba que el token no haya expirado.
  • Asegura la conectividad a internet para la carga de teselas.

Errores de token de acceso

  • Revisa de nuevo el valor del token (normalmente empieza por pk.).
  • Verifica los permisos del token en el panel de Mapbox.
  • Comprueba que los ámbitos del token incluyan los permisos necesarios.

Errores de compilación

  • Asegúrate de que las coordenadas del SDK de Mapbox coincidan con la configuración de tu proyecto.
  • Verifica que estás utilizando la variante NDK27 adecuada.
  • Comprueba que el archivo secrets.properties exista y contenga el token.

Próximos pasos

Section titled “Próximos pasos”

Una vez configurado correctamente el SDK de Mapbox Maps, puedes usar el componente MapboxMapView de MapConductor con la API unificada.