Comenzando con Google Maps para Android: Conceptos básicos

Spanish (Español) translation by CYC (you can also view the original English article)

Introducción

Sin lugar a dudas, los mapas son una de las herramientas más útiles para los usuarios cuando se incluyen en una aplicación. Este tutorial es el primero de una serie sobre Google Maps v2 para Android. Esto cubrirá la configuración de la API de Google Maps a través de Google Developer Console, incluido un fragmento de mapa en tus aplicaciones, mostrando la ubicación del usuario, agregando marcadores, dibujando en el mapa y algunos métodos generales que agregarán utilidad a tu aplicación. Todo el código para este tutorial se puede encontrar en GitHub.

1. Configurando la Consola de Desarrollador

Para utilizar la API de Google Maps, debes registrar tu aplicación en la Consola de desarrollador de Google y habilitar la API. Para hacerlo, ve a Google Developer Console. Si ya tienes un proyecto creado, puedes omitir la siguiente sección. Si no, puedes continuar y crear un nuevo proyecto para tu aplicación de mapas.

Paso 1: Crear un proyecto

Para crear un nuevo proyecto, haz clic en el botón azul Crear proyecto en la esquina superior izquierda de la pantalla. Si no ves el botón Crear proyecto, busca un botón etiquetado Crear un proyecto vacío.

Esto te presenta un diálogo que solicita un nombre de proyecto. Para este tutorial, he creado un proyecto llamado TutsPlusMaps. Existen algunas restricciones sobre el nombre del proyecto, ya que solo se permiten letras, números, comillas, guiones, espacios y signos de exclamación.

Una vez que presionas en Crear, aparece un cuadro de diálogo en la esquina inferior derecha de la página con un indicador de carga mientras se está creando el proyecto.

Paso 2: Habilitar la API de Maps

Cuando se haya creado el proyecto o hayas seleccionado un proyecto existente, te llevará a la pantalla de descripción general del proyecto. Desde aquí, deberás expandir las API y el elemento de autenticación en el panel de navegación izquierdo y hacer clic en API.

Si bien hay un cuadro de búsqueda en esta pantalla, observarás que Google colocó los elementos de API de Google Maps en la parte superior de la columna central para que los desarrolladores puedan acceder. Para este tutorial, haz clic en el ítem titulado Google Maps Android API bajo el encabezado API de Google Maps.

Esto te lleva a una pantalla donde puedes hacer clic en el botón azul Habilitar API para habilitar la API de Maps para tu proyecto.

Paso 3: Crear una clave API de Android

Una vez que hayas habilitado la API de Maps, haz clic en el elemento Credenciales en APIs y auth en la barra lateral de navegación para obtener una clave para acceder a la API de Maps en tu aplicación. Cuando se te presente el cuadro de diálogo Credenciales, presiona el botón azul Agregar credenciales y selecciona la clave de API.

Dialog for selecting the type of credentials to create

Como esta es una aplicación de Android, debes seleccionar Android Key en el siguiente cuadro de diálogo. Si crearas la misma aplicación usando mapas en diferentes plataformas, podrías crear una clave para cada plataforma.

Dialog for selecting the type of key to generate

En la siguiente pantalla, haz clic en Agregar nombre de paquete y huella digital. Esto proporciona dos campos, uno para agregar un nombre de paquete y otro para agregar el SHA1 de la clave de firma de la aplicación.

Para este tutorial, usaré el nombre del paquete com.tutsplus.mapsdemo. Para obtener la firma SHA1, debe abrir una terminal o símbolo del sistema y navegar hasta la ubicación de la clave de firma de su aplicación. Esta puede ser tu clave de liberación o debug.keystore. Puedes generar el SHA1 con el siguiente comando:

1	keytool -list -v -keystore debug.keystore

Screenshot of a terminal output when getting an SHA1 key from a keystore

Después de haber creado tu clave SHA1 y haberla ingresado en el campo de texto, haz clic en el botón azul Crear . Luego se te presenta un cuadro de diálogo que contiene la clave de API que necesitas agregar a tu aplicación Android para acceder a la API de Maps.

2. Configurando el Proyecto Android

