Crea una app para Android que muestre un mapa con la plantilla de Google Maps para Android Studio. Si deseas configurar un proyecto existente de Android Studio, consulta Cómo configurar un proyecto.
Esta guía de inicio rápido está dirigida a los desarrolladores familiarizados con los conceptos básicos del desarrollo de Android con Java o Kotlin.
Cómo configurar el entorno de desarrollo
- Se requiere Android Studio Arctic Fox o una versión posterior. Si aún no lo tienes, descárgalo y, luego, instálalo.
- Verifica que estés utilizando la versión 7.0 o posterior del complemento de Android para Gradle en 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 Android Emulator que se base en Android 4.0 o posterior y que incluya las API de Google.
- Si deseas utilizar 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.
Crea un proyecto de Google Maps en Android Studio
Abre Android Studio y haz clic en Create New Project en la ventana Welcome to Android Studio.
En la ventana New Project, en la categoría Phone and Tablet, selecciona Google Maps Activity y, luego, haz clic en Next.
Completa el formulario Google Maps Activity:
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 18.0.x, que actualmente es la API nivel 19 (Android 4.4, KitKat) o una posterior. Consulta las Notas de versión a fin de obtener la información más reciente sobre los requisitos de la versión del SDK.
Haz clic en Finish.
Android Studio inicia Gradle y compila tu proyecto. Espera un momento.
Cuando se completa la compilación, Android Studio abre los archivos
AndroidManifest.xml
yMapsActivity
. Es posible que tu actividad tenga un nombre diferente, pero será el mismo proyecto que configuraste en la etapa anterior.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 archivoAndroidManifest.xml
, ya que allí se almacenará de forma menos segura. En cambio, sigue las instrucciones que se indican en las próximas secciones para crear un proyecto de Cloud 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
Console
-
En Google Cloud Console, 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 API o los SDK que planeas usar con tu proyecto.
Console
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:
Console
-
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 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:
- En Android Studio, abre el archivo
build.gradle
a nivel del proyecto y agrega el siguiente código al elementodependencies
enbuildscript
.plugins { // ... id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' version '2.0.1' apply false }
- A continuación, abre el archivo
build.gradle
a nivel del módulo y agrega el siguiente código al elementoplugins
.id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
- Guarda el archivo y sincroniza tu proyecto con Gradle.
- Abre el archivo
local.properties
en el directorio de nivel de proyecto y, luego, agrega el siguiente código. ReemplazaYOUR_API_KEY
por tu clave de API.MAPS_API_KEY=YOUR_API_KEY
- Guarda el archivo.
- En tu archivo
AndroidManifest.xml
, ve acom.google.android.geo.API_KEY
y actualiza elandroid: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 API 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.
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.
El archivo de actividad en Maps incluye el siguiente código:
Java
import android.os.Bundle; import androidx.appcompat.app.AppCompatActivity; import com.google.android.gms.maps.CameraUpdateFactory; import com.google.android.gms.maps.GoogleMap; import com.google.android.gms.maps.OnMapReadyCallback; import com.google.android.gms.maps.SupportMapFragment; import com.google.android.gms.maps.model.LatLng; import com.google.android.gms.maps.model.MarkerOptions; public class MapsActivity extends AppCompatActivity implements OnMapReadyCallback { private GoogleMap mMap; @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_maps); // Obtain the SupportMapFragment and get notified when the map is ready to be used. SupportMapFragment mapFragment = (SupportMapFragment) getSupportFragmentManager() .findFragmentById(R.id.map); mapFragment.getMapAsync(this); } /** * Manipulates the map once available. * This callback is triggered when the map is ready to be used. * This is where we can add markers or lines, add listeners or move the camera. In this case, * we just add a marker near Sydney, Australia. * * If Google Play services is not installed on the device, the user will be prompted to install * it inside the SupportMapFragment. This method will only be triggered once the user has * installed Google Play services and returned to the app. */ @Override public void onMapReady(GoogleMap googleMap) { mMap = googleMap; // Add a marker in Sydney and move the camera LatLng sydney = new LatLng(-34, 151); mMap.addMarker(new MarkerOptions() .position(sydney) .title("Marker in Sydney")); mMap.moveCamera(CameraUpdateFactory.newLatLng(sydney)); } }
Kotlin
import androidx.appcompat.app.AppCompatActivity import android.os.Bundle import com.google.android.gms.maps.CameraUpdateFactory import com.google.android.gms.maps.GoogleMap import com.google.android.gms.maps.OnMapReadyCallback import com.google.android.gms.maps.SupportMapFragment import com.google.android.gms.maps.model.LatLng import com.google.android.gms.maps.model.MarkerOptions internal class MapsActivity : AppCompatActivity(), OnMapReadyCallback { private lateinit var mMap: GoogleMap override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.activity_maps) // Obtain the SupportMapFragment and get notified when the map is ready to be used. val mapFragment = supportFragmentManager .findFragmentById(R.id.map) as SupportMapFragment mapFragment.getMapAsync(this) } /** * Manipulates the map once available. * This callback is triggered when the map is ready to be used. * This is where we can add markers or lines, add listeners or move the camera. In this case, * we just add a marker near Sydney, Australia. * If Google Play services is not installed on the device, the user will be prompted to install * it inside the SupportMapFragment. This method will only be triggered once the user has * installed Google Play services and returned to the app. */ override fun onMapReady(googleMap: GoogleMap) { mMap = googleMap // Add a marker in Sydney and move the camera val sydney = LatLng(-34.0, 151.0) mMap.addMarker(MarkerOptions() .position(sydney) .title("Marker in Sydney")) mMap.moveCamera(CameraUpdateFactory.newLatLng(sydney)) } }
Archivo Gradle del módulo
El archivo build.gradle
del módulo incluye la siguiente dependencia de Maps, requerida por el SDK de Maps para Android.
dependencies { implementation 'com.google.android.gms:play-services-maps:18.1.0' // ... }
Para obtener más información sobre cómo administrar la dependencia de Maps, consulta la guía 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 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:tools="http://schemas.android.com/tools"
android:layout_width="match_parent"
android:layout_height="match_parent"
android:id="@+id/map"
tools:context=".MapsActivity"
android:name="com.google.android.gms.maps.SupportMapFragment" />
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 tema, 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.