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

  1. Se requiere Android Studio. Si aún no lo tienes, descárgalo y, luego, instálalo.

  2. Agrega el SDK de Servicios de Google Play a Android Studio. El SDK de Maps para Android se distribuye como parte del SDK de Servicios de Google Play, el cual puedes agregar a través de SDK Manager.

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 Android basado en la versión 4.2.2 o posterior, y que incluya las API de Google.

Cómo crear un proyecto de Google Maps

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

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

  3. Completa el formulario Google Maps Activity:

    • En la sección Languaje, 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.

  4. Haz clic en Finish.

Cuando termines de configurar tu proyecto, Android Studio iniciará Gradle y lo creará. Esto puede demorar un poco. Una vez que se complete este proceso, Android Studio abrirá los archivos google_maps_api.xml y MapsActivity. Es posible que tu actividad tenga un nombre diferente, pero será el mismo proyecto que configuraste en la etapa anterior.

Para obtener más información sobre cómo crear un proyecto, consulta la sección Cómo crear un proyecto de Android.

El archivo google_maps_api.xml contiene instrucciones para obtener una clave de API de Google Maps y agregarla al archivo. No agregues tu clave de API al archivo, ya que allí se almacenará de forma menos segura. En cambio, sigue las instrucciones que se indican en la próxima sección.

Configuración en Cloud Console

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

Paso 1

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

    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 gratuita de USD 300, y Google Maps Platform cuenta con 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.

Paso 2

Para usar Google Maps Platform, debes habilitar las API o los SDK que planeas usar con tu proyecto en Cloud Console.

Habilitar el SDK de Maps para Android

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:

  1. Ve a la página API y servicios > 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).

Cómo agregar la clave de API a tu app

En esta sección, se explica cómo debes almacenar tu clave de API para que tu app pueda hacer referencia a ella de manera más segura. No debes verificar la clave de API en tu 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.

Para optimizar esta tarea, puedes usar el complemento Secrets Gradle para Android.

Para instalar el complemento y almacenar tu clave de API, haz lo siguiente:

  1. En Android Studio, abre el archivo build.gradle a nivel de tu app y agrega el siguiente código al elemento plugins.
    id 'com.google.secrets_gradle_plugin' version '0.5'
        
  2. Guarda el archivo y sincroniza tu proyecto con Gradle.
  3. Abre el archivo local.properties en el directorio de nivel de proyecto y, luego, agrega el siguiente código. Reemplaza YOUR_API_KEY por la clave de API.
    MAPS_API_KEY=YOUR_API_KEY
        
  4. Guarda el archivo y sincroniza tu proyecto con Gradle.
  5. 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 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 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

// Copyright 2020 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package com.google.maps.example;

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;

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

// Copyright 2020 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package com.google.maps.example.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
import com.google.maps.example.R

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 a nivel de la app

El archivo build.gradle a nivel de la app incluye la siguiente dependencia de Maps, requerida por el SDK de Maps para Android.

dependencies {
    implementation 'com.google.android.gms:play-services-maps:17.0.1'
    // ...
}

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:

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