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
MapViewandSceneView, which are wrappers for theMapViewandSceneViewclasses 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
Authenticatorcomposable that uses theonlambda.Pending O Auth User Sign In - Recommended: Use the updated
Authenticatorcomposable that accepts aonlambda.Pending Browser Authentication Challenge : ( Browser Authentication Challenge) - > Unit Browseris 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:
Oin 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?) AuthenticatorState.complete O Auth Sign In(intent) - Recommended:
Activity.launchCustom Tabs(pending Browser Authentication Challenge) AuthenticatorState.complete Browser Authentication Challenge(intent) - These updated methods support both OAuth and IAP sign-in/sign-out flows.
- Recommended:
-
Deprecated:
Authenticationas it does not support IAP sign-out.Manager.sign Out() - Recommended: Use
Authenticator. IfState.sign Out() Iapare present in the credential cache, this will launch a browser page to invalidate the IAP sessionCredentials
- Recommended: Use
-
The
Authenticatornow supports managing multipleState Oinstances through the newAuth User Configuration Authenticatorproperty. 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
Worldmay now enter aScale Scene View Failedstatus inTo Initialize Worldif the component is unable to access the device sensor data.Scale Tracking Mode. World Worldwill now receive a validScale Scene View mapin thePoint Singlesupplied by theTap Confirmed Event oncallback. ThisSingle Tap Confirmed mapis 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 mapwill be null.Point - When the
Worldis running inScale Scene View Geospatialmode, ARCore uses Google VPS when available. User can now make use of two versions of thecheckfunction (with and without location parameters) available onVps Availability() Worldto query VPS availability.Scale Scene View Proxy Worldnow has anScale Scene View onparameter which can be used to track transient errors after theTracking Error Changed Worldhas 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
Utilitys in theAssociations Form Element Feature. This allows users to view a list ofForm Utilitys, navigate to associated features, and edit them.Association - Introduced a new
Featureclass to support navigation for associations inForm State Utilityand associated features. A new overload acceptingAssociations Form Element Featureas a parameter has been added.Form State - Navigation to other features while viewing
Utilitys can be disabled using theAssociation isparameter, which defaults toNavigation Enabled : Boolean true.
- Added support for
- Close Icon:
- A close icon is now displayed in the form UI. The
onparameter allows handling the tap action, and the icon can be hidden by settingDismiss showtoClose 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 showtoForm Actions : Boolean false. A newoncallback of typeEditing Event Featureis 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
AttachmentsandElement 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
Featurecomposable introduced in version 200.4.0. This overload does not displayForm(feature Form : Feature Form, ..) Utility. Use the overload that acceptsAssociations Form Elements Featureinstead.Form State - Deprecated
AttachmentsandElement Colors.outline Color tileas 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-composecomponent, which contains the composable functionsMapViewandSceneView.
Gradle version catalogs are the standard Android approach to declaring dependency versions. They are preferred over specifying versions numbers in the
build.gradle.ktsor listing version numbers in aversion.gradle. In recent releases of Android Studio, the New Project Wizard generatesbuild.gradle.ktsandgradle/libs.versions.tomlfiles 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 BOMin theREADMEof 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.