ArcGIS Maps SDK for Kotlin offers a toolkit, ArcGIS Maps SDK for Kotlin Toolkit, that contains composable UI components to help simplify your Android development work. For information on how Android Jetpack Compose works, see Get started with Jetpack Compose.
The Geo
module has composable components to display maps and scenes. Most apps that use Android Jetpack Compose will need this module.
- GeoView-Compose - Contains the composable components
MapView
andSceneView
, which are wrappers for theMapView
andSceneView
classes in the Kotlin Maps SDK API.
The Toolkit contains other, special-purpose composable components:
- Augmented Reality - FlyoverSceneView - Allows you to explore a scene using your device as a window into the virtual world.
- Augmented Reality - TableTopSceneView - Allows you to anchor scene content to a physical surface, as if it were a 3D-printed model.
- Augmented Reality - WorldScaleSceneView - Allows you to integrate scene content with the real world features like streets and buildings.
- Authenticator - Displays a user interface when network and ArcGIS authentication challenges occur.
- BasemapGallery - Provides a control for selecting basemaps.
- 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 a feature using pre-configured forms.
- FloorFilter - Allows filtering of floor plan data in a GeoView by a site, a facility in the site, or a floor in the facility.
- GeoView-Compose Callout - Draws a callout on the GeoView to display Composable content.
- GeoView-Compose OverviewMap - Displays the visible extent of a GeoView in a small "inset" map.
- Legend - Displays a legend for a map or a scene.
- OfflineMapAreas - Allows you to take a web map offline by downloading map areas.
- Popup - View field values of features in a layer using the Popup API.
- Scalebar - Displays current scale reference.
- UtilityNetworkTrace - Configure, run, and visualize UtilityNetworkTraces on a composable MapView.
The fastest way to get the toolkit into your app is to reference the compiled library (.aar file) from Jfrog, as described below. For instructions on using the toolkit from source code — for example, if you want to customize it — see Developer setup in the toolkit's repo.
Enhancements in 200.8.0
Authenticator
The Authenticator
toolkit component now supports Identity-Aware Proxy (IAP) Sign-in and Sign-out. This works out of the box when there's an Iap
set on the Authenticator
property. As part of adding support for IAP several updates were made to the Toolkit Authenticator
which include deprecations and new recommendations:
-
Deprecated: The
Authenticator
composable that uses theon
lambda.Pending O Auth User Sign In - Recommended: Use the updated
Authenticator
composable that accepts aon
lambda.Pending Browser Authentication Challenge : ( Browser Authentication Challenge) - > Unit Browser
is a wrapper around sign-in/out objects such asAuthentication Challenge Iap
,Sign In O
, andAuth User Sign In Iap
. This new parameter is similar to the previous lambda and should be used when launching and receiving IAP/OAuth flows from your ownSign Out Activity
.
- Recommended: Use the updated
-
Deprecated:
O
in the AndroidManifest, previously used to handle OAuth redirect URIs.Auth User Sign In Activity - Recommended: Replace it with
Authentication
, which provides the same functionality and also supports IAP sign-in/sign-out completion.Activity
- Recommended: Replace it with
-
Deprecated:
Activity.launch
&Custom Tabs(pending Sign In : O Auth User Sign In?) Authenticator
State.complete O Auth Sign In(intent) - Recommended:
Activity.launch
Custom Tabs(pending Browser Authentication Challenge) Authenticator
State.complete Browser Authentication Challenge(intent) - These updated methods support both OAuth and IAP sign-in/sign-out flows.
- Recommended:
-
Deprecated:
Authentication
as it does not support IAP sign-out.Manager.sign Out() - Recommended: Use
Authenticator
. IfState.sign Out() Iap
are present in the credential cache, this will launch a browser page to invalidate the IAP sessionCredentials
- Recommended: Use
-
The
Authenticator
now supports managing multipleState O
instances through the newAuth User Configuration Authenticator
property. This enhancement allows developers to configure multiple OAuth setups more flexibly.State. O Auth User Configurations
See the Authenticator toolkit component for more details.
Augmented Reality - FlyoverSceneView
The Flyover
component uses augmented reality to render a scene that is navigated by moving the device, providing a more natural navigation experience than a mouse or touch interface. Flyover
can be customized to render any location with a variable translation
to control the degree to which device movement affects the movement of the scene camera. See the FlyoverSceneView toolkit component for more details.
Augmented Reality - WorldScaleSceneView
World
may now enter aScale Scene View Failed
status inTo Initialize World
if the component is unable to access the device sensor data.Scale Tracking Mode. World World
will now receive a validScale Scene View map
in thePoint Single
supplied by theTap Confirmed Event on
callback. ThisSingle Tap Confirmed map
is calculated using the ARCore Depth API. If the Depth API is not supported on a device, it will test against any horizontal or vertical planes detected at the tapped screen coordinate. If no planes are detected, thePoint map
will be null.Point - When the
World
is running inScale Scene View Geospatial
mode, ARCore uses Google VPS when available. User can now make use of two versions of thecheck
function (with and without location parameters) available onVps Availability() World
to query VPS availability.Scale Scene View Proxy World
now has anScale Scene View on
parameter which can be used to track transient errors after theTracking Error Changed World
has been initialized.Scale Scene View
See the WorldScaleSceneView toolkit component for more details.
Basemap Gallery
The Basemap
toolkit component has been enhanced to allow basemaps that come from a portal item to be marked as 3D basemaps. If the new property Basemap
is set true
, a "3D" badge is displayed on top of the basemap's thumbnail in the gallery. See the BasemapGallery toolkit component for more details.
Feature Forms
New Features:
- Utility Network Associations Support:
- Added support for
Utility
s in theAssociations Form Element Feature
. This allows users to view a list ofForm Utility
s, navigate to associated features, and edit them.Association - Introduced a new
Feature
class to support navigation for associations inForm State Utility
and associated features. A new overload acceptingAssociations Form Element Feature
as a parameter has been added.Form State - Navigation to other features while viewing
Utility
s can be disabled using theAssociation is
parameter, which defaults toNavigation Enabled : Boolean true
.
- Added support for
- Close Icon:
- A close icon is now displayed in the form UI. The
on
parameter allows handling the tap action, and the icon can be hidden by settingDismiss show
toClose Icon : Boolean false
.
- A close icon is now displayed in the form UI. The
- Action Bar for Edits:
- When edits are present in the
Feature
, an action bar is displayed at the top of the form with “Save” and “Discard” buttons. This can be hidden by settingForm show
toForm Actions : Boolean false
. A newon
callback of typeEditing Event Feature
is introduced to listen for save and discard actions.Form Editing Event
- When edits are present in the
- Attachments UI has been redesigned with a modern look. New styling options are introduced with
Attachments
andElement Colors.tile Container Color Attachments
.Element Typography.tile Supporting Text Style - The toolkit now supports downloading large attachments up to 999MB, while uploading remains limited to 50MB.
Deprecations:
- Deprecated the
Feature
composable introduced in version 200.4.0. This overload does not displayForm(feature Form : Feature Form, ..) Utility
. Use the overload that acceptsAssociations Form Elements Feature
instead.Form State - Deprecated
Attachments
andElement Colors.outline Color tile
as the element is no longer outlined.Border Color
See the FeatureForm toolkit component for more details.
OfflineMapAreas
The Offline
composable allows users to take web maps offline. Users can download map areas created ahead-of-time by the web map author, or they can create map areas on-demand by specifying an area of interest and level of detail. Map areas are downloaded to the app's Documents directory and can be used even when the app is completely offline. Users can get information about a map area such as its size and the geographic region it covers. They can also delete a downloaded map area to free up storage space on the device. See the OfflineMapAreas toolkit component for more details.
OverviewMap
The Overview
in the geoview-compose
module is a small, secondary Map
that can be superimposed on a Map
or Scene
. Its purpose is to show the current viewpoint of the map or scene in a wider context. The Overview
can use a customized Symbol
to display the visible area or viewpoint center for the larger Map
or Scene
. See the OverviewMap toolkit component for more details.
Modular toolkit library
The toolkit has library modules that can be deployed independent of each other in an application. Note that an individual library module can contain one or more composable UI components.
Reference the library from Jfrog
-
If you haven't already, install and set up ArcGIS Maps SDK for Kotlin.
-
Ensure the Esri public Jfrog Maven repository is in your project's gradle file,
https
://esri.jfrog.io/artifactory/arcgis settings.gradle.kts (Project Settings)Use dark colors for code blocks dependencyResolutionManagement { repositories { ... maven { url = uri("https://esri.jfrog.io/artifactory/arcgis") } ... } }
-
From the Android view, open Gradle Scripts > build.gradle.kts (Module: app) and add a dependency for each component of the ArcGIS Maps SDK for Kotlin Toolkit that you will be using.
From the Project tool window, open Gradle Scripts > libs.versions.toml. In the
[versions]
section, verify you're using the correct version number for ArcGIS Maps SDK for Kotlin. And in the[libraries]
section, add the library declarations for the following:- the ArcGIS Maps SDK for Kotlin SDK.
- the ArcGIS Maps SDK for Kotlin Toolkit BOM.
- any Toolkit components needed. For example, to display a simple map or scene, you need only the
geoview-compose
component, which contains the composable functionsMapView
andSceneView
.
Gradle version catalogs are the standard Android approach to declaring dependency versions. They are preferred over specifying versions numbers in the
build.gradle.kts
or listing version numbers in aversion.gradle
. In recent releases of Android Studio, the New Project Wizard generatesbuild.gradle.kts
andgradle/libs.versions.toml
files that support this standard.Gradle version catalogs can also use BOM files to specify a single version number for all artifacts in the BOM. For more details, see
Using the BOM
in theREADME
of the ArcGIS Maps SDK for Kotlin Toolkit.Use dark colors for code blocks Copy // 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) implementation(libs.arcgis.maps.kotlin.toolkit.authentication)
The highlights above indicate lines that we are adding to the default build.gradle.kts (
and gradle/libs.versions.toml
generated by the Android Studio New Project Wizard.
The first time you build a project, the Gradle build script will automatically download the ArcGIS Maps SDK for Kotlin and its resources to your development machine. Your Android Studio project will then access the Kotlin Maps SDK with no further action on your part.
Build from source
Although not required to do so, you can build the Toolkit components and micro-apps from the source code in the Toolkit repo. See the setup instructions for details.
Requirements
The following table shows version compatibility.
SDK Version | Toolkit Version |
---|---|
200.0.0 | none |
200.1.0 | none |
200.2.0 | 200.2.0 |
200.3.0 | 200.3.0 |
200.4.0 | 200.4.0 |
200.5.0 | 200.5.0 |
200.6.0 | 200.6.0 |
200.7.0 | 200.7.0 |
200.8.0 | 200.8.0 |
Issues
Find a bug or want to request a new feature enhancement? Please let us know by submitting an issue.