Cómo configurar un proyecto de Android Studio

En esta página, se describe cómo configurar un proyecto de Android Studio para utilizar el SDK de Maps para Android sin la plantilla de Google Maps que se detalla en la Guía de inicio rápido.

La plantilla de Google Maps configura automáticamente un proyecto de Android Studio nuevo y agrega un mapa básico. Sin embargo, también puedes agregar un mapa a un proyecto de Android que utilice una plantilla de Android Studio diferente. Para ello, debes configurar tu proyecto manualmente y, luego, agregar el mapa.

Paso 1: Configura Android Studio

  1. Se requiere Android Studio Arctic Fox o una versión posterior. Si aún no lo tienes, descárgalo y, luego, instálalo.
  2. Verifica que estés utilizando la versión 7.0 o posterior del complemento de Android para Gradle en Android Studio.

Paso 2. Configura el SDK

La biblioteca del SDK de Maps para Android está disponible a través del repositorio Maven de Google. Para agregar el SDK a tu app, haz lo siguiente:

  1. En el archivo settings.gradle de nivel superior, incluye el portal de complementos de Gradle, el repositorio Maven de Google y el repositorio central de Maven debajo del bloque pluginManagement. El bloque pluginManagement debe aparecer antes que cualquier otra sentencia en la secuencia de comandos.
    pluginManagement {
        repositories {
            gradlePluginPortal()
            google()
            mavenCentral()
        }
    } 
  2. En el archivo settings.gradle de nivel superior, incluye el repositorio de Maven de Google y el repositorio central de Maven debajo del bloque dependencyResolutionManagement:
    dependencyResolutionManagement {
        repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
        repositories {
            google()
            mavenCentral()
        }
    } 
  3. En el archivo build.gradle a nivel del módulo, agrega la dependencia de Servicios de Google Play para el SDK de Maps para Android.
    dependencies {
        implementation 'com.google.android.gms:play-services-maps:18.1.0'
        // ...
    } 
  4. En tu archivo build.gradle a nivel del módulo, configura compileSdk y minSdk con los siguientes valores:
    android {
        compileSdk 31
    
        defaultConfig {
            minSdk 19
            // ...
        }

Paso 3: Agrega tu clave de API al proyecto

En esta sección, se describe cómo almacenar tu clave de API para que tu app pueda hacer referencia a ella de manera más segura. No debes incluir la clave de API en el sistema de control de versión, por lo que te recomendamos almacenarla en el archivo local.properties, que se encuentra en el directorio raíz de tu proyecto. Para obtener más información sobre el archivo local.properties, consulta los archivos de propiedades de Gradle.

A fin de optimizar esta tarea, te recomendamos usar el complemento Secrets Gradle para Android. Para instalar el complemento y almacenar tu clave de API, haz lo siguiente:

  1. En Android Studio, abre el archivo build.gradle a nivel del proyecto y agrega el siguiente código al elemento dependencies en buildscript.
    plugins {
        // ...
        id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' version '2.0.1' apply false
    }
  2. A continuación, abre el archivo build.gradle a nivel del módulo y agrega el siguiente código al elemento plugins.
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
        
  3. Guarda el archivo y sincroniza tu proyecto con Gradle.
  4. Abre el archivo local.properties en el directorio de nivel de proyecto y, luego, agrega el siguiente código. Reemplaza YOUR_API_KEY por tu clave de API.
    MAPS_API_KEY=YOUR_API_KEY
        
  5. Guarda el archivo.
  6. En tu archivo AndroidManifest.xml, ve a com.google.android.geo.API_KEY y actualiza android:value attribute de la siguiente manera:
    <meta-data
        android:name="com.google.android.geo.API_KEY"
        android:value="${MAPS_API_KEY}" />
        

Nota: Como se mostró anteriormente, com.google.android.geo.API_KEY es el nombre de metadatos recomendado para la clave de API. Se puede utilizar una clave con este nombre a fin de autenticar varias APIs basadas en Google Maps en la plataforma de Android, incluido Maps SDK for Android. Respecto de la retrocompatibilidad, la API también admite el nombre com.google.android.maps.v2.API_KEY. Este nombre heredado solo permite la autenticación de la versión 2 de la API de Google Maps para Android. Una aplicación puede especificar solo uno de los nombres de metadatos de la clave de API. Si se especifican ambos, la API arrojará una excepción.

Paso 4: Actualiza el manifiesto de la app

En esta sección, se explica qué parámetros debes agregar al archivo AndroidManifest.xml.

Número de versión de Servicios de Google Play

Agrega la siguiente declaración en el elemento application. Esto incorporará la versión de Servicios de Google Play con la que se compiló la app.

<meta-data
    android:name="com.google.android.gms.version"
    android:value="@integer/google_play_services_version" />

Permiso de ubicación

Si tu app necesita acceder a la ubicación del usuario, debes solicitar el permiso de ubicación en el archivo AndroidManifest.xml. Las opciones son ACCESS_FINE_LOCATION, que proporciona la ubicación exacta del dispositivo, y ACCESS_COARSE_LOCATION, que es menos precisa. Para obtener más detalles, consulta la guía Datos de ubicación.

Para solicitar el permiso ACCESS_FINE_LOCATION, agrega este código al elemento manifest:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>

Permiso de almacenamiento externo

Si planeas utilizar la versión 8.3 o una posterior del SDK de Servicios de Google Play, no necesitas el permiso WRITE_EXTERNAL_STORAGE. Si planeas usar versiones anteriores del SDK de Servicios de Google Play, debes solicitar el permiso WRITE_EXTERNAL_STORAGE en el elemento manifest.

<uses-permission
        android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

Biblioteca Apache HTTP Legacy

Si utilizas com.google.android.gms:play-services-maps:16.0.0 o versiones anteriores, y tu app planea usar el nivel de API 28 (Android 9.0) o uno posterior, debes incluir la siguiente declaración en el elemento <application> del archivo AndroidManifest.xml. De lo contrario, omite esta declaración.

<uses-library
    android:name="org.apache.http.legacy"
    android:required="false" />

Paso 5: Configura un dispositivo Android

Para ejecutar una app que usa el SDK de Maps para Android, debes implementarla en un dispositivo Android o en un Android Emulator que se base en Android 4.0 o posterior y que incluya las API de Google.

  • Si deseas usar un dispositivo Android, sigue las instrucciones que se indican en Cómo ejecutar apps en un dispositivo de hardware.
  • Para usar Android Emulator, puedes crear un dispositivo virtual y, luego, instalar el emulador mediante el Administrador de dispositivos virtuales de Android (AVD) incluido con Android Studio.

Próximos pasos

Una vez que tu proyecto esté configurado, podrás agregar un mapa.