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.

Nota: Si tu entorno de desarrollo emplea una versión diferente de Android Studio o Gradle, quizás debas modificar los pasos en función de tu entorno. Para obtener más información sobre las versiones de Android Studio y Gradle, consulta la Compatibilidad del complemento de Android para Gradle y Android Studio.

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.
  Nota: Si eliges usar un emulador de Android, asegúrate de elegir un dispositivo que muestre el ícono de Play, , en la columna Play Store. Este ícono indica que estos perfiles satisfacen el CTS y pueden usar imágenes del sistema que incluyan la app de Play Store:

  

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.

     Nota: Si no sabes cuál es la versión de SDK que deberías elegir, selecciona el vínculo Ayúdame a elegir para mostrar la información de distribución de los SDK de Android compatibles. Por ejemplo, si eliges la API para Android nivel 21 ("Lollipop"; Android 5.0), tu app debería ejecutarse en más del 99% de los dispositivos Android.

   • 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.

   Precaución: El archivo AndroidManifest.xml contiene instrucciones para obtener una clave de API de Google Maps y agregarla a tu archivo local.properties. No agregues tu clave de API al archivo local.properties, ya que allí se almacenará de forma menos segura. En cambio, sigue las instrucciones que se incluyen en la sección Configura tu proyecto de Google Cloud para crear un proyecto en esta plataforma y configurar una clave de API.

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:

Paso 1

Consola

1. En la consola de Google Cloud, en la página del selector de proyectos, haz clic en Crear proyecto para comenzar a crear un proyecto nuevo de Cloud.

   Ir a la página del selector de proyectos

2. Asegúrate de que la facturación esté habilitada para tu proyecto de Cloud. Confirma que la facturación esté habilitada para tu proyecto.

   Google Cloud ofrece una prueba con un cargo de USD 0.00. La prueba vence al final de un plazo de 90 días, o bien después de que la cuenta acumule USD 300 en cargos, lo que ocurra primero. Puedes cancelar la prueba en cualquier momento. Google Maps Platform incluye un crédito mensual recurrente de USD 200. Para obtener más información, consulta Créditos de la cuenta de facturación y Facturación.

SDK de Cloud

gcloud projects create "PROJECT"

Obtén más información sobre el SDK de Google Cloud, la instalación del SDK de Cloud y los siguientes comandos:

• gcloud projects create

Nota: Si no planeas conservar los recursos que creaste en un ejercicio de aprendizaje, crea un proyecto nuevo en lugar de seleccionar uno existente. Cuando termines el ejercicio, puedes borrar el proyecto y quitar todos los recursos asociados con él.

Paso 2

Para usar Google Maps Platform, debes habilitar las APIs o los SDKs que planeas usar con tu proyecto.

Consola

Habilitar el SDK de Maps para Android

SDK de Cloud

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

Obtén más información sobre el SDK de Google Cloud, la instalación del SDK de Cloud y los siguientes comandos:

• gcloud services enable
• gcloud services disable

Paso 3

En este paso, solo se realiza el proceso de creación de la clave de API. Si usas la clave de API en producción, te recomendamos que la restrinjas. Puedes encontrar más información en la página Usar claves de API específica del producto.

La clave de API es un identificador único que se utiliza para autenticar solicitudes asociadas a tu proyecto con fines de uso y facturación. Debes tener, al menos, una clave de API asociada a tu proyecto.

Para crear una clave de API, sigue estos pasos:

Consola

1. Ve a la página Google Maps Platform > Credenciales.

   Ir a la página Credenciales

2. En la página Credenciales, haz clic en Crear credenciales > Clave de API.
   El diálogo Se creó la clave de API mostrará la clave de API que acabas de crear.
3. Haz clic en Cerrar.
   La nueva clave de API aparecerá en la página Credenciales debajo de Claves de API.
   (Recuerda restringir la clave de API antes de utilizarla en producción).

SDK de Cloud

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

Obtén más información sobre el SDK de Google Cloud, la instalación del SDK de Cloud y los siguientes comandos:

• gcloud alpha services api-keys create

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.

Nota: Consulta la documentación del complemento Secrets Gradle para Android en GitHub para conocer los requisitos del sistema y las instrucciones de instalación más recientes.

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.
   Nota: Si el archivo secrets.properties no existe, créalo en la misma carpeta en la que se encuentra el archivo local.properties.

   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.

   Nota: Ingresa el código como se muestra. No reemplaces DEFAULT_API_KEY por tu clave de API.

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

   Nota: 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 para autenticar varias APIs basadas en Google Maps en la plataforma de Android, incluido el SDK de Maps para 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 en 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.

10. En Android Studio, abre el archivo build.gradle.kts o build.gradle a nivel del módulo y edita la propiedad secrets. Si la propiedad secrets no existe, agrégala.

    Edita las propiedades del complemento para establecer propertiesFileName en secrets.properties, defaultPropertiesFileName en local.defaults.properties y cualquier otra propiedad.

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

Nota: La versión exacta puede cambiar según la versión actual del SDK de Maps para Android.

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.