Get started

Get started with the ArcGIS Runtime API for Android:

  1. Review system requirements
  2. Install and set up
  3. Get an API key (to access services)
  4. Complete the Display a map tutorial

1. System requirements

Ensure your development environment meets the system requirements.

For an overview of this release, including enhancements, deprecations, and known issues, see the Release notes.

2. Install and set up

We recommend installing with Gradle, which will install the needed dependencies and SDK binaries from Esri's Maven repository. If you are unable to make use of Gradle, you can instead download the SDK and then add dependencies to your project manually by including the AAR library and dependency artifacts.

Get the API with Gradle

Perform the following set up steps in an existing Android Studio project, or create a new project.

  1. In your project-level build.gradle file, within the repositories block, add Esri's Maven repository URL to your project. Esri's repository is not open source and therefore not available in the default repository in the script, so you must specify this URL.

               
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    allprojects {
      repositories {
        google()
        jcenter()
    
        // Add the Esri public Maven repository
        maven {
            url 'https://esri.jfrog.io/artifactory/arcgis'
        }
      }
    }
    
  2. In your module-level build.gradle file, within the dependencies block, add the ArcGIS Runtime SDK for Android dependency to your app.

        
    1
    2
    3
    4
    dependencies {
      implementation 'com.esri.arcgisruntime:arcgis-android:100.12.0'
      ...
    }
    
  3. Android Studio supports a subset of Java 8 language features. These features are used throughout the ArcGIS Runtime API for Android documentation and samples. To ensure code examples compile if used in your apps, set the compatibility of your app module to use Java 8. In the app module build.gradle file, within the android block, add a compileOptions directive to set the Java compatibility version:

           
    1
    2
    3
    4
    5
    6
    7
    android {
      ...
      compileOptions {
        sourceCompatibility 1.8
        targetCompatibility 1.8
      }
    }

Get the API manually

If you are unable to make use of the public Gradle repository, you can instead download the SDK and add then dependencies to your project manually by including the local AAR and all dependency artifacts. You can also download a separate PDF of the Guide documentation.

Download Android SDK
  1. Sign in to ArcGIS Developer.
  2. On your Dashboard, click Downloads, and select the latest version of ArcGIS Runtime SDK for Android.
  3. Unzip the downloaded archive to a location on your development machine.

Manually add dependencies to the ArcGIS Runtime SDK for Android or use other resources contained in the download. The Android library module (.aar), found in the libs folder, contains the API jar libraries arcgis-android-api and its third-party dependencies and core native libraries

Setting up ArcGIS Android API to work with local Maven repository

The following setup steps assume that you are working in a development environment that is disconnected from the internet. For example, behind a firewall that doesn't allow access to Maven repositories that are hosted on the internet. If you are developing with internet access, please follow these setup steps instead: https://developers.arcgis.com/android/install-and-set-up/ . The following steps describe the setup with a Maven repository that is on your local machine, however they can be applied in a similar way if you have a Maven server set up on your network.

