Get started with the ArcGIS Runtime API for Android:
- Review system requirements
- Install and set up
- Get an API key (to access services)
- 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.
-
In your settings.gradle file, within the
repositories
block of thedependency
block, add aResolution Management maven
block and specify the URL of Esri's Maven repository. Esri's repository is not open source and therefore not available fromgoogle()
ormaven
, so you must specify this URL.Central() settings.gradleUse dark colors for code blocks dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { google() mavenCentral() maven { url 'https://esri.jfrog.io/artifactory/arcgis' } } }
-
In your module-level build.gradle file, within the
dependencies
block, add the ArcGIS Runtime SDK for Android dependency to your app.build.gradleUse dark colors for code blocks dependencies { . . . implementation 'com.esri.arcgisruntime:arcgis-android:100.15.5' }
-
In your module-level build.gradle file, within the
android
block, make sure you have the following directive to set compatibility with Java 8 language features:build.gradleUse dark colors for code blocks Copy android { . . . compileOptions { sourceCompatibility JavaVersion.VERSION_1_8 targetCompatibility JavaVersion.VERSION_1_8 } . . . }
-
In your module-level build.gradle file, within the
android
block, make sure you have abuild
block that enables view binding. For more information on view binding, see https://developer.android.com/topic/libraries/view-binding.Features build.gradleUse dark colors for code blocks Copy android { . . . buildFeatures { viewBinding true } . . . }
-
In your module-level build.gradle file, within the
android
block, make sure you have apackaging
block that excludes duplicates of theOptions META-INF\DEPENDENCIES
file. This setting will prevent a compiler error that occurs if you try to include the same file in theMETA-INF
directory more than once in the output. For more information on packaging options, see https://developer.android.com/reference/tools/gradle-api/7.4/com/android/build/api/dsl/PackagingOptions.build.gradleUse dark colors for code blocks Copy android { . . . packagingOptions { exclude 'META-INF/DEPENDENCIES' } . . . }
Get the API manually
If you are unable to make use of the public Gradle repository, you can instead download the SDK and add the dependencies to your project manually by including the local AAR and all dependency artifacts. On the Downloads page, you can also download a separate PDF of the Guide documentation.
- Click the downloads link, and select the latest version of ArcGIS Runtime SDK for Android.
- 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 Get the API with Gradle instead.
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
-
Obtain the
arcgis-runtime-sdk-android-100.15.5.zip file
in whatever way is compatible with the security measures at your work environment. -
Extract the contents of the archive to a location on disk.
-
From the extracted location, copy the contents of the
libs/aar
directory to the following location on your disk. (Note that your local Maven repo is the directory tree rooted at.m2\repository
in your user directory.)mac:
/Users/[user-name]/.m2/repository/com/esri/arcgisruntime/arcgis-android/100.15.5/
Windows:
%USERPROFILE%\.m2\repository\com\esri\arcgisruntime\arcgis-android\100.15.5\
-
Your full directory path should resemble the following:
mac (2 files):
/Users/[user-name]/.m2/repository/com/esri/arcgisruntime/arcgis-android/100.15.5/arcgis-android-100.15.5.aar
/Users/[user-name]/.m2/repository/com/esri/arcgisruntime/arcgis-android/100.15.5/arcgis-android-100.15.5.pom
Windows (2 files):
%USERPROFILE%\.m2\repository\com\esri\arcgisruntime\arcgis-android\100.15.5\arcgis-android-100.15.5.aar
%USERPROFILE%\.m2\repository\com\esri\arcgisruntime\arcgis-android\100.15.5\arcgis-android-100.15.5.pom
-
A list of these dependencies and the URLs from where they may be downloaded is below. You should obtain them in whatever way is compatible with the security measures at your work environment.
- gson 2.9.0: https://search.maven.org/artifact/com.google.code.gson/gson/2.9.0/jar
- androidx.browser 1.4.0: https://maven.google.com/web/index.html?q=browser#androidx.browser:browser:1.4.0
- androidx.localbroadcastmanager 1.1.0: https://maven.google.com/web/index.html?q=localbroadcastmanager#androidx.localbroadcastmanager:localbroadcastmanager:1.1.0
- httpcore5 5.0.4: https://search.maven.org/artifact/org.apache.httpcomponents.core5/httpcore5/5.0.4/jar
- httpcore5-h2 5.0.4: https://search.maven.org/artifact/org.apache.httpcomponents.core5/httpcore5-h2/5.0.4/jar
- slf4j-api 1.7.32: https://search.maven.org/artifact/org.slf4j/slf4j-api/1.7.32/jar
- commons-codec 1.15: https://search.maven.org/artifact/commons-codec/commons-codec/1.15/jar
- conscrypt-openjdk-uber 2.2.1 https://search.maven.org/artifact/org.conscrypt/conscrypt-openjdk-uber/2.2.1/jar
- spymemcached 2.12.3 https://search.maven.org/artifact/net.spy/spymemcached/2.12.3/jar
- ehcache-api 3.4.0 https://search.maven.org/artifact/org.ehcache.modules/ehcache-api/3.4.0/jar
-
Deploy the dependencies you downloaded in the previous step. You use Maven to install the dependencies in your local Maven repo.
-
Install the
mvn
Maven tool.mac:
brew install mvn
Windows:
See https://maven.apache.org/guides/getting-started/windows-prerequisites.html for information about installing the
mvn
Maven tool. -
For androidx dependencies (
browser
andlocalbroadcastmanager
), run:mvn install:
install-file -Dfile=<relative path to aar> -Dgroup Id=<group ID> -Dartifact Id=<artifact id> -Dversion=<version> -Dpackaging=aar -Dgenerate Pom=true -
For all other dependencies, run:
mvn install:
install-file -Dfile=<relative path to aar> -Dgroup Id=<group ID> -Dartifact Id=<artifact id> -Dversion=<version> -Dpackaging=jar -Dgenerate Pom=true
-
-
Your local Maven repo should be set. We will modify the build files to use your local Maven repo in the next section.
Edit Gradle build settings and scripts
-
You should edit your project gradle.settings file to look at your local Maven repository. To do this, add
maven
as follows:Local() gradle.settingsUse dark colors for code blocks dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { google() mavenCentral() mavenLocal() } }
-
In your module-level build.gradle file, add the following dependencies:
build.gradleUse dark colors for code blocks dependencies { . . . implementation 'com.esri.arcgisruntime:arcgis-android:100.15.5' implementation 'com.google.code.gson:gson:2.9.0' implementation 'androidx.browser:browser:1.4.0' implementation 'androidx.localbroadcastmanager:localbroadcastmanager:1.1.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.32' 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' }
-
In your module-level build.gradle file, within the
android
block, make sure you have the following directive to set compatibility with Java 8 language features:build.gradleUse dark colors for code blocks Copy android { . . . compileOptions { sourceCompatibility JavaVersion.VERSION_1_8 targetCompatibility JavaVersion.VERSION_1_8 } . . . }
-
In your module-level build.gradle file, within the
android
block, make sure you have abuild
block that enables view binding. For more information on view binding, see https://developer.android.com/topic/libraries/view-binding.Features build.gradleUse dark colors for code blocks Copy android { . . . buildFeatures { viewBinding true } . . . }
-
In your module-level build.gradle file, within the
android
block, make sure you have apackaging
block that excludes duplicates of theOptions META-INF
. This setting will prevent a compiler error that occurs if you try to include the same file in theMETA-INF
directory more than once in the output. For more information on packaging options, see https://developer.android.com/reference/tools/gradle-api/7.4/com/android/build/api/dsl/PackagingOptions.build.gradleUse dark colors for code blocks Copy android { . . . packagingOptions { exclude 'META-INF/DEPENDENCIES' } . . . }
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. 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_
/ ACCESS_
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.
- Log in to your developer dashboard.
- Select and copy your default API key, or generate a new one.
- In your code, replace the string
YOUR_
/API_ KEY ACCESS_
with the API key from your dashboard.TOKEN
- Learn more about API keys in the developer guide.
4. Tutorials
Follow step-by-step instructions to build apps that incorporate ArcGIS Runtime functionality.
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.