Before installing ArcGIS Maps SDK for Kotlin, make sure your development machine meets the system requirements. A minimum Android API version is required for any target device on which your app will run. For more information, see system requirements.
We recommend installing with Gradle, which will install the needed dependencies and SDK binaries from Esri's Maven repository.
Get the API with Gradle
Perform the following set up steps in the project created for you by Android Studio's New Project wizard.
-
In settings.gradle.kts: find the
repositories
block (which is nested insidedependency
), and add aResolution Management maven
block, specifying the URL of Esri's Maven repository. Because Esri's repository is not open source, it is not available fromgoogle()
ormaven
: you must specify its URL here.Central() settings.gradle.ktsUse dark colors for code blocks dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { google() mavenCentral() maven { url = uri("https://esri.jfrog.io/artifactory/arcgis") } } }
-
In your module-level build.gradle.kts (Module :app) file, within the
dependencies
block, add the ArcGIS Maps SDK for Kotlin dependency to your app.build.gradle.kts (Module: app)Use dark colors for code blocks dependencies { . . . // ArcGIS Map Kotlin SDK dependency implementation("com.esri:arcgis-maps-kotlin:200.4.0") }
-
Add dependencies that provide ready-to-use Compose components published by Esri. Defined in the ArcGIS Maps SDK for Kotlin Toolkit, these Compose components access classes from the standard APIs in ArcGIS Maps SDK for Kotlin. The Toolkit is the most efficient way to include tested UI elements that are Compose-based and compatible with ArcGIS Maps SDK for Kotlin.
Declare a dependency on the Toolkit module named
geoview-compose
. This module contains composable functions to implement map views and scene views. The Toolkit contains several other useful Compose-based modules. Add to thedependency
block any other Toolkit modules you will use.build.gradle.kts (Module: app)Use dark colors for code blocks dependencies { . . . // ArcGIS Map Kotlin SDK dependency implementation("com.esri:arcgis-maps-kotlin:200.4.0") // Toolkit dependencies implementation("com.esri:arcgis-maps-kotlin-toolkit-geoview-compose:200.4.0") // Additional modules from Toolkit, if needed, such as: // implementation("com.esri:arcgis-maps-kotlin-toolkit-authentication:200.4.0") }
Artifact versioning (Alternative)
In the code above, Toolkit dependencies specify their artifact version. Alternatively, you can rely on the Toolkit's BOM (Bill of Materials), which specifies versions of the individual toolkit components that are compatible with each other. You can see these version numbers by examining the BOM's .pom file. For more information, see the toolkit repo's top-level README. Note that the Toolkit BOM itself has a version number.
Gradle Version Catalogs are the state-of-the-art way to manage dependency versions. A file named
gradle/libs.versions.toml
declares a variable for each dependency's Maven name and variables for version numbers. All dependencies can be declared here, including Toolkit BOM, Toolkit modules, ArcGIS Maps SDK for Kotlin, Kotlin libraries, and Android libraries. In recent releases of Android Studio, the New Project wizard creates that file for you.Modified to use the Toolkit BOM, the
build.gradle.kts
code looks as follows. Note that the variables, such aslibs.arcgis.map.kotlin.toolkit.bom
andlibs.arcgis.maps.kotlin.toolkit.geoview.compose
, do not specify their version, sincegradle/libs.versions.toml
manages versions.Use dark colors for code blocks // ArcGIS Maps for Kotlin - SDK dependency implementation(libs.arcgis.maps.kotlin) // Toolkit dependencies implementation(platform(libs.arcgis.maps.kotlin.toolkit.bom)) implementation(libs.arcgis.maps.kotlin.toolkit.geoview.compose) // Additional modules from Toolkit, if needed, such as: // implementation(libs.arcgis.maps.kotlin.toolkit.authentication)
-
The module-level
build.gradle.kts
file generated by the Android Studio New Project wizard declares Android and Kotlin tool versions that should all work together. The options for the Compose Compiler and the Kotlin Compiler must be compatible. You can confirm compatibility by consulting Android's Compose to Kotlin Compatibility Map.build.gradle.kts (Module: app)Use dark colors for code blocks Copy android { . . . kotlinOptions { jvmTarget = "1.8" } buildFeatures { compose = true // Enable Jetpack Compose for this project. } composeOptions { kotlinCompilerExtensionVersion = "1.5.11" } . . . }
Required permissions and features
Android is a permissions-separated operating system. Depending on which ArcGIS capabilities you use in your app, you may need to add permissions to your manifest. Make sure that you do not include permissions for capabilities that are not included in your app.
If an app is running on Android API version 22 or earlier, all permissions are requested (and granted or denied), at installation time. If an app is running on Android API version 23 or newer, permissions are requested and automatically granted at installation time. Potentially dangerous permissions, however, must be requested at run time, and you need to add code to your app to do so. The Android framework or Android Support library is used to check for and request permissions if not already granted. For more information, see Declaring Permissions and Requesting Permissions at Run Time.
ArcGIS Maps SDK for Kotlin capabilities requiring permissions
Some of the capabilites of ArcGIS Maps SDK for Kotlin that you use in your app require Android permissions.
- Access to the Internet (most apps will require this): normal permission in Android API 23 and newer.
- Access to the device's GPS will require fine location permissions: dangerous permission in Android API 23 and newer.
The following code example (for the AndroidManifest.xml file) includes these permissions:
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
Android storage and permissions
As of Android API Level 30, all apps use scoped storage for accessing the file system of the Android device. With scoped storage, an app can access (1) its own files and (2) shared files in a media store. Declaring the <uses-permission android:
permission is no longer supported.
Storage in Android has changed dramatically since API level 29. Consult the following links to learn more about Android storage and permissions:
- Data and file storage overview
- Android storage use cases and best practices
- Access media files from shared storage
- Manage all files on a storage device
Declaring OpenGL ES version
Adding a uses-feature element to the Android manifest will help the Play store make your app available to the correct type of devices.
Apps that use a Map
(2D) require at least OpenGL ES 2.x:
<uses-feature android:glEsVersion="0x00020000" android:required="true" />
Apps that use a Scene
(3D) require OpenGL ES 3.x:
<uses-feature android:glEsVersion="0x00030000" android:required="true" />
Additional downloads
Additional sources of sample code and data are available to enhance your development projects. You can even download this guide as stand-alone developer documentation.
Sample code
Browse the comprehensive list of samples in the documentation or download sample code from the GitHub repository.
You can also download and interact with our live samples on your device using the sample viewer app from the Google Play Store.
ArcGIS Maps SDK for Kotlin Toolkit
The ArcGIS Maps SDK for Kotlin Toolkit contains Compose-enabled components (controls and utilities) to simplify your app development. To use the Map
and Scene
composable functions, include the following dependency in your module-level build.gradle.kts
:
- GeoView-Compose - Provides Composable implementations of the
Map
andView Scene
classes.View
The Toolkit contains other special-purpose components, which are also Compose-enabled.
- Authenticator - Displays a user interface when network and ArcGIS authentication challenges occur.
- Compass - Shows a compass direction when the map is rotated. Auto-hides when the map points north.
- FeatureForm - Enables users to edit field values of features in a layer using the
Feature
API that has been configured externally.Form - FloorFilter - Allows filtering of floor plan data in a geo view by a site, a building in the site, or a floor in the building.
Stand-alone developer documentation
You can download the developer documentation as an archive from the downloads page. The archive contains instructions to serve the documentation from a local web server so you can access it without a connection to the internet. The stand-alone documentation includes the developer guide, API reference, tutorials, and samples documentation. This documentation is designed to run on a local stand-alone computer or on an internal network and not on the public internet.
To serve the documentation locally:
- Download the documentation for the SDK you want to use. The downloaded files are in a .zip archive format.
- Extract the archive to a local folder. The extracted archive has two subfolders:
public
andinstall
. - Open the
README.md
file in theinstall
folder and follow the instructions for your chosen web server.
Supplemental data
StreetMap Premium
StreetMap Premium delivers a high-quality, multiscale cartographic map display with enriched street data. In addition, it provides accurate geocoding, optimized routing, easy to follow directions, and powerful network analysis. StreetMap Premium maps can simultaneously fulfill the need for an address locator, street network dataset, and basemap in your apps. They are consistent across all regions of the world and are available for both online, connected scenarios and for use in offline, disconnected scenarios in the form of mobile map packages.
If you want to use StreetMap Premium data (the StreetMap Premium extension), download the demonstration data from the downloads page for development and testing. Please contact Esri Customer Service for access to a region of your choice for development and testing or to license StreetMap Premium data for deployment.
Projection Engine data
Datum transformations are used when geometries must be projected from one spatial reference to another when there is a difference in the datum that underlies the two spatial references. Datum transformations can be mathematically defined (equation-based transformations), or may rely on external supporting files (grid-based transformations). Certain Projection Engine data files must be present when you use a grid-based transformation in your app; attempting to use a transformation with missing Projection Engine files will cause an error. The API can detect whether the necessary files are available on the local file system.
If your app requires grid-based transformations, you can download supporting Projection Engine files from the downloads page. See the Spatial references topic for more information about working with coordinate systems, projections, and datum transformations.
Electronic Navigational Charts (ENC)
Electronic navigational charts (ENCs) are georeferenced vector datasets for the visualization and analysis of hydrographic and maritime information. This SDK supports ENCs that conform to the International Hydrographic Organization (IHO) S-57 standard.
If you want to work with Electronic Navigational Charts (ENC) download the hydrography directory from the downloads page.
See the Display electronic navigational charts topic for more information about working with ENC data.