Mapas en Android (Google Maps Android API v2) – I

Hace tan sólo 3 días, Google presentaba la segunda versión de su API de Google Maps para Android. Esta nueva versión presenta muchas novedades interesantes, de las que cabe destacar las siguientes:

• Integración con los Servicios de Google Play (Google Play Services) y la Consola de APIs.
• Utilización a través de un nuevo tipo específico de fragment (MapFragment), una mejora muy esperada por muchos.
• Utilización de mapas vectoriales, lo que repercute en una mayor velocidad de carga y una mayor eficiencia en cuanto a uso de ancho de banda.
• Mejoras en el sistema de caché, lo que reducirá en gran medida las famosas áreas en blanco que tardan en cargar.
• Los mapas son ahora 3D, es decir, podremos mover nuestro punto de vista de forma que lo veamos en perspectiva.

Al margen de las novedades generales, como desarrolladores ¿qué diferencias nos vamos a encontrar con respecto a la API anterior a la hora de desarrollar nuestras aplicaciones Android?

Pues la principal será el componente que utilizaremos para la inclusión de mapas en nuestra aplicación. Si recordamos la anterior versión de la API, para incluir un mapa en la aplicación debíamos utilizar un control de tipo MapView, que además requería que su actividad contenedora fuera del tipo MapActivity. Con la nueva API nos olvidaremos de estos dos componentes y pasaremos a tener sólo uno, un nuevo tipo específico de fragment llamado MapFragment. Esto nos permitirá entre otras cosas añadir uno [o varios, esto también es una novedad] mapas a cualquier actividad, sea del tipo que sea, y contando por supuesto con todas las ventajas del uso de fragments. Nota importante: dado que el nuevo control de mapas se basa en fragments, si queremos mantener la compatibilidad con versiones de Android anteriores a la 3.0 tendremos que utilizar la librería de soporte android-support. Más adelante veremos más detalles sobre esto.

Además de esta novedad, la integración de la API con los Google Play Services y la Consola de APIs de Google, harán que los preparativos del entorno, las librerías utilizadas, y el proceso de obtención de la API Key de Google Maps sean un poco distintos a los que ya vimos en los artículos dedicados la primera versión.

Pues bien, en este nuevo artículo del Curso de Programación Android vamos a describir los pasos necesarios para hacer uso de la nueva versión de la API de mapas de Google (Google Maps Android API v2).

Como en los artículos previos donde aprendimos a utilizar la API v1, en este caso también será necesario realizar algunos preparativos y tareas previas antes de poder empezar a utilizarlos en nuestras aplicaciones.

En primer lugar, dado que la API v2 se proporciona como parte del SDK de Google Play Services, será necesario incorporar previamente a nuestro entorno de desarrollo dicho paquete. Haremos esto accediendo desde Eclipse al Android SDK Manager y descargando del apartado de extras el paquete llamado “Google Play Services”.

Tras pulsar el botón de Install y aceptar la licencia correspondiente el paquete quedará instalado en nuestro sistema, concretamente en la ruta: <carpeta-sdk-android>/extras/google/google_play_services/. Recordemos esto porque nos hará falta más adelante.

El siguiente paso será obtener una API Key para poder utilizar el servicio de mapas de Google en nuestra aplicación. Este paso ya lo comentamos en los artículos sobre la API v1, pero en este caso el procedimiento será algo distinto. La nueva API de mapas de Android se ha integrado por fin en la Consola de APIs de Google (una herramienta de la que ya hablamos por ejemplo en los artículos dedicados a Google Cloud Messaging), por lo que el primer paso será acceder a ella. Una vez hemos accedido, tendremos que crear un nuevo proyecto desplegando el menú superior izquierdo y seleccionando la opción “Create…”.

Aparecerá entonces una ventana que nos solicitará el nombre del proyecto. Introducimos algún nombre descriptivo y aceptamos sin más.

Una vez creado el proyecto, accederemos a la opción “Services” del menú izquierdo. Desde esta ventana podemos activar o desactivar cada uno de los servicios de Google que queremos utilizar. En este caso sólo activaremos el servicio llamado “Google Maps Android API v2″ pulsando sobre el botón ON/OFF situado justo a su derecha.

Una vez activado aparecerá una nueva opción en el menú izquierdo llamada “API Access”. Accediendo a dicha opción tendremos la posibilidad de obtener nuestra nueva API Key que nos permita utilizar el servicio de mapas desde nuestra aplicación particular.

Para ello, pulsaremos el botón “Create new Android key…”. Esto nos llevará a un cuadro de diálogo donde tendremos que introducir algunos datos identificativos de nuestra aplicación. En concreto necesitaremos dos: la huella digital (SHA1) del certificado con el que firmamos la aplicación, y el paquete java utilizado. El segundo no tiene misterio, pero el primero requiere alguna explicación. Toda aplicación Android debe ir firmada para poder ejecutarse en un dispositivo, tanto físico como emulado. Este proceso de firma es uno de los pasos que tenemos que hacer siempre antes de distribuir públicamente una aplicación.  Adicionalmentes, durante el desarrollo de la misma, para realizar pruebas y la depuración del código, aunque no seamos conscientes de ello también estamos firmado la aplicación con un “certificado de pruebas”. Podemos saber en qué carpeta de nuestro sistema está almacenado este certificado accediendo desde Eclipse al menú Window /Preferences y accediendo a la sección Android / Build.

Como se puede observar, en mi caso el certificado de pruebas está en la ruta “C:\Users\Salvador\.android\debug.keystore”. Pues bien, para obtener nuestra huella digital SHA1 deberemos acceder a dicha ruta desde la consola de comando de Windows y ejecutar los siguientes comandos:

C:\>cd C:\Users\Salvador\.android\

C:\Users\Salvador\.android>"C:\Program Files\Java\jdk1.7.0_07\bin\keytool.exe" -list -v -keystore debug.keystore -alias androiddebugkey -storepass android -keypass android

Suponiendo que tu instalación de Java está en la ruta “C:\Program Files\Java\jdk1.7.0_07“. Si no es así sólo debes sustituir ésta por la correcta. Esto nos deberá devolver varios datos del certificado, entre ellos la huella SHA1.

Pues bien, nos copiamos este dato y lo añadimos a la ventana de obtención de la API Key donde nos habíamos quedado antes, y a continuación separado por un punto y coma añadimos el paquete java que vayamos a utilizar en nuestra aplicación, que en mi caso será “net.sgoliver.android.mapasapi2″.

Pulsamos el botón “Create” y ya deberíamos tener nuestra API Key generada, podremos verla en la pantalla siguiente dentro del apartado “Key for Android Apps (with certificates)”. Apuntaremos también este dato para utilizarlo más tarde.

Con esto ya habríamos concluido los preparativos iniciales necesarios para utilizar el servicio de mapas de Android en nuestras propias aplicaciones, por lo que empecemos a crear un proyecto de ejemplo en Eclipse.

Abriremos Eclipse y crearemos un nuevo proyecto estandar de Android, en mi caso lo he llamado “android-mapas-api2″. Recordemos utilizar para el proyecto el mismo paquete java que hemos indicado durante la obtención de la API key.

Tras esto lo primero que haremos será añadir al fichero AndroidManifest.xml la API Key que acabamos de generar. Para ello añadiremos al fichero, dentro de la etiqueta <application>, un nuevo elemento <meta-data> con los siguientes datos:

...
<application>
...
    <meta-data android:name="com.google.android.maps.v2.API_KEY"
               android:value="api_key"/>
...
</application>

Como valor del parámetro android:value tendremos que poner nuestra API Key recien generada.

Siguiendo con el AndroidManifest, también tendremos que incluir una serie de permisos que nos permitan hacer uso de los mapas. En primer lugar tendremos que definir y utilizar un permiso llamado “tu.paquete.java.permission.MAPS_RECEIVE”, en mi caso quedaría de la siguiente forma:

<permission
      android:name="net.sgoliver.android.mapasapi2.permission.MAPS_RECEIVE"
      android:protectionLevel="signature"/>

<uses-permission android:name="net.sgoliver.android.mapasapi2.permission.MAPS_RECEIVE"/>

Además, tendremos que añadir permisos adicionales que nos permitan acceder a los servicios web de Google, a Internet, y al almacenamiento externo del dispositivo (utilizado para la caché de los mapas):

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
<uses-permission android:name="com.google.android.providers.gsf.permission.READ_GSERVICES"/>

Por último, dado que la API v2 de Google Maps Android utiliza OpenGL ES versión 2, deberemos especificar también dicho requisito en nuestro AndroidManifest añadiendo un nuevo elemento <uses-feature>:

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

Una vez hemos configurado todo lo necesario en el AndroidManifest, y antes de escribir nuestro código, tenemos que seguir añadiendo elementos externos a nuestro proyecto. El primero de ellos será referenciar desde nuestro proyecto la librería con el SDK de Google Play Services que nos descargamos al principio de este tutorial. Para ello, desde Eclipse podemos importar la librería a nuestro conjunto de proyectos mediante la opción de menú “File / Import… / Existing Android Code Into Workspace”. Como ya dijimos este paquete se localiza en la ruta “<carpeta-sdk-android>/extras/google/google_play_services/libproject/google-play-services_lib“.

Tras seleccionar la ruta correcta dejaremos el resto de opciones con sus valores por defecto y pulsaremos Finish para que Eclipse importe esta librería a nuestro conjunto de proyectos.

El siguiente paso será referenciar esta librería desde nuestro proyecto de ejemplo. Para ello iremos a sus propiedades pulsando botón derecho / Properties sobre nuestro proyecto y accediendo a la sección Android de las preferencias. En dicha ventana podemos añadir una nueva librería en la sección inferior llamada Library. Cuando pulsamos el botón “Add…” nos aparecerá la librería recien importada y podremos seleccionarla directamente, añadiéndose a nuestra lista de librerías referenciadas por nuestro proyecto.

Como último paso de configuración de nuestro proyecto, si queremos que nuestra aplicación se pueda ejecutar desde versiones “antiguas” de Android (concretamente desde la versión de Android 2.2) deberemos asegurarnos de que nuestro proyecto incluye la librería android-support-v4.jar, que debería aparecer si desplegamos las sección “Android Dependencies” o la carpeta “lib” de nuestro proyecto.

Las versiones más recientes de ADT incluyen por defecto esta librería en nuestros proyectos, pero si no está incluida podéis hacerlo mediante la opción del menú contextual “Android Tools / Add Support Library…”  sobre el proyecto, o bien de forma manual.

Y con esto hemos terminado de configurar todo lo necesario. Ya podemos escribir nuestro código. Y para este primer artículo sobre el tema nos vamos a limitar a mostrar un mapa en la pantalla principal de la aplicación. En artículos posteriores veremos como añadir otras opciones o elementos al mapa.

Para esto tendremos simplemente que añadir el control correspondiente al layout de nuestra actividad principal. En el caso de la nueva API v2 este “control” se añadirá en forma de fragment (de ahí que hayamos tenido que incluir la librería android-support para poder utilizarlos en versiones de Android anteriores a la 3.0) de un determinado tipo (concretamente de la nueva clase com.google.android.gms.maps.SupportMapFragment), quedando por ejemplo de la siguiente forma:

<?xml version="1.0" encoding="utf-8"?>
<fragment xmlns:android="http://schemas.android.com/apk/res/android"
        android:id="@+id/map"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        class="com.google.android.gms.maps.SupportMapFragment"/>

Por supuesto, dado que estamos utilizando fragments, la actividad principal también tendrá que extender a FragmentActivity (en vez de simplemente Activity como es lo “normal”). Usaremos también la versión de FragmentActivity incluida en la librería android-support para ser compatibles con la mayoría de las versiones Android actuales.

public class MainActivity extends android.support.v4.app.FragmentActivity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
	super.onCreate(savedInstanceState);
	setContentView(R.layout.activity_main);
    }

...
}

Con esto, ya podríamos ejecutar y probar nuestra aplicación. En mi caso las pruebas las he realizado sobre un dispositivo físico con Android 2.2 ya que por el momento parece haber algunos problemas para hacerlo sobre el emulador. Por tanto tendréis que conectar vuestro dispositivo  al PC mediante el cable de datos e indicar a Eclipse que lo utilice para la ejecución de la aplicación.

Si ejecutamos el ejemplo deberíamos ver un mapa en la pantalla principal de la aplicación, sobre el que nos podremos mover y hacer zoom con los gestos habituales o utilizando los controles de zoom incluidos por defecto sobre el mapa.

Con este artículo espero haber descrito todos los pasos necesarios para comenzar a utilizar los servicios de mapas de Google utilizando su nueva API Google Maps Android v2. Si tenéis cualquier duda o propuesta de mejora no dudéis en escribirlo en los comentarios.

Como habéis podido comprobar hay muchos preparativos que hacer, aunque ninguno de ellos de excesiva dificultad. En los próximos artículos aprenderemos a utilizar más características de la nueva API.

Puedes consultar y/o descargar el código completo de los ejemplos desarrollados en este artículo accediendo a la pagina del curso en GitHub.