Guía de inicio rápido del SDK de Maps para Android

Crea una app para Android que muestre un mapa con la plantilla de Google Maps Views para Android Studio. Si deseas configurar un proyecto existente de Android Studio, consulta Configura un proyecto de Android Studio.

Esta guía de inicio rápido está dirigida a los desarrolladores familiarizados con los conceptos básicos del desarrollo de Android con Kotlin o Java.

Acerca del entorno de desarrollo

Esta guía de inicio rápido se desarrolló utilizando Android Studio Hedgehog y el complemento de Android para Gradle versión 8.2.

Cómo configurar un dispositivo Android

Para ejecutar una app que usa el SDK de Maps para Android, debes implementarla en un dispositivo Android o en un emulador de Android que se base en Android 5.0 o posterior, y que incluya las APIs 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 un emulador de Android, puedes crear un dispositivo virtual y, luego, instalar el emulador usando el Administrador de dispositivos virtuales de Android (AVD) incluido con Android Studio.

Crea un proyecto de Google Maps en Android Studio

El procedimiento para crear un proyecto de Google Maps en Android Studio se modificó en Android Studio Flamingo y las versiones posteriores.

1. Abre Android Studio y haz clic en New Project en la ventana Welcome to Android Studio.

2. En la ventana New Project, en la categoría Phone and Tablet, selecciona No Activity y, luego, haz clic en Next.

3. Completa el formulario New Project:

   • En la sección Language, selecciona Java o Kotlin. Ambos lenguajes son totalmente compatibles con el SDK de Maps para Android. Para obtener información sobre Kotlin, consulta Desarrolla apps para Android con Kotlin.

   • Configura Minimum SDK con una versión del SDK de Android que sea compatible con tu dispositivo de prueba. Debes seleccionar una versión superior a la mínima requerida por el SDK de Maps para Android versión 19.0.x, que es la API nivel 21 (Android 5.0, "Lollipop") o una posterior. Consulta las Notas de versión para obtener la información más reciente sobre los requisitos de la versión del SDK.

   • Establece Build configuration language en Kotlin DSL o Groovy DSL. En los procedimientos siguientes se muestran fragmentos de ambos lenguajes de configuración de compilación.

4. Haz clic en Finish.

   Android Studio inicia Gradle y compila tu proyecto. Espera un momento.

5. Agrega Google Maps Views Activity:

   1. Haz clic con el botón derecho sobre la carpeta app de tu proyecto.

   2. Selecciona New > Google > Google Maps Views Activity.

      

   3. En el cuadro de diálogo New Android Activity, selecciona la casilla de verificación Launcher Activity.

   4. Selecciona Finish.

      Para obtener más información, consulta Cómo agregar código desde una plantilla.

6. Cuando se completa la compilación, Android Studio abre los archivos AndroidManifest.xml y MapsActivity. Es posible que tu actividad tenga un nombre diferente, pero es la que configuraste en el paso anterior.

Configura tu proyecto de Google Cloud

Completa los pasos de configuración necesarios en la consola de Cloud. Para ello, haz clic en las siguientes pestañas:

gcloud projects create "PROJECT"

gcloud services enable \
    --project "PROJECT" \
    "maps-android-backend.googleapis.com"

gcloud alpha services api-keys create \
    --project "PROJECT" \
    --display-name "DISPLAY_NAME"

Agrega la clave de API a tu app

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 secrets.properties, que se encuentra en el directorio raíz de tu proyecto. Para obtener más información sobre el archivo secrets.properties, consulta los archivos de propiedades de Gradle.

Para optimizar esta tarea, te recomendamos que uses el complemento Secrets Gradle para Android.

Si deseas instalar el complemento Secrets Gradle para Android en tu proyecto de Google Maps, haz lo siguiente:

1. En Android Studio, abre tu archivo build.gradle.kts o build.gradle de nivel superior y agrega el siguiente código al elemento dependencies en buildscript.

   Kotlin

   buildscript {
       dependencies {
           classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1")
       }
   }

   Groovy

   buildscript {
       dependencies {
           classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1"
       }
   }
   

2. Abre el archivo build.gradle.kts o build.gradle a nivel del módulo y agrega el siguiente código al elemento plugins.

   Kotlin

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

   Groovy

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

3. En tu archivo build.gradle.kts o build.gradle a nivel del módulo, asegúrate de que targetSdk y compileSdk estén establecidos en 34.
4. Guarda el archivo y sincroniza tu proyecto con Gradle.
5. Abre el archivo secrets.properties en tu directorio de nivel superior y agrega el siguiente código. Reemplaza YOUR_API_KEY por tu clave de API. Almacena tu clave en este archivo, ya que secrets.properties no se registra en un sistema de control de versión.

   MAPS_API_KEY=YOUR_API_KEY

6. Guarda el archivo.

7. Crea el archivo local.defaults.properties en tu directorio de nivel superior, en la misma carpeta en la que se encuentra el archivo secrets.properties, y agrega el siguiente código.

   MAPS_API_KEY=DEFAULT_API_KEY

   El propósito de este archivo es proporcionar una ubicación de copia de seguridad de la clave de API si no se encuentra el archivo secrets.properties, de modo que no fallen las compilaciones. Esto puede ocurrir si clonas la app desde un sistema de control de versión que omite secrets.properties y aún no creaste un archivo secrets.properties localmente para proporcionar tu clave de API.

8. Guarda el archivo.
9. En tu archivo AndroidManifest.xml, ve a com.google.android.geo.API_KEY y actualiza android:value attribute. Si la etiqueta <meta-data> no existe, créala como un elemento secundario de la etiqueta <application>.

   <meta-data
       android:name="com.google.android.geo.API_KEY"
       android:value="${MAPS_API_KEY}" />

   Note: com.google.android.geo.API_KEY is the recommended metadata name for the API key. A key with this name can be used to authenticate to multiple Google Maps-based APIs on the Android platform, including the Maps SDK for Android. For backwards compatibility, the API also supports the name com.google.android.maps.v2.API_KEY. This legacy name allows authentication to the Android Maps API v2 only. An application can specify only one of the API key metadata names. If both are specified, the API throws an exception.

10. In Android Studio, open your module-level build.gradle.kts or build.gradle file and edit the secrets property. If the secrets property does not exist, add it.

    Edit the properties of the plugin to set propertiesFileName to secrets.properties, set defaultPropertiesFileName to local.defaults.properties, and set any other properties.

    Kotlin

    secrets {
        // To add your Maps API key to this project:
        // 1. If the secrets.properties file does not exist, create it in the same folder as the local.properties file.
        // 2. Add this line, where YOUR_API_KEY is your API key:
        //        MAPS_API_KEY=YOUR_API_KEY
        propertiesFileName = "secrets.properties"
    
        // A properties file containing default secret values. This file can be
        // checked in version control.
        defaultPropertiesFileName = "local.defaults.properties"
    
        // Configure which keys should be ignored by the plugin by providing regular expressions.
        // "sdk.dir" is ignored by default.
        ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore"
        ignoreList.add("sdk.*")       // Ignore all keys matching the regexp "sdk.*"
    }
            

    Groovy

    secrets {
        // To add your Maps API key to this project:
        // 1. If the secrets.properties file does not exist, create it in the same folder as the local.properties file.
        // 2. Add this line, where YOUR_API_KEY is your API key:
        //        MAPS_API_KEY=YOUR_API_KEY
        propertiesFileName = "secrets.properties"
    
        // A properties file containing default secret values. This file can be
        // checked in version control.
        defaultPropertiesFileName = "local.defaults.properties"
    
        // Configure which keys should be ignored by the plugin by providing regular expressions.
        // "sdk.dir" is ignored by default.
        ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore"
        ignoreList.add("sdk.*")       // Ignore all keys matching the regexp "sdk.*"
    }
            

