Quickstart: Create an Android app with Azure Maps

• 12/10/2020
• 6 minutes to read
• • r
  • D
  • a

This article shows you how to add the Azure Maps to an Android app. It walks you through these basic steps:

• Setup your development environment.
• Create your own Azure Maps account.
• Get your primary Azure Maps key to use in the app.
• Reference the Azure Maps libraries from the project.
• Add an Azure Maps control to the app.

Prerequisites

1. Create an Azure Maps account by signing into the Azure portal. If you don't have an Azure subscription, create a free account before you begin.
2. Make an Azure Maps account
3. Obtain a primary subscription key, also known as the primary key or the subscription key. For more information on authentication in Azure Maps, see manage authentication in Azure Maps.
4. Download Android Studio for free from Google.

Create an Azure Maps account

Create a new Azure Maps account with the following steps:

1. In the upper left-hand corner of the Azure portal, click Create a resource.

2. In the Search the Marketplace box, type Azure Maps.

3. From the Results, select Azure Maps. Click Create button that appears below the map.

4. On the Create Maps Account page, enter the following values:

   • The Subscription that you want to use for this account.
   • The Resource group name for this account. You may choose to Create new or Use existing resource group.
   • The Name of your new account.
   • The Pricing tier for this account.
   • Read the License and Privacy Statement, and check the checkbox to accept the terms.
   • Click the Create button.

   

Get the primary key for your account

Once your Maps account is successfully created, retrieve the primary key that enables you to query the Maps APIs.

1. Open your Maps account in the portal.
2. In the settings section, select Authentication.
3. Copy the Primary Key to your clipboard. Save it locally to use later in this tutorial.

Create a project in Android Studio

First, create a new project with an empty activity. Complete these steps to create an Android Studio project:

1. Under Choose your project, select Phone and Tablet. Your application will run on this form factor.
2. On the Phone and Tablet tab, select Empty Activity, and then select Next.
3. Under Configure your project, select API 21: Android 5.0.0 (Lollipop) as the minimum SDK. This is the earliest version supported by the Azure Maps Android SDK.
4. Accept the default Activity Name and Layout Name and select Finish.

See the Android Studio documentation for more help with installing Android Studio and creating a new project.

Set up a virtual device

Android Studio lets you set up a virtual Android device on your computer. Doing so can help you test your application during development. To set up a virtual device, select the Android Virtual Device (AVD) Manager icon in the upper-right corner of your project screen, and then select Create Virtual Device. You can also get to the AVD Manager by selecting Tools > Android > AVD Manager from the toolbar. In the Phones category, select Nexus 5X, and then select Next.

You can learn more about setting up an AVD in the Android Studio documentation.

Install the Azure Maps Android SDK

The next step in building your application is to install the Azure Maps Android SDK. Complete these steps to install the SDK:

1. Open the top-level build.gradle file and add the following code to the all projects, repositories block section:

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

2. Update your app/build.gradle and add the following code to it:

   1. Make sure that your project's minSdkVersion is at API 21 or higher.

   2. Add the following code to the Android section:

      compileOptions {
          sourceCompatibility JavaVersion.VERSION_1_8
          targetCompatibility JavaVersion.VERSION_1_8
      }
      

   3. Update your dependencies block and add a new implementation dependency line for the latest Azure Maps Android SDK:

      implementation "com.microsoft.azure.maps:mapcontrol:0.6"
      

      Note

      You can set the version number to "0+" to have your code always point to the latest version.

   4. Go to File in the toolbar and then click on Sync Project with Gradle Files.

3. Add a map fragment to the main activity (res > layout > activity_main.xml):

   <?xml version="1.0" encoding="utf-8"?>
   <FrameLayout
       xmlns:android="http://schemas.android.com/apk/res/android"
       xmlns:app="http://schemas.android.com/apk/res-auto"
       android:layout_width="match_parent"
       android:layout_height="match_parent"
       >
   
       <com.microsoft.azure.maps.mapcontrol.MapControl
           android:id="@+id/mapcontrol"
           android:layout_width="match_parent"
           android:layout_height="match_parent"
           />
   </FrameLayout>
   

4. In the MainActivity.java file you'll need to:

   • add imports for the Azure Maps SDK
   • set your Azure Maps authentication information
   • get the map control instance in the onCreate method

   Setting the authentication information on the AzureMaps class globally using the setSubscriptionKey or setAadProperties methods makes it so you won't have to add your authentication information on every view.

   The map control contains its own lifecycle methods for managing Android's OpenGL lifecycle. These lifecycle methods must be called directly from the containing Activity. For your app to correctly call the map control's lifecycle methods, you must override the following lifecycle methods in the Activity that contains the map control. And, you must call the respective map control method.

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

   Edit the MainActivity.java file as follows:

   package com.example.myapplication;
   
   //For older versions use: import android.support.v7.app.AppCompatActivity; 
   import androidx.appcompat.app.AppCompatActivity;
   import com.microsoft.azure.maps.mapcontrol.AzureMaps;
   import com.microsoft.azure.maps.mapcontrol.MapControl;
   import com.microsoft.azure.maps.mapcontrol.layer.SymbolLayer;
   import com.microsoft.azure.maps.mapcontrol.options.MapStyle;
   import com.microsoft.azure.maps.mapcontrol.source.DataSource;
   
   public class MainActivity extends AppCompatActivity {
   
   static {
       AzureMaps.setSubscriptionKey("<Your Azure Maps 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);
   }}
   

   Note

   After you complete the preceding steps, you'll probably get warnings from Android Studio about some of the code. To resolve these warnings, import the classes referenced in MainActivity.java. You can automatically import these classes by selecting Alt + Enter (Option + Return on a Mac).

5. Select the run button, as shown in the following graphic (or press Control + R on a Mac), to build your application.

   

Android Studio will take a few seconds to build the application. After the build is complete, you can test your application in the emulated Android device. You should see a map like this one:

Clean up resources

If you don't plan to continue to the tutorials, take these steps to clean up the resources:

1. Close Android Studio and delete the application you created.
2. If you tested the application on an external device, uninstall the application from that device.

If you don't plan on continuing to develop with the Azure Maps Android SDK:

1. Navigate to the Azure portal page. Select All resources from the main portal page. Or, click on the menu icon in the upper left-hand corner. Select All resources.
2. Click on your Azure Maps account. At the top of the page, click Delete.
3. Optionally, if you don't plan to continue developing Android apps, uninstall Android Studio.

For more code examples, see these guides:

• Manage authentication in Azure Maps
• Change map styles in Android maps
• Add a symbol layer
• Add a line layer
• Add a polygon layer

Next steps

In this quickstart, you created your Azure Maps account and created a demo application. Take a look at the following tutorials to learn more about Azure Maps: