Quickstart

The Kotlin types are MapLibre*, not MapMetrics*

The MapMetrics Android SDK is a MapLibre distribution: the artifact is org.mapmetrics.android-sdk:mapmetrics-native-sdk, but the classes inside it keep their upstream org.maplibre.android.* package and their upstream names. There is no MapMetricsMap class — the AAR contains no type whose name starts with MapMetrics at all.

Wrong	Correct
MapMetricsMap	org.maplibre.android.maps.MapLibreMap
MapMetricsMapOptions	org.maplibre.android.maps.MapLibreMapOptions
R.drawable.mapmetrics_*	R.drawable.maplibre_*

import org.maplibre.android.maps.MapMetricsMap will not compile — the package is real, the class is not. Earlier revisions of these guides used the MapMetrics* spelling throughout (and in places contradicted themselves within one file); every page has been corrected. "MapMetrics" remains correct for the product, the portal, the API key and the Maven artifact — just not for Kotlin type names.

To follow this example from scratch, in Android Studio create a new "Empty Views Activity" and then select "Kotlin" as the language. Select "Groovy DSL" as the build configuration language.

1. If you have an older project, you'll need to add Maven Central to your project-level Gradle file (usually <project>/<app-module>/build.gradle). Add mavenCentral() to where repositories are already defined in that file, something like this:

   allprojects {
       repositories {
       ...
       mavenCentral()
       }
   }

   A newly-created app will likely already have mavenCentral() in a top-level settings.gradle file, and you won't need to add it.

2. Add the library as a dependency into your module Gradle file (usually <project>/<app-module>/build.gradle). The current release is 1.0.3 — see all released versions:

   dependencies {
       ...
       implementation 'org.mapmetrics.android-sdk:mapmetrics-native-sdk:1.0.3'
   
   }

3. Sync your Android project with Gradle files.

4. Add a MapView to your layout XML file (usually <project>/<app-module>/src/main/res/layout/activity_main.xml).

   ...
   <org.maplibre.android.maps.MapView
       android:id="@+id/mapView"
       android:layout_width="match_parent"
       android:layout_height="match_parent"
       />
   ...

5. Initialize the MapView in your MainActivity file by following the example below. If modifying a newly-created "Empty Views Activity" example, it replaces all the Kotlin code after the "package" line.

   
   class SimpleMapActivity : AppCompatActivity() {
   
       // Declare a variable for MapView
       private lateinit var mapView: MapView
   
       private lateinit var mapView: MapView
   override fun onCreate(savedInstanceState: Bundle?) {
       super.onCreate(savedInstanceState)
       onBackPressedDispatcher.addCallback(this, object: OnBackPressedCallback(true) {
           override fun handleOnBackPressed() {
               // activity uses singleInstance for testing purposes
               // code below provides a default navigation when using the app
               NavUtils.navigateHome(this@SimpleMapActivity)
           }
       })
       setContentView(R.layout.activity_map_simple)
       mapView = findViewById(R.id.mapView)
       mapView.onCreate(savedInstanceState)
       mapView.getMapAsync {
           val key = ApiKeyUtils.getApiKey(applicationContext)
           if (key == null || key == "YOUR_API_KEY_GOES_HERE") {
               it.setStyle(
                   Style.Builder().fromUri(fileName)
               )
           } else {
               val styles = Style.getPredefinedStyles()
               if (styles.isNotEmpty()) {
                   val styleUrl = styles[0].url
                   it.setStyle(Style.Builder().fromUri(styleUrl))
               }
           }
       }
   }
       override fun onStart() {
           super.onStart()
           mapView.onStart()
       }
   
       override fun onResume() {
           super.onResume()
           mapView.onResume()
       }
   
       override fun onPause() {
           super.onPause()
           mapView.onPause()
       }
   
       override fun onStop() {
           super.onStop()
           mapView.onStop()
       }
   
       override fun onLowMemory() {
           super.onLowMemory()
           mapView.onLowMemory()
       }
   
       override fun onDestroy() {
           super.onDestroy()
           mapView.onDestroy()
       }
   
       override fun onSaveInstanceState(outState: Bundle) {
           super.onSaveInstanceState(outState)
           mapView.onSaveInstanceState(outState)
       }
   }

6. Build and run the app. If you run the app successfully, a map will be displayed.