En este punto, puedes crear el proyecto inicial de Android con el mismo nombre de paquete que usaste para crear la clave API. Una vez que se haya creado tu proyecto, abre el archivo build.gradle. Debes importar la biblioteca Play Services para mapas. En este ejemplo, también necesitas importar la biblioteca Play Services de las ubicaciones para establecer una posición inicial para tu mapa. Coloca las siguientes líneas en el nodo dependencies del archivo build.gradle.

1	compile 'com.google.android.gms:play-services-maps:7.8.0'
2	compile 'com.google.android.gms:play-services-location:7.8.0'

Una vez que hayas importado tus bibliotecas, puedes cerrar build.gradle y abrir tu archivo AndroidManifest.xml. Por encima del nodo application, debes declarar que la aplicación utiliza OpenGL ES 2.0 y definir los permisos necesarios para tu aplicación.

Ten en cuenta que el permiso ACCESS_FINE_LOCATION solo es necesario para esta demostración a fin de obtener la ubicación del usuario para definir dónde debe mostrarse inicialmente el mapa. Si tienes una ubicación conocida en tu propia aplicación, no es necesario utilizar la ubicación del usuario.

<uses-feature
    android:glEsVersion="0x00020000"
    android:required="true"/>

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

Dentro del nodo application, necesitas agregar dos partes de metadatos. El primero informa a la aplicación que se utiliza Play Services y el segundo vincula la clave de Maps API con tu aplicación. En el siguiente fragmento de código, @string/google_api_key es una referencia de cadena a la clave de Google Developer Console.

<meta-data
    android:name="com.google.android.gms.version"
    android:value="@integer/google_play_services_version" />

<meta-data
    android:name="com.google.android.geo.API_KEY"
    android:value="@string/google_api_key"/>

Una vez que hayas terminado de actualizar AndroidManifest.xml, avanza y cierra el archivo. A continuación, debes crear una nueva clase Java, llamada MapFragment, que amplía SupportMapFragment. SupportMapFragment se utiliza aquí en lugar de com.google.android.gms.maps.MapFragment para agregar compatibilidad hacia atrás antes de API 12.

Si tu aplicación no necesita dispositivos que ejecuten versiones anteriores de Android, puedes usar com.google.android.gms.maps.MapFragment. Una vez que hayas creado el fragmento base, debes implementar las seis interfaces que utilizaremos para esta demostración.

