Configuración de Google Maps

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

Requisitos previos

Entorno de desarrollo Android
Cuenta de Google Cloud Console
Maps SDK for Android habilitado en tu proyecto de Google Cloud

Pasos de configuración

1. Configuración en Google Cloud Console

Accede a la Google Cloud Console.
Crea un nuevo proyecto o selecciona uno existente.
Habilita la API Maps SDK for Android.
Ve a Credenciales y crea una clave de API.
Restringe la clave de API al nombre de paquete y huella SHA-1 de tu app.

2. Configuración de Gradle

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

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

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

// (root)/build.gradle
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:

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

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

dependencies {
    // Google Maps SDK (versión gestionada mediante libs.versions.toml)
    implementation("com.google.android.gms:play-services-maps:20.0.0")

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

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

plugins {
    // ... otros plugins
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
}

dependencies {
    // Google Maps SDK (versión gestionada mediante libs.versions.toml)
    implementation "com.google.android.gms:play-services-maps:20.0.0"

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

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

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

Añade el marcador de posición de la clave de API de Google Maps en tu AndroidManifest.xml:

<application>
    <!-- Google Maps API Key -->
    <meta-data
        android:name="com.google.android.geo.API_KEY"
        android:value="${GOOGLE_MAPS_API_KEY}" />

    <!-- Añade permisos de localización -->
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
</application>

4. Configuración de la clave de API

Añade la clave de API real a tu archivo secrets.properties (créalo si no existe):

GOOGLE_MAPS_API_KEY=tu_clave_real_de_google_maps_aquí

Importante:

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

secrets.properties

5. Configuración de ProGuard / R8 (si aplica)

Si utilizas ProGuard/R8, añade estas reglas a tu archivo proguard-rules.pro:

# Google Play Services
-keep class com.google.android.gms.maps.** { *; }
-keep interface com.google.android.gms.maps.** { *; }
-dontwarn com.google.android.gms.**

Verificación

Para verificar la configuración de Google Maps:

Compila y ejecuta la app.
Comprueba que el mapa se muestra sin errores.
Verifica que los permisos de localización funcionan correctamente.
Prueba interacciones básicas con el mapa (zoom, desplazamiento).

@Composable
fun TestGoogleMaps() {
    val mapState = rememberGoogleMapViewState(
        cameraPosition =
            MapCameraPosition(
                position = GeoPoint.fromLatLong(0, 0),
                zoom = 3,
            ),
    )

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

Resultado de TestGoogleMaps

Solución de problemas

Problemas comunes

El mapa no se muestra (pantalla gris)

Verifica que la clave de API en secrets.properties sea correcta.
Comprueba que Maps SDK for Android esté habilitado en Google Cloud Console.
Asegúrate de que las restricciones de la clave coincidan con el nombre de paquete y la huella SHA-1 de tu app.

Errores de clave de API en los logs

Revisa de nuevo el valor de la clave.
Comprueba que la clave siga activa.
Verifica las restricciones de la clave en Google Cloud Console.

Errores de compilación

Asegúrate de que la dependencia de Play Services Maps coincida con la configuración de tu proyecto.
Verifica que el archivo secrets.properties exista y esté correctamente formateado.
Comprueba que secrets.properties no esté siendo ignorado accidentalmente en tu entorno local.

Próximos pasos

Una vez configurado correctamente el SDK de Google Maps, puedes usar el componente GoogleMapView de MapConductor tal como se describe en la documentación del componente Map View.