Inicio rápido: Creación de una aplicación de Android con Azure Maps

En este artículo se muestra cómo agregar Azure Maps a una aplicación de Android. Le guía por estos pasos básicos:

• Configurar su entorno de desarrollo
• Cree su propia cuenta de Azure Maps.
• Obtenga la clave principal de Azure Maps que se usará en la aplicación.
• Haga referencia a las bibliotecas de Azure Maps desde el proyecto.
• Agregue un control de Azure Maps a la aplicación.

Nota:

Retirada de Android SDK para Azure Maps

El SDK nativo de Azure Maps para Android ya está en desuso y se retirará el 3/31/25. Para evitar interrupciones del servicio, migre al SDK de Azure Maps para web antes del 31 de marzo de 2025. Para obtener más información, consulte la Guía de migración del SDK de Maps para Android.

Requisitos previos

1. Una suscripción a Microsoft Azure. Si no tiene una suscripción a Azure, cree una cuenta gratuita antes de empezar.

2. Android Studio. Si no tiene Android Studio, puede obtenerlo de forma gratuita en Google.

Nota:

Muchas de las instrucciones de este inicio rápido se crearon con Android Studio Arctic Fox (2020.3.1). Si usa una versión diferente de Android Studio, los pasos específicos de Android Studio pueden variar.

Crear una cuenta de Azure Maps

Cree una nueva cuenta de Azure Maps con los pasos siguientes:

1. En la esquina superior izquierda de Azure Portal, seleccione Crear un recurso.

2. En el cuadro Buscar en el Marketplace, escriba Azure Maps y, a continuación, seleccione Azure Maps en los resultados de la búsqueda.

3. Seleccione el botón Crear.

4. En la página Create Maps Account (Crear una cuenta de Azure Maps), escriba los siguientes valores:

   • La suscripción que quiere usar para esta cuenta.
   • El nombre del grupo de recursos para esta cuenta. Puede elegir Crear nuevo o Usar existente para el grupo de recursos.
   • El nombre de la nueva cuenta.
   • El Plan de tarifa de la cuenta. Seleccione Gen2.
   • Lea los términos y condiciones y active la casilla para confirmar que ha leído y acepta la licencia y la declaración de privacidad.
   • Seleccione el botón Revisar y crear.
   • Cuando se haya asegurado de que todo es correcto en la página Revisar y crear, seleccione el botón Crear.

   

Obtener la clave de suscripción de su cuenta

Una vez que se haya creado correctamente la cuenta de Azure Maps, recupere la clave de suscripción que le permitirá consultar las API de Maps.

1. Abra su cuenta de Azure Maps en el portal.
2. En el panel izquierdo, seleccione Autenticación.
3. Copie la clave principal y guárdela localmente para usarla más adelante en este tutorial.

Nota

Por motivos de seguridad, se recomienda que rote las claves principal y secundaria. Para rotar las claves, actualice la aplicación para que use la clave secundaria, impleméntela y, luego, presione el botón de ciclo/actualización situado junto a la clave principal para generar una nueva clave principal. La clave principal anterior se deshabilitará. Para más información sobre la rotación de claves, consulte Configuración de Azure Key Vault con la auditoría y la rotación de claves.

Creación de un proyecto en Android Studio

Complete los pasos siguientes para crear un proyecto con una actividad vacía en Android Studio:

1. Inicie Android Studio, seleccione New (Nuevo) en el menú File (Archivo) y, a continuación, New Project... (Nuevo proyecto...).

2. En la pantalla New Project (Nuevo proyecto), seleccione Phone and Tablet (Teléfono y tableta) en la lista Templates (Plantillas) del lado izquierdo de la pantalla.

   

3. Seleccione Empty Activity (Actividad vacía) en la lista de plantillas y, a continuación, Next (Siguiente).

   