public class MapFragment extends SupportMapFragment implements GoogleApiClient.ConnectionCallbacks,
        GoogleApiClient.OnConnectionFailedListener,
        GoogleMap.OnInfoWindowClickListener,
        GoogleMap.OnMapLongClickListener,
        GoogleMap.OnMapClickListener,
        GoogleMap.OnMarkerClickListener {

ConnectionCallbacks y OnConnectionFailedListener están diseñados para monitorear el estado de GoogleApiClient, que se usa en esta aplicación para obtener la ubicación actual del usuario.
OnInfoWindowClickListener se activa cuando el usuario hace clic en la ventana de información que aparece sobre un marcador en el mapa.
OnMapLongClickListener y OnMapClickListener se activan cuando el usuario toca o mantiene presionada una parte del mapa.
Se llama a OnMarkerClickListener cuando el usuario hace clic en un marcador en el mapa, que generalmente también muestra la ventana de información para ese marcador.

Cuando se te solicite, haz clic en la bombilla roja que aparece junto al nombre de la clase para agregar los métodos necesarios para estas interfaces.

Una vez que hayas creado el fragmento inicial, debes informar a MainActivity que debe usar este fragmento. Abre activity_main.xml de la carpeta de recursos y cámbialo para que incluya el fragmento como vista.

<RelativeLayout xmlns:android="https://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools" android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MainActivity">

    <fragment
        android:id="@+id/map"
        android:name="com.tutsplus.mapsdemo.MapFragment"
        android:layout_width="match_parent"
        android:layout_height="match_parent"/>

</RelativeLayout>

Después de actualizar el diseño de Activity, deberías poder ejecutar tu aplicación y ver un mapa de la Tierra que está completamente alejado y enfocado en la latitud 0, longitud 0.

What your screen should look like when Google Maps is initially set up correctly

3. Inicializando el mapa

Paso 1: Declarar tipos de mapas

Volviendo a nuestra clase MapFragment, necesitas definir algunos valores globales en la parte superior de la clase para usar en tu aplicación.

private GoogleApiClient mGoogleApiClient;
private Location mCurrentLocation;

private final int[] MAP_TYPES = { GoogleMap.MAP_TYPE_SATELLITE,
                                  GoogleMap.MAP_TYPE_NORMAL,
                                  GoogleMap.MAP_TYPE_HYBRID,
                                  GoogleMap.MAP_TYPE_TERRAIN,
                                  GoogleMap.MAP_TYPE_NONE };
private int curMapTypeIndex = 0;

Aquí mGoogleApiClient y mCurrentLocation se utilizan para obtener la ubicación del usuario para inicializar la cámara de mapa. MAP_TYPES y curMapTypeIndex se utilizan en el código de muestra para alternar entre diferentes tipos de visualización de mapa. Cada uno de los tipos de mapas tiene un propósito diferente, por lo que uno o más pueden ser adecuados para tus propias aplicaciones.

GoogleMap.MAP_TYPE_SATELLITE muestra una vista de satélite del área sin nombres ni etiquetas de calles.

GoogleMap.MAP_TYPE_NORMAL muestra un mapa genérico con nombres y etiquetas de calles.

GoogleMap.MAP_TYPE_HYBRID combina el modo satelital y el normal, que muestra imágenes satelitales de un área con todas las etiquetas.

GoogleMap.MAP_TYPE_TERRAIN es similar a un mapa normal, pero las texturas se agregan para mostrar los cambios en la elevación del entorno. Estas texturas son más visibles cuando el mapa está en ángulo con un arrastre de dos dedos.

GoogleMap.MAP_TYPE_NONE es similar a un mapa normal, pero no muestra etiquetas ni coloraciones para el tipo de entorno en un área. Permite mostrar el tráfico y otras superposiciones en el mapa.

Paso 2: Creando el API Client

A continuación, debes crear tu GoogleApiClient e iniciar LocationServices para obtener la ubicación actual de tu usuario. Como mencioné antes, si tienes una ubicación configurada que deseas mostrar en lugar de enfocarte en el usuario, puedes omitir el uso de LocationServices.

@Override
public void onViewCreated(View view, Bundle savedInstanceState) {
    super.onViewCreated(view, savedInstanceState);

    setHasOptionsMenu(true);

    mGoogleApiClient = new GoogleApiClient.Builder( getActivity() )
            .addConnectionCallbacks( this )
            .addOnConnectionFailedListener( this )
            .addApi( LocationServices.API )
            .build();

    initListeners();
}

El método initListeners vincula las interfaces que declaraste en la parte superior de la clase con el objeto GoogleMap asociado con SupportMapFragment. Así es como se ve la implementación:

private void initListeners() {
    getMap().setOnMarkerClickListener(this);
    getMap().setOnMapLongClickListener(this);
    getMap().setOnInfoWindowClickListener( this );
    getMap().setOnMapClickListener(this);
}

Es posible que hayas notado que el GoogleApiClient y los receptores se crean y enlazan onViewCreated en lugar del típico onCreate Esto se debe a que el objeto GoogleMap no se ha inicializado cuando se llama a onCreate, por lo que debemos esperar hasta que la vista esté completamente creada antes de intentar llamar a getMap para evitar una NullPointerException.

Paso 3: Configurando el Mapa

Como configurarás la cámara de mapas una vez que hayas encontrado la ubicación del usuario a través de Play Services, utilizaremos el ciclo de vida de Play Services para iniciar nuestro mapa. Puedes conectar GoogleApiClient en onStart. Cuando el cliente se haya conectado, puedes tomar la ubicación recuperada más recientemente del usuario y usarla para apuntar la cámara del mapa.

@Override
public void onStart() {
    super.onStart();
    mGoogleApiClient.connect();
}

@Override
public void onStop() {
    super.onStop();
    if( mGoogleApiClient != null && mGoogleApiClient.isConnected() ) {
        mGoogleApiClient.disconnect();
    }
}

@Override
public void onConnected(Bundle bundle) {
    mCurrentLocation = LocationServices
        .FusedLocationApi
        .getLastLocation( mGoogleApiClient );

    initCamera( mCurrentLocation );
}

En el método initCamera, se inicializa la cámara y algunas propiedades básicas del mapa. Empieza creando un objeto CameraPosition a través de CameraPosition.Builder, con un objetivo establecido para la latitud y la longitud de tu usuario y un nivel de zoom establecido.

La inclinación y el rumbo se utilizan aquí en tus valores predeterminados para ilustrar que están disponibles las opciones. Una vez que tienes un objeto CameraPosition, puedes animar la cámara de mapa a esa posición usando CameraUpdateFactory.

private void initCamera( Location location ) {
    CameraPosition position = CameraPosition.builder()
            .target( new LatLng( location.getLatitude(), 
                location.getLongitude() ) )
            .zoom( 16f )
            .bearing( 0.0f )
            .tilt( 0.0f )
            .build();

    getMap().animateCamera( CameraUpdateFactory
            .newCameraPosition( position ), null );

    getMap().setMapType( MAP_TYPES[curMapTypeIndex] );
    getMap().setTrafficEnabled( true );
    getMap().setMyLocationEnabled( true );
    getMap().getUiSettings().setZoomControlsEnabled( true );
}

Al final de este método, observarás que las últimas cuatro líneas establecen algunas propiedades para el mapa. Establece el tipo de mapa, como se describió anteriormente en este tutorial, y habilita las superposiciones de flujo de tráfico en vivo en las dos primeras líneas. setMyLocationEnabled agrega un botón a la esquina superior derecha de MapFragment que mueve automáticamente la cámara a la ubicación de tu usuario cuando se presiona.

Finalmente, al llamar a setZoomControlsEnabled se agregan los botones + y - en la esquina inferior derecha, lo que permite al usuario cambiar el nivel de zoom del mapa sin tener que usar gestos. Hay algunas cosas más interesantes que puedes configurar con UiSettings, como agregar una brújula o deshabilitar los gestos, que puedes encontrar en la documentación de referencia de Android.

4. Marcando ubicaciones

Una de las funciones de mapa más utilizadas implica indicar ubicaciones con marcadores. Como se necesita una latitud y una longitud para agregar un marcador, debes usar OnMapClickListener para permitir que el usuario elija un punto en el mapa para colocar un objeto Marker.

@Override
public void onMapClick(LatLng latLng) {

    MarkerOptions options = new MarkerOptions().position( latLng );
    options.title( getAddressFromLatLng( latLng ) );

    options.icon( BitmapDescriptorFactory.defaultMarker() );
    getMap().addMarker( options );
}

Este método crea un marcador rojo genérico donde el usuario ha tocado. Se pueden establecer opciones adicionales, como establecer un marcador como arrastrable, a través del objeto MarkerOptions. Puedes encontrar atributos adicionales en la documentación oficial de referencia de Android. Si deseas cambiar el color del marcador, puedes llamar a BitmapDescriptorFactory.defaultMarker al agregar un icono a MarkerOptions. El método defaultMarker acepta un valor flotante que define el tono. El matiz se puede establecer manualmente o como un valor estático predefinido de BitmapDescriptorFactory. Cabe señalar que addMarker devuelve un objeto Marker, que se puede almacenar para eliminar marcadores específicos manualmente si es necesario.

Si deseas evitar el uso de los pines de colores genéricos para tus marcadores de ubicación, puedes establecer un mapa de bits como el icono en el objeto MarkerOptions. Para demostrar esto, reemplaza el método onMapLongClick para que uses el ícono de la aplicación de la carpeta de recursos como Marker cuando tu usuario presione el mapa durante mucho tiempo.

@Override
public void onMapLongClick(LatLng latLng) {
    MarkerOptions options = new MarkerOptions().position( latLng );
    options.title( getAddressFromLatLng( latLng ) );

    options.icon( BitmapDescriptorFactory.fromBitmap(
            BitmapFactory.decodeResource( getResources(), 
                    R.mipmap.ic_launcher ) ) );

    getMap().addMarker( options );
}

Probablemente hayas notado que el método getAddressFromLatLng se está utilizando en ambos métodos clic. Este es un método de ayuda que toma un LatLng y lo ejecuta a través de un Geocoder para obtener una dirección de calle. En los dos últimos ejemplos, estamos usando este método para mostrar una dirección de calle cuando se toca un marcador.

private String getAddressFromLatLng( LatLng latLng ) {
    Geocoder geocoder = new Geocoder( getActivity() );

    String address = "";
    try {
        address = geocoder
          .getFromLocation( latLng.latitude, latLng.longitude, 1 )
          .get( 0 ).getAddressLine( 0 );
    } catch (IOException e ) {
    }

    return address;
}

@Override
public boolean onMarkerClick(Marker marker) {
    marker.showInfoWindow();
    return true;
}

5. Dibujar en el mapa

El objeto GoogleMap tiene un conjunto de métodos que hacen que sea más fácil dibujar formas y colocar imágenes en el mapa. Para dibujar un círculo simple, solo necesitas crear un objeto CircleOptions, establecer un radio y una ubicación central, y definir los colores y el tamaño de trazo/relleno.

Una vez que tengas un objeto CircleOptions, puedes llamar a addCircle para dibujar el círculo definido en la parte superior del mapa. Al igual que cuando se colocan marcadores, los objetos que se dibujan en el mapa devuelven un objeto del tipo de elemento dibujado para que pueda ser referenciado más adelante si es necesario.

private void drawCircle( LatLng location ) {
    CircleOptions options = new CircleOptions();
    options.center( location );
    //Radius in meters
    options.radius( 10 );
    options.fillColor( getResources()
        .getColor( R.color.fill_color ) );
    options.strokeColor( getResources()
        .getColor( R.color.stroke_color ) );
    options.strokeWidth( 10 );
    getMap().addCircle(options);
}

Illustration of a circle drawn programmatically on the map

Para dibujar una forma cerrada distinta, puedes tomar múltiples puntos LatLng y crear un objeto PolygonOptions. Como puedes ver a continuación, los PolygonOptions se crean de forma similar a CircleOptions. En lugar de usar un método center y radius, usas add con una lista de puntos. Puedes llamar a addPolygon para dibujar la forma. Para este ejemplo, simplemente dibuja un triángulo en el mapa.

private void drawPolygon( LatLng startingLocation ) {
    LatLng point2 = new LatLng( startingLocation.latitude + .001, 
        startingLocation.longitude );
    LatLng point3 = new LatLng( startingLocation.latitude, 
        startingLocation.longitude + .001 );

    PolygonOptions options = new PolygonOptions();
    options.add( startingLocation, point2, point3 );

    options.fillColor( getResources()
        .getColor( R.color.fill_color ) );
    options.strokeColor( getResources()
        .getColor( R.color.stroke_color ) );
    options.strokeWidth( 10 );

    getMap().addPolygon( options );
}

El último tipo de dibujo que aprenderás es agregar una imagen como una superposición en el mapa. Las superposiciones pueden ser útiles si tienes un mapa dibujado para un área que deseas mostrar sobre un tipo de mapa normal. Esto se puede lograr creando GroundOverlayOptions con una ubicación establecida, ancho y alto, y la imagen que deseas usar como BitmapDescriptor.

En el siguiente método, dibuja el icono del iniciador para la aplicación como una superposición en los mosaicos del mapa.

private void drawOverlay( LatLng location, int width, int height ) {
    GroundOverlayOptions options = new GroundOverlayOptions();
    options.position( location, width, height );

    options.image( BitmapDescriptorFactory
            .fromBitmap( BitmapFactory
                .decodeResource( getResources(), 
                    R.mipmap.ic_launcher ) ) );
    getMap().addGroundOverlay( options );
}

Conclusión

En este tutorial, has aprendido a crear una API key y habilitar Google Maps para Android. También aprendiste sobre la clase MapFragment y algunas de las características básicas que puedes activar para un mapa.

Aprendiste cómo colocar marcadores, recibir las interacciones con el mapa y dibujar en el mapa para mostrar información adicional.

En el siguiente tutorial de esta serie, aprenderás a superponer una View sobre MapFragment, cómo interactuar con mapas de nivel interior y cómo mostrar una vista de calle a tus usuarios.