Observa el código

Examina el código que proporciona la plantilla. En particular, observa los siguientes archivos de tu proyecto de Android Studio.

Archivo de actividad en Maps

El archivo de actividad en Maps contiene la actividad principal de la app y el código para administrar y mostrar el mapa. De forma predeterminada, el archivo que define la actividad se denomina MapsActivity.java o, si utilizas el lenguaje Kotlin para tu app, MapsActivity.kt.

Estos son los elementos principales de la actividad en Maps:

• El objeto SupportMapFragment administra el ciclo de vida del mapa y es el elemento principal de la IU de la app.

• El objeto GoogleMap proporciona acceso a la vista y los datos del mapa. Es la clase principal del SDK de Maps para Android. En la guía de objetos de mapas, se describen los objetos SupportMapFragment y GoogleMap en más detalle.

• La función moveCamera centra el mapa en las coordenadas LatLng para Sídney, Australia. Normalmente, cuando agregas un mapa, lo primero que debes configurar es su ubicación y los parámetros de la cámara, como el ángulo de vista, la orientación del mapa y el nivel de zoom. Consulta la guía Cámara y vista para obtener más información.

• La función addMarker agrega un marcador a las coordenadas de Sídney. Para obtener más información, consulta la guía Marcadores.

Archivo Gradle del módulo

El archivo build.gradle.kts del módulo incluye la siguiente dependencia de Maps, requerida por el SDK de Maps para Android.

dependencies {

    // Maps SDK for Android
    implementation("com.google.android.gms:play-services-maps:19.0.0")
}

Para obtener más información sobre cómo administrar la dependencia de Maps, consulta la guía del control de versiones.

Archivo de diseño XML

El archivo activity_maps.xml es el archivo de diseño XML que define la estructura de la IU de la app. Se ubica en el directorio res/layout. El archivo activity_maps.xml declara un fragmento que incluye los siguientes elementos:

• tools:context establece la actividad predeterminada del fragmento en MapsActivity, que se define en el archivo de actividad en Maps.
• android:name establece el nombre de clase del fragmento en SupportMapFragment, que es el tipo de fragmento que se usa en el archivo de actividad en Maps.

El archivo de diseño XML contiene el siguiente código:

<fragment xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:map="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:id="@+id/map"
    android:name="com.google.android.gms.maps.SupportMapFragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MapsActivity" />

Cómo implementar y ejecutar la app

Cuando ejecutes la app correctamente, se mostrará un mapa centrado en Sídney, Australia, con un marcador en la ciudad, tal como se ve en la siguiente captura de pantalla.

Para implementar y ejecutar la app, sigue estos pasos:

1. En Android Studio, haz clic en la opción Run del menú (o en el ícono del botón de reproducción) para ejecutar tu app.
2. Cuando se te solicite que selecciones un dispositivo, elige una de las siguientes opciones:
   • Selecciona el dispositivo Android conectado a tu computadora.
   • Como alternativa, haz clic en el botón de selección Launch Emulator y elige el dispositivo virtual que configuraste.
3. Haz clic en OK. Android Studio iniciará Gradle para compilar tu app y, luego, mostrará los resultados en tu dispositivo o emulador. Es posible que la app demore varios minutos en iniciarse.

Próximos pasos

• Configura un mapa: En este documento, se explica cómo configurar los parámetros iniciales y de tiempo de ejecución de tu mapa, como la posición de la cámara, el tipo de mapa, los componentes de la IU y los gestos.

• Agrega un mapa a tu app para Android (Kotlin): Este codelab te guiará por una app que muestra algunas funciones adicionales del SDK de Maps para Android.

• Usa la biblioteca Maps Android KTX: Esta biblioteca de extensiones de Kotlin (KTX) te permite aprovechar varias funciones de este lenguaje mientras usas el SDK de Maps para Android.