4. En la pantalla Actividad vacía, escriba valores para los campos siguientes:

   • Nombre. Enter AzureMapsApp.
   • Nombre del paquete. Use la aplicación com.example.azuremapsapp predeterminada.
   • Ubicación de almacenamiento Use el valor predeterminado o seleccione una nueva ubicación para guardar los archivos del proyecto. Evite el uso de espacios en la ruta de acceso o el nombre de archivo debido a posibles problemas con las herramientas de NDK.
   • Idioma. Seleccione Kotlin o Java.
   • Minimum SDK (SDK mínimo). Seleccione API 21: Android 5.0.0 (Lollipop) como el SDK mínimo. Se trata de la versión más antigua compatible con Android SDK para Azure Maps.

5. Seleccione Finish (Finalizar) para crear el nuevo proyecto.

Consulte la documentación de Android Studio a fin de obtener más ayuda para la instalación de Android Studio y la creación de un proyecto.

Configuración de un dispositivo virtual

Android Studio permite configurar un dispositivo virtual Android en el equipo. Esto puede ayudarle a probar la aplicación durante el desarrollo.

Para configurar un dispositivo virtual Android (AVD):

1. Seleccione AVD Manager en el menú Tools (Herramientas).
2. Aparece el administrador de dispositivos virtuales Android. Seleccione Create Virtual Device (Crear dispositivo virtual).
3. En la categoría Phones (Teléfonos), seleccione Nexus 5X y haga clic en Next (Siguiente).

Para obtener más información sobre cómo configurar un AVD, consulte Crear y administrar dispositivos virtuales en la documentación de Android Studio.

Instalación de Android SDK para Azure Maps

El siguiente paso en la creación de la aplicación es instalar el Android SDK para Azure Maps. Para instalar el SDK, siga estos pasos:

1. Abra el archivo de configuración del proyecto settings.gradle y agregue el código siguiente a la sección de repositorios:

   maven {url "https://atlas.microsoft.com/sdk/android"}
   

2. En el mismo archivo de configuración del proyecto settings.gradle, cambie repositoriesMode a PREFER_SETTINGS:

   repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)
   

   El archivo de configuración del proyecto debería aparecer ahora de la siguiente manera:

   

3. Abra el archivo gradle.properties del proyecto y compruebe que android.useAndroidX y android.enableJetifier están establecidos en true.

   Si el archivo gradle.properties no incluye android.useAndroidX y android.enableJetifier, agregue las dos líneas siguientes al final del archivo:

   android.useAndroidX=true
   android.enableJetifier=true
   

4. Abra el archivo build.gradle de la aplicación y haga lo siguiente:

   1. Compruebe que el minSdk del proyecto es 21 o superior.

   2. Asegúrese de que compileOptions en la sección Android sea el siguiente:

      compileOptions {
          sourceCompatibility JavaVersion.VERSION_1_8
          targetCompatibility JavaVersion.VERSION_1_8
      }
      

   3. Actualice el bloque de dependencias y agregue una nueva dependencia de implementación para Android SDK de Azure Maps más reciente:

      implementation 'com.azure.android:azure-maps-control:1.+'
      

   4. Seleccione Sync Project with Gradle Files (Sincronizar Project archivos de Gradle) en el menú Archivo.

   

5. Agregue un fragmento de mapa a la actividad principal:

   <com.azure.android.maps.control.MapControl
       android:id="@+id/mapcontrol"
       android:layout_width="match_parent"
       android:layout_height="match_parent"
       />
   

   Para actualizar la actividad principal, seleccione aplicación > res > layout >activity_main.xml en el navegador del proyecto:

   

6. En el archivo MainActivity.java:

   • Agregar las importaciones para el SDK de Azure Maps.
   • Establecer la información de autenticación de Azure Maps.
   • Obtener la instancia del control de mapa en el método onCreate.

   Sugerencia

   Al configurar la información de autenticación en la clase AzureMaps de forma global mediante los métodos setSubscriptionKey o setAadProperties, no será necesario agregar la información de autenticación en cada vista.

   El control de mapa contiene sus propios métodos de ciclo de vida para administrar el ciclo de vida de OpenGL de Android. Estos métodos de ciclo de vida deben llamarse directamente desde la actividad contenedora. Para llamar correctamente a los métodos de ciclo de vida del control de mapa, invalide los siguientes métodos de ciclo de vida en la actividad que contiene el control de mapa y, a continuación, llame al método del control de mapa correspondiente.

   • onCreate(Bundle)
   • onDestroy()
   • onLowMemory()
   • onPause()
   • onResume()
   • onSaveInstanceState(Bundle)
   • onStart()
   • onStop()

   Edite el MainActivity.java como sigue:

   package com.example.azuremapsapp;
   
   import androidx.appcompat.app.AppCompatActivity;
   import android.os.Bundle;
   import com.azure.android.maps.control.AzureMaps;
   import com.azure.android.maps.control.MapControl;
   import com.azure.android.maps.control.layer.SymbolLayer;
   import com.azure.android.maps.control.options.MapStyle;
   import com.azure.android.maps.control.source.DataSource;
   
   public class MainActivity extends AppCompatActivity {
   
   static {
       AzureMaps.setSubscriptionKey("<Your-Azure-Maps-Primary-Subscription-Key>");
   
       //Alternatively use Azure Active Directory authenticate.
       //AzureMaps.setAadProperties("<Your-AAD-clientId>", "<Your-AAD-appId>", "<Your-AAD-tenant>");
   }
   
   MapControl mapControl;
   
   @Override
   protected void onCreate(Bundle savedInstanceState) {
       super.onCreate(savedInstanceState);
       setContentView(R.layout.activity_main);
   
       mapControl = findViewById(R.id.mapcontrol);
   
       mapControl.onCreate(savedInstanceState);
   
       //Wait until the map resources are ready.
       mapControl.onReady(map -> {
   
           //Add your post map load code here.
   
       });
   }
   
   @Override
   public void onResume() {
       super.onResume();
       mapControl.onResume();
   }
   
   @Override
   protected void onStart(){
       super.onStart();
       mapControl.onStart();
   }
   
   @Override
   public void onPause() {
       super.onPause();
       mapControl.onPause();
   }
   
   @Override
   public void onStop() {
       super.onStop();
       mapControl.onStop();
   }
   
   @Override
   public void onLowMemory() {
       super.onLowMemory();
       mapControl.onLowMemory();
   }
   
   @Override
   protected void onDestroy() {
       super.onDestroy();
       mapControl.onDestroy();
   }
   
   @Override
   protected void onSaveInstanceState(Bundle outState) {
       super.onSaveInstanceState(outState);
       mapControl.onSaveInstanceState(outState);
   }}
   

7. En el archivo MainActivity.kt:

   • agregar las importaciones del SDK de Azure Maps
   • establecer la información de autenticación de Azure Maps
   • obtener la instancia del control de mapa en el método onCreate

   Sugerencia

   Al configurar la información de autenticación en la clase AzureMaps de forma global mediante los métodos setSubscriptionKey o setAadProperties, no será necesario agregar la información de autenticación en cada vista.

   El control de mapa contiene sus propios métodos de ciclo de vida para administrar el ciclo de vida de OpenGL de Android. Estos métodos de ciclo de vida deben llamarse directamente desde la actividad contenedora. Para llamar correctamente a los métodos de ciclo de vida del control de mapa, invalide los siguientes métodos de ciclo de vida en la actividad que contiene el control de mapa. Además, debe llamar al método de control de mapa correspondiente.

   • onCreate(Bundle)
   • onDestroy()
   • onLowMemory()
   • onPause()
   • onResume()
   • onSaveInstanceState(Bundle)
   • onStart()
   • onStop()

   Edite el archivo MainActivity.kt de este modo:

   package com.example.azuremapsapp;
   
   import androidx.appcompat.app.AppCompatActivity
   import android.os.Bundle
   import com.azure.android.maps.control.AzureMap
   import com.azure.android.maps.control.AzureMaps
   import com.azure.android.maps.control.MapControl
   import com.azure.android.maps.control.events.OnReady
   
   class MainActivity : AppCompatActivity() {
   
       companion object {
           init {
               AzureMaps.setSubscriptionKey("<Your-Azure-Maps-Primary-Subscription-Key>");
   
               //Alternatively use Azure Active Directory authenticate.
               //AzureMaps.setAadProperties("<Your-AAD-clientId>", "<Your-AAD-appId>", "<Your-AAD-tenant>");
           }
       }
   
       var mapControl: MapControl? = null
   
       override fun onCreate(savedInstanceState: Bundle?) {
           super.onCreate(savedInstanceState)
           setContentView(R.layout.activity_main)
   
           mapControl = findViewById(R.id.mapcontrol)
   
           mapControl?.onCreate(savedInstanceState)
   
           //Wait until the map resources are ready.
           mapControl?.onReady(OnReady { map: AzureMap -> })
       }
   
       public override fun onStart() {
           super.onStart()
           mapControl?.onStart()
       }
   
       public override fun onResume() {
           super.onResume()
           mapControl?.onResume()
       }
   
       public override fun onPause() {
           mapControl?.onPause()
           super.onPause()
       }
   
       public override fun onStop() {
           mapControl?.onStop()
           super.onStop()
       }
   
       override fun onLowMemory() {
           mapControl?.onLowMemory()
           super.onLowMemory()
       }
   
       override fun onDestroy() {
           mapControl?.onDestroy()
           super.onDestroy()
       }
   
       override fun onSaveInstanceState(outState: Bundle) {
           super.onSaveInstanceState(outState)
           mapControl?.onSaveInstanceState(outState)
       }
   }
   

8. Seleccione el botón de ejecución en la barra de herramientas, como se muestra en la siguiente imagen (o presione Control + R en un equipo Mac), para compilar la aplicación.

   

Android Studio tarda unos segundos en crear la aplicación. Una vez finalizada la compilación, puede probar la aplicación en el dispositivo Android emulado. Debería ver un mapa como el siguiente:

Sugerencia

De forma predeterminada, Android vuelve a cargar la actividad cuando cambia la orientación o el teclado está oculto. Esto da como resultado que se restablezca el estado del mapa (vuelva a cargar el mapa que restablece la vista y vuelve a cargar los datos al estado inicial). Para evitar que esto suceda, agregue lo siguiente al manifiesto: android:configChanges="orientation|keyboardHidden". Esto impedirá que la actividad se vuelva a cargar y, en su lugar, llame onConfigurationChanged() a cuando la orientación haya cambiado o el teclado esté oculto.

Limpieza de recursos

Advertencia

Los tutoriales que se enumeran en la sección Pasos siguientes describen cómo usar y configurar Azure Maps con su cuenta. Si tiene pensado seguir con los tutoriales, no elimine los recursos que se crearon con este inicio rápido.

Si no tiene previsto continuar con los tutoriales, siga estos pasos para realizar la limpieza de recursos:

1. Cierre Android Studio y elimine la aplicación que ha creado.
2. Si ha probado la aplicación en un dispositivo externo, desinstálela del mismo.

Si no planea continuar desarrollando con el Android SDK de Azure Maps:

1. Vaya a la página de Azure Portal. En la página principal del portal, seleccione Todos los recursos.
2. Seleccione la cuenta de Azure Maps. En la parte superior de la página, seleccione Eliminar.
3. Si no planea seguir desarrollando aplicaciones de Android, puede desinstalar Android Studio.

Para ver más ejemplos de código, consulte estas guías:

• Administración de la autenticación en Azure Maps
• Cambio de estilos de mapa en mapas de Android
• Adición de una capa de símbolo
• Adición de una capa de línea
• Adición de una capa de polígono

Pasos siguientes

En esta guía de inicio rápido, ha creado la cuenta de Azure Maps y ha creado una aplicación de demostración. Consulte el siguiente tutorial para más información sobre Azure Maps:

Tutorial: Carga de datos GeoJSON en Android SDK de Azure Maps