Configuración de Google Maps

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

Tip

MapConductor proporciona una capa de API unificada sobre los SDKs de mapas existentes. Debes configurar el SDK de Google Maps de forma independiente antes de usar la integración de Google Maps de 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

1. Accede a la Google Cloud Console.
2. Crea un nuevo proyecto o selecciona uno existente.
3. Habilita la API Maps SDK for Android.
4. Ve a Credenciales y crea una clave de API.
5. 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)

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

Groovy (build.gradle)

// (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)

App/build.gradle.kts

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:19.2.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-googlemaps")
}

Groovy (build.gradle)

App/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:19.2.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-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:

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

secrets.properties

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.

.gitignore

secrets.properties

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

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

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:

1. Compila y ejecuta la app.
2. Comprueba que el mapa se muestra sin errores.
3. Verifica que los permisos de localización funcionan correctamente.
4. 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
    }
}

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.