Deploy SDK and its dependencies to your computer
  1. Download the arcgis-runtime-sdk-android-100.12.0.zip file.

  2. Extract the contents of the archive to a location on disk.

  3. From the extracted location, copy the contents of the libs/aar directory to the following location on your disk:

    mac: /Users/[user-name]/.m2/repository/com/esri/arcgisruntime/arcgis-android/100.12.0/

    Windows: %USERPROFILE%\.m2\repository\com\esri\arcgisruntime\arcgis-android\100.12.0\

  4. Your full directory path should resemble the following:

    mac (2 files):

    /Users/[user-name]/.m2/repository/com/esri/arcgisruntime/arcgis-android/100.12.0/arcgis-android-100.12.0.aar

    /Users/[user-name]/.m2/repository/com/esri/arcgisruntime/arcgis-android/100.12.0/arcgis-android-100.12.0.pom

    Windows (2 files):

    %USERPROFILE%\.m2\repository\com\esri\arcgisruntime\arcgis-android\100.12.0\arcgis-android-100.12.0.aar

    %USERPROFILE%\.m2\repository\com\esri\arcgisruntime\arcgis-android\100.12.0\arcgis-android-100.12.0.pom

  5. If you are working with an internet connection, you may skip this step and step 6 below.

    If you are working offline, deploy all dependencies listed in the arcgis runtime SDK's pom file to your local Maven repo. A list of these dependencies and URLs from where they may be downloaded is below.

  6. If you are working offline, use maven to install the dependencies downloaded in step 5 above.

    • Install the mvn maven tool.

      mac:

      brew install mvn

      Windows:

      see https://maven.apache.org/guides/getting-started/windows-prerequisites.html

    • For androidx dependencies (browser and localbroadcastmanager), run:

      mvn install:install-file -Dfile=<relative path to aar> -DgroupId=<group ID> -DartifactId=<artifact id> -Dversion=<version> -Dpackaging=aar -DgeneratePom=true

    • For all other dependencies, run:

      mvn install:install-file -Dfile=<relative path to aar> -DgroupId=<group ID> -DartifactId=<artifact id> -Dversion=<version> -Dpackaging=jar -DgeneratePom=true

  7. Your local Maven repo should be set. We will confirm this in the next section.

Edit Gradle build scripts for project and app module
  1. You should edit your project build.gradle file to look at your local Maven repository. To do this, add the following to your project root build.gradle file:

         
    1
    2
    3
    4
    5
    allprojects {
        repositories {
            mavenLocal()
        }
    }
    
  2. In the app module build.gradle file, within the android block, add the following directive to set compatibility with Java 8 language features:

        
    1
    2
    3
    4
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
    
  3. Add the following dependencies to your app's build.gradle file.

                   
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    dependencies {
            ...
        implementation 'com.esri.arcgisruntime:arcgis-android:100.12.0'
        implementation 'com.google.code.gson:gson:2.8.6'
        implementation 'androidx.browser:browser:1.3.0'
        implementation 'androidx.localbroadcastmanager:localbroadcastmanager:1.0.0'
        implementation 'org.apache.httpcomponents.core5:httpcore5:5.0.4'
        implementation 'org.apache.httpcomponents.core5:httpcore5-h2:5.0.4'
        implementation 'org.slf4j:slf4j-api:1.7.25'
        implementation 'commons-codec:commons-codec:1.15'
        implementation 'org.conscrypt:conscrypt-openjdk-uber:2.2.1'
        implementation 'net.spy:spymemcached:2.12.3'
        implementation 'org.ehcache.modules:ehcache-api:3.4.0'
    
    }
    

3. Access services and content with an API key

API keys are permanent tokens that grant your application access to ready-to-use services and, with an ArcGIS Developer account, private content hosted in ArcGIS Platform (currently in beta). Your apps will always require an access token, such as an API key or OAuth 2.0 token, in order to access these resources. Refer to authentication methods in the developer guide for details.

To set an API key in your application, find and copy an API key from your developer dashboard and replace the string YOUR_API_KEY / ACCESS_TOKEN in your code with the API key copied from your dashboard. This key is scoped to provide access to all of the services and resources shown in the tutorials.

  1. Log in to your developer dashboard.
  2. Select and copy your default API key, or generate a new one.
  3. In your code, replace the string YOUR_API_KEY / ACCESS_TOKEN with the API key from your dashboard.

4. Tutorials

Deploy your app

No license is required to develop ArcGIS Runtime apps; there is no need to authorize your development machine or devices. As a member of the ArcGIS Developer Program, you have a free ArcGIS Developer Account (Essentials Plan). With this plan, you can download and install any ArcGIS API and immediately have access to all the functionality of the APIs for development purposes. You can become a member of the developer program for free.

You need an ArcGIS Developer Subscription to deploy an app to your users. The Essentials plan is free.

Learn more about Runtime licensing and deployment and get your license string at License and deployment.

Next steps

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.