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 Android emulador de aplicaciones que se basa en Android 5.0 o una versión posterior, e incluye 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.
Abre Android Studio y haz clic en New Project en Ventana Welcome to Android Studio.
En la ventana New Project, en la categoría Phone and Tablet, selecciona No Activity y, luego, haz clic en Next.
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 Versión 19.0.x del SDK de Maps para Android que corresponde al nivel de API 21 de Android ("Lollipop"; Android 5.0) o 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.
Haz clic en Finish.
Android Studio inicia Gradle y compila tu proyecto. Espera un momento.
Agrega Google Maps Views Activity:
- Haz clic con el botón derecho sobre la carpeta
app
de tu proyecto. Selecciona New > Google > Google Maps Views Activity.
En el cuadro de diálogo New Android Activity, selecciona la casilla de verificación Launcher Activity.
Selecciona Finish.
Para obtener más información, consulta Cómo agregar código desde una plantilla.
- Haz clic con el botón derecho sobre la carpeta
Cuando se completa la compilación, Android Studio abre los archivos
AndroidManifest.xml
yMapsActivity
. 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:
Paso 1
Consola
-
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.
-
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:
Paso 2
Para usar Google Maps Platform, debes habilitar las APIs o los SDKs que planeas usar con tu proyecto.
Consola
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:
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
-
Ve a la página Google Maps Platform > Credenciales.
-
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. -
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:
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:
-
En Android Studio, abre tu archivo
build.gradle.kts
obuild.gradle
de nivel superior y agrega el siguiente código al elementodependencies
enbuildscript
.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" } }
-
Abre el archivo
build.gradle.kts
obuild.gradle
a nivel del módulo y agrega el siguiente código al elementoplugins
.Kotlin
plugins { // ... id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") }
Groovy
plugins { // ... id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' }
- En el archivo
build.gradle.kts
obuild.gradle
a nivel del módulo, asegúrate de que quetargetSdk
ycompileSdk
están configurados a 34. - Guarda el archivo y sincroniza tu proyecto con Gradle.
-
Abre el archivo
secrets.properties
en tu directorio de nivel superior y agrega el siguiente código. ReemplazaYOUR_API_KEY
por tu clave de API. Almacena tu clave en este archivo, ya quesecrets.properties
no se registra en un sistema de control de versión.MAPS_API_KEY=YOUR_API_KEY
- Guarda el archivo.
-
Crea el archivo
local.defaults.properties
en tu directorio de nivel superior, en la misma carpeta en la que se encuentra el archivosecrets.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 omitesecrets.properties
y aún no creaste un archivosecrets.properties
localmente para proporcionar tu clave de API. - Guarda el archivo.
-
En tu archivo
AndroidManifest.xml
, ve acom.google.android.geo.API_KEY
y actualizaandroid: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 namecom.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. -
In Android Studio, open your module-level
build.gradle.kts
orbuild.gradle
file and edit thesecrets
property. If thesecrets
property does not exist, add it.Edit the properties of the plugin to set
propertiesFileName
tosecrets.properties
, setdefaultPropertiesFileName
tolocal.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 objetosSupportMapFragment
yGoogleMap
en más detalle.La función
moveCamera
centra el mapa en las coordenadasLatLng
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 directoriores/layout
. El archivoactivity_maps.xml
declara un fragmento que incluye los siguientes elementos:tools:context
establece la actividad predeterminada del fragmento enMapsActivity
, que se define en el archivo de actividad en Maps.android:name
establece el nombre de clase del fragmento enSupportMapFragment
, 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:
- 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.
- 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.
- 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.
Salvo que se indique lo contrario, el contenido de esta página está sujeto a la licencia Atribución 4.0 de Creative Commons, y los ejemplos de código están sujetos a la licencia Apache 2.0. Para obtener más información, consulta las políticas del sitio de Google Developers. Java es una marca registrada de Oracle o sus afiliados.
Última actualización: 2024-08-22 (UTC)
[{ "type": "thumb-down", "id": "missingTheInformationINeed", "label":"Falta la información que necesito" },{ "type": "thumb-down", "id": "tooComplicatedTooManySteps", "label":"Muy complicado o demasiados pasos" },{ "type": "thumb-down", "id": "outOfDate", "label":"Desactualizado" },{ "type": "thumb-down", "id": "translationIssue", "label":"Problema de traducción" },{ "type": "thumb-down", "id": "samplesCodeIssue", "label":"Problema con las muestras o los códigos" },{ "type": "thumb-down", "id": "otherDown", "label":"Otro" }] [{ "type": "thumb-up", "id": "easyToUnderstand", "label":"Fácil de comprender" },{ "type": "thumb-up", "id": "solvedMyProblem", "label":"Resolvió mi problema" },{ "type": "thumb-up", "id": "otherUp", "label":"Otro" }]