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

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.
  
  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 API 19: Android 4.4 (KitKat), la app debería ejecutarse en más del 99% de los dispositivos Android.
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 y MapsActivity. 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 archivo AndroidManifest.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

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.

Ir a la página del selector de proyectos
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

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:

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.

Ir a la página 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:

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 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 elemento dependencies en buildscript.
```
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 elemento plugins.
```
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. Reemplaza YOUR_API_KEY por tu clave de API.
```
MAPS_API_KEY=YOUR_API_KEY
    
```
Guarda el archivo.
En tu archivo AndroidManifest.xml, ve a com.google.android.geo.API_KEY y actualiza el 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.

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.

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 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: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

Captura de pantalla con el mapa y un marcador centrados en Sídney, Australia.

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.