API de Google Maps para Android

API de Google Maps para Android: biblioteca externa

Para ayudarte a añadir potentes capacidades de creación de mapas a tu aplicación, el complemento para las API de Google incluye una biblioteca externa de Google Maps, com.google.android.maps. Las clases de la biblioteca de Google Maps ofrecen descargas, procesamiento y almacenamiento en caché integrados de mosaicos de Google Maps, así como numerosos controles y opciones de visualización.

La clase clave de la biblioteca de Google Maps es MapView, una subclase de ViewGroup de la biblioteca estándar de Android. Una clase MapView muestra un mapa con datos obtenidos del servicio de Google Maps. Cuando la clase MapView está enfocada, puede capturar pulsaciones de teclas y formas de tocar la pantalla para desplazar y acercar o alejar el mapa de forma automática, incluso administrar solicitudes de redes para obtener mosaicos de mapas adicionales. También proporciona todos los elementos de interfaz de usuario que necesitan los usuarios para controlar el mapa. Tu aplicación solo puede utilizar los métodos de clase MapView para controlar MapView mediante programación y dibujar algunos tipos de superposiciones (Overlay) en la parte superior del mapa.

En general, la clase MapView proporciona un envoltorio alrededor del API de Google Maps que permite a tu aplicación manipular datos de Google Maps mediante métodos de clase y, además, te permite trabajar con datos de Google Maps como lo harías con otros tipos de vistas.

La biblioteca externa de Google Maps no forma parte de la biblioteca de Android estándar, por lo que es posible que no se incluya en algunos dispositivos con Android que cumplan los requisitos. Del mismo modo, la biblioteca externa de Google Maps no se incluye en la biblioteca de Android estándar proporcionada en el kit de desarrollo de software. El complemento para las API de Google proporciona la biblioteca de Google Maps, de forma que puedes desarrollar, crear y ejecutar aplicaciones basadas en mapas en el kit de desarrollo de software de Android con total acceso a los datos de Google Maps.

Para utilizar las clases de la biblioteca externa de Google Maps en tu aplicación, debes realizar las siguientes acciones:

En las secciones que aparecen a continuación se proporciona más información.

Cómo configurar un proyecto de Google Maps

Una vez hayas instalado el complemento para las API de Google, podrás añadir capacidades de Google Maps a cualquier proyecto de Android nuevo o existente. Para que tu aplicación pueda acceder a la biblioteca de Google Maps, lo único que tienes que hacer es establecer las propiedades del proyecto de forma que las herramientas de creación puedan localizar la biblioteca de Google Maps en el complemento para las API de Google. El procedimiento para hacerlo depende de si el proceso de desarrollo se realiza en Eclipse con el complemento ADT o si se lleva a cabo mediante Ant.

A continuación, se indica cómo establecer el objetivo de desarrollo si realizas el proceso en Eclipse con ADT.

  • Si quieres añadir Google Maps a una aplicación existente, haz clic con el botón derecho en el proyecto del explorador de paquetes, selecciona la opción de propiedades, después la opción de Android y, a continuación selecciona un objetivo de desarrollo de la lista que se muestra. Debes seleccionar el objetivo de desarrollo de las API de Google.
  • Si creas un proyecto de Android nuevo en Eclipse, el asistente para proyectos nuevos te pedirá que especifiques el objetivo de desarrollo de la aplicación. Debes seleccionar el objetivo de desarrollo de las API de Google.

Si el proceso de desarrollo se lleva a cabo en Ant, debes utilizar la herramienta de Android incluida en el kit de desarrollo de software para establecer el objetivo de desarrollo de tu proyecto.

  • En el caso de un proyecto existente, utiliza el comando android list targets para que aparezcan los objetivos de desarrollo disponibles en tu kit de desarrollo de software. Localiza el objetivo de desarrollo de las API de Google y anota su ID. A continuación, utiliza el comando android update project --target <targetID> --path path/to/your/project/ para que el proyecto utilice el objetivo del complemento para las API de Google.
  • En el caso de un nuevo proyecto, sigue los pasos descritos anteriormente para que aparezcan los objetivos de desarrollo y utiliza el comando android create project --target <targetID> --path path/to/your/project/ para que el proyecto utilice el objetivo de las API de Google.

Ten en cuenta que hay disponibles varias versiones del complemento para las API de Google y que cada una está orientada a un nivel de API de la plataforma de Android. Selecciona la versión con el nivel de API apropiado para tu aplicación en base al atributo android:minSdkVersion de esta, que se indica en el archivo de manifiesto de la aplicación.

Para obtener más información sobre cómo trabajar con proyectos de Android, consulta la página sobre cómo desarrollar aplicaciones en Eclipse con ADT o sobre cómo desarrollar aplicaciones en otros entornos de desarrollo integrado, en función de tu entorno, en el sitio de Desarrolladores de Android.

Para obtener más información sobre los niveles de API y cómo utilizarlos, consulta la página sobre los niveles de API para Android y la documentación del elemento de manifiesto <uses-sdk>.

Cómo configurar un dispositivo virtual de Android

Una vez hayas creado tu proyecto, necesitas poder ejecutarlo, depurar los errores, asignar un perfil y probarlo. Para ejecutar tu aplicación basada en Google Maps en el Emulador de Android, debes configurar un dispositivo virtual de Android para que utilice el complemento para las API de Google. Para configurar el dispositivo virtual de Android, utiliza el administrador del dispositivo virtual de Android.

Inicia el administrador del dispositivo virtual de Android con el comando android son ninguna opción. Si llevas a cabo el proceso en Eclipse/ADT, también puedes acceder a la herramienta desde la ventana y, a continuación, accediendo al administrador del dispositivo virtual y al kit de desarrollo de software de Android.

  1. Haz clic en el botón para crear un nuevo dispositivo virtual de Android.
  2. En el cuadro de diálogo que aparece, especifica un nombre para el dispositivo virtual y selecciona el objetivo de imagen de sistema que quieres que utilice el dispositivo. Selecciona uno de los objetivos de las API de Google (Google Inc.) y asegúrate de que eliges una versión cuyo nivel de API se corresponda con el atributo android:minSdkVersion incluido en el manifiesto de tu aplicación, tal y como se ha indicado anteriormente.
  3. Configura las otras opciones y, a continuación, haz clic en la opción para crear el dispositivo virtual de Android.

Cuando hayas terminado de crear el dispositivo virtual de Android, puedes ejecutarlo desde la interfaz de usuario del administrador del dispositivo o utilizar la interfaz de línea de comando del emulador. Si llevas a cabo el proceso de desarrollo en Eclipse, puedes establecer una configuración de ejecución para iniciar el dispositivo virtual de Android e instalar tu aplicación en él.

Para obtener más información, consulta la sección sobre dispositivos virtuales de Android del sitio de Desarrolladores de Android.

Si tienes un dispositivo físico con la plataforma adecuada (tal y como establece su nivel de API) e incluye la biblioteca externa de Google Maps, siempre puedes ejecutar tu aplicación, depurar los errores de esta y probarla en este dispositivo en lugar de en el emulador. Para obtener más información, consulta la página sobre cómo desarrollar una aplicación en un dispositivo.

Cómo hacer referencia a la biblioteca de Google Maps desde el archivo de manifiesto de la aplicación

Para utilizar las clases de la biblioteca externa de Google Maps en tu aplicación, debes hacer referencia a la biblioteca desde el archivo de manifiesto de la aplicación. De forma específica, debes añadir un elemento <uses-library> como elemento secundario del elemento <application>, con un atributo android:name cuyo valor sea com.google.android.maps. A continuación se muestra un ejemplo:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
 package="com.example.package.name">
  ...
  <application android:name="MyApplication" >
    <uses-library android:name="com.google.android.maps" />
    ...
  </application>
  ...
</manifest>

La referencia <uses-library> es obligatoria debido a que permite que las herramientas de creación vinculen tu aplicación a la biblioteca externa de Google Maps. También garantiza que el sistema Android no instale tu aplicación en un dispositivo si no está disponible la biblioteca necesaria.

Cómo utilizar las clases de Google Maps en tu aplicación

La biblioteca de Google Maps proporciona numerosas clases que te permiten mostrar y manipular datos de Google Maps en tu aplicación. Antes de empezar, primero echa un vistazo a los elementos disponibles en el paquete com.google.android.maps.

La clase clave de la biblioteca es MapView, una subclase de ViewGroup de la biblioteca estándar de Android. La clase MapView muestra datos de mapas del servicio de Google Maps y se encarga de la interacción con el servicio. Además, incluye todos los elementos de interfaz de usuario necesarios para que el usuario controle el mapa y también proporciona métodos que permiten a tu aplicación manipular el mapa, dibujar superposiciones, etc.

Para utilizar Google Maps en tu aplicación, amplía la clase MapActivity y, a continuación crea una distribución que incluya un elemento MapView. Para hacerte una idea sobre cómo configurar un elemento MapView, consulta este tutorial del sitio de Desarrolladores de Android.

Si quieres ver un código de ejemplo, el complemento para las API de Google incluye una aplicación de ejemplo denominada MapsDemo que puedes cargar en tu entorno de desarrollo y ejecutarla. La aplicación está ubicada en el directorio de las API de Google.

<sdk>/add-ons/google_apis-<api-level>/samples/MapsDemo

Ten en cuenta que, para que los objetos MapView puedan mostrar datos del servicio de Google Maps, debes registrarte en el servicio y recibir la clave de API de Google Maps, tal y como se describe a continuación.

Cómo obtener una clave de API de Google Maps

Los objetos MapView muestran mosaicos de Google Maps descargados desde el servicio de Google Maps. Para poder utilizar datos de Google Maps, debes registrarte en el servicio de Google Maps, aceptar las Condiciones de servicio y proporcionar una huella digital MD5 de los certificados que utilizarás para firmar tu aplicación. Para cada huella digital de certificado registrada, el servicio te proporciona una clave de API de Google Maps (una cadena alfanumérica que identifica tu certificado y a ti de forma única). A continuación, debes almacenar la clave de API en los objetos MapView, de forma que cuando soliciten datos de Google Maps, el servidor pueda determinar que te has registrado en el servicio.

Para obtener información detallada sobre cómo obtener y utilizar una clave de API de Google Maps, consulta esta sección.

Si no almacenas una clave de API de Google Maps válida en los elementos MapView, puedes compilar y ejecutar la aplicación, pero los elementos MapView no podrán mostrar datos del servidor de Google Maps. Por esta razón, debes registrarte para obtener una clave de API tan pronto como sea posible una vez hayas comenzado el proceso de desarrollo. El registro es gratuito y solo te llevará unos minutos.

Ten en cuenta que cada clave de API de Google Maps está asociada de forma única con un certificado de firma específico. Es decir:

  • Cuando inicias el proceso de desarrollo, puedes registrarte utilizando el certificado de depuración de errores que crean las herramientas del kit de desarrollo de software.
  • Cuando estás preparado para publicar tu aplicación, debes registrarte de nuevo utilizando el certificado con el que firmarás tu aplicación para publicarla. A continuación, debes actualizar los elementos MapView de forma que hagan referencia a la clave de API de publicación, en lugar de a la clave de depuración de errores y, a continuación, firma tu aplicación con el certificado de publicación.

Cómo firmar tu aplicación con el certificado adecuado

Si has seguido los pasos que se indican en la sección Cómo obtener una clave de API de Google Maps, el paso final para permitir la visualización de datos de Google Maps es firmar tu aplicación con el certificado adecuado. El certificado que utilices para firmar tu aplicación debe coincidir con el certificado asociado a la clave de API en los objetos MapView. Por ejemplo:

  • Si los objetos MapView hacen referencia a una clave de API que has obtenido registrando el certificado de depuración de errores, debes firmar la aplicación con este certificado.
  • Si quieres firmar la aplicación para publicarla, los objetos MapView deben hacer referencia a una clave de API que hayas obtenido registrando el certificado de publicación.

El servicio de Google Maps permite que los objetos MapView descarguen datos únicamente si se identifican con la clave de API correspondiente al certificado con el que se firma la aplicación. Por esta razón, recuerda que debes actualizar la clave de API de Google Maps a la que hacen referencia los objetos MapView siempre que cambies los certificados de firma.

Autenticación obligatoria

Tienes que acceder a Google+ para realizar esta acción.

Acceder a...

Desarrolladores de Google necesita tu permiso para realizar esta acción.