Skip to main content
Version: 6.0

Getting Started

Using Mappedin SDK for Android with your own map requires a Pro license. Try a demo map for free or refer to the Pricing page for more information.

Mappedin SDK for Android helps to deliver the rich indoor mapping experience of a venue, inside Android apps.

The Mappedin SDK for Android is a native interface to Mappedin JS. The SDK is a dependency built using Kotlin, and it automatically handles any authentication, network communication, fetching of map data, its display, and basic user interaction, such as panning, tapping, and zooming. The SDK allows a developer to build their own interactions. Additional layers can be rendered on top of the map.

info

Mappedin SDK for Android is supported on Android versions 8.0 and above.

Coding with AI​

Mappedin SDK for Android provides an llms-mappedin-android.txt file that can be used to help with coding when using Large Language Models (LLMs).

Expand for instructions on how to use Mappedin provided llms.txt files with Cursor, Github Copilot, JetBrains AI Assistant and Windsurf.

How to use llms.txt files with LLMs:

To use the llms.txt file with Cursor:

  1. Download the llms.txt file for this guide.
  2. Create a .cursor directory in your project root if it doesn't exist already.
  3. Place the llms.txt file in the .cursor directory.
  4. Start creating a new Cursor rule using Cursor's instructions.
  5. Set the rule type to: Apply Intelligently.
  6. Set the agent description to: Use this rule whenever a question is asked about Mappedin, Mappedin-JS, Mappedin SDK..
  7. In the rule body, add the the llms.txt file as an mdc reference: [llms-mappedin-js.txt](mdc:.cursor/llms-mappedin-js.txt)
  8. Optionally, if using Mappedin JS add an mde reference to the Mappedin JS TypeScript definitions: [@mappedin/mappedin-js TypeScript definitions](mdc:node_modules/@mappedin/mappedin-js/lib/esm/index.d.ts)
  9. The full rull text should look like this:
    ---
description: Use this rule whenever a question is asked about Mappedin, Mappedin-JS, Mappedin SDK.
alwaysApply: false
---

[llms-mappedin-js.txt](mdc:.cursor/llms-mappedin-js.txt)

[@mappedin/mappedin-js TypeScript definitions](mdc:node_modules/@mappedin/mappedin-js/lib/esm/index.d.ts)
  10. With this configuration, Cursor will automatically use the llms.txt whenever a question is asked about Mappedin, Mappedin-JS or Mappedin SDKs. When starting a new chat be sure to mention Mappedin to trigger the rule.
  11. The llms.txt file includes:
    • Detailed explanations of concepts
    • Code examples and their context
    • Related documentation references
    • Source file locations for verification

This helps ensure that Cursor provides assistance that is consistent with Mappedin documentation and best practices, using the same structured information that's available on the Mappedin Developer Portal.

Android Studio Project Setup​

Add Permissions​

Add the following permissions to the AndroidManifest.xml in the application tag.

<uses-permission android:name="android.permission.INTERNET" />
<!--Permissions below are only needed if displaying user location-->
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT"/>

Ensure that hardware acceleration is not turned off by setting it to true.

<application
    android:hardwareAccelerated="true"
/>

Ensure that the application has a large heap by setting it to true.

<application
    android:largeHeap="true"
/>

Add Application Dependency to Gradle​

Add the Mappedin SDK dependency to the application's build.gradle, settings.gradle or libs.versions.toml and sync the changes to download the SDK. The latest version can be found in in Maven Central.

build.gradle or settings.gradle​

implementation 'com.mappedin.sdk:mappedin:6.0.0-alpha.1'

libs.versions.toml​

[versions]
mappedin = "6.0.0-alpha.1"

[libraries]
mappedin = { module = "com.mappedin.sdk:mappedin", version.ref = "mappedin" }
tip

The Mappedin Android Github repository contains a reference project that demonstrates how to use the Mappedin SDK for Android.

Display a Map​

The core class of the Mappedin SDK for Android is MapView, which is responsible for instantiating an Android WebView that loads Mappedin JS. MapView is the core class of which all other views and data models can be accessed.

Load Map Data​

Call MapView.getMapData to load map data from Mappedin servers. This function must be called first and map data must be loaded before any other Mappedin functions can be called.

// See Trial API key Terms and Conditions
// https://developer.mappedin.com/docs/demo-keys-and-maps
val options =
    GetMapDataWithCredentialsOptions(
        key = "mik_yeBk0Vf0nNJtpesfu560e07e5",
        secret = "mis_2g9ST8ZcSFb5R9fPnsvYhrX3RyRwPtDGbMGweCYKEq385431022",
        mapId = "64ef49e662fd90fe020bee61",
    )

// Load the map data.
mapView.getMapData(options) { result ->
    result.onSuccess {
        Log.d("MappedinDemo", "getMapData success")
    }
}

Show a Map​

Call MapView.show3dMap to display the map.

mapView.show3dMap(Show3DMapOptions()) { result ->
    result.onSuccess {
        Log.d("MappedinDemo", "show3dMap success")
    }
}

The following sample code combines the loading of map data and the display of the map and includes a function to be called when the map is ready.

// See Trial API key Terms and Conditions
// https://developer.mappedin.com/docs/demo-keys-and-maps
val options =
    GetMapDataWithCredentialsOptions(
        key = "mik_yeBk0Vf0nNJtpesfu560e07e5",
        secret = "mis_2g9ST8ZcSFb5R9fPnsvYhrX3RyRwPtDGbMGweCYKEq385431022",
        mapId = "64ef49e662fd90fe020bee61",
    )

// Load the map data.
mapView.getMapData(options) { result ->
    result
        .onSuccess {
            Log.d("MappedinDemo", "getMapData success")
        // Display the map.
        mapView.show3dMap(Show3DMapOptions()) { r ->
            r.onSuccess {
                runOnUiThread {
                    loadingIndicator.visibility = android.view.View.GONE
                }
                onMapReady(mapView)
            }
            r.onFailure {
                runOnUiThread {
                    loadingIndicator.visibility = android.view.View.GONE
                }
                Log.e("MappedinDemo", "show3dMap error: $it")
            }
        }
        }.onFailure {
            Log.e("MappedinDemo", "getMapData error: $it")
        }
}

// Place your code to be called when the map is ready here.
private fun onMapReady(mapView: MapView) {
  Log.d("MappedinDemo", "show3dMap success - Map displayed")
}

Result​

The app should display something that looks like this in the Android Emulator:

Map displayed using Mappedin SDK for Android v6

And zooming in to have a closer look:

Map zoomed using Mappedin SDK for Android v6

Debug Mode​

Use Debug Mode to get a closer look at how various map components behave and interact. Here's how to enable it:

1. Enable Debug Mode​

To activate the debug interface, call the following function in your code:

mapView.enableDebug()

MapView.enableDebug displays a panel on the right side of the map, revealing several tools and controls for direct interaction with the map's elements.

2. Navigating the Debug Panel​

The debug panel provides access to a variety of controls:

Geometry Controls

  • Adjust individual geometry settings, such as color, opacity, visibility. These controls make it easy to see how different elements respond to changes.

Interactivity

  • Use toggles to turn interactivity on/off
  • Change colors and hover effects to highlight specific areas

Scene Controls

  • Manage the overall scene settings, such as scaling, positioning, and group management. Toggle the visibility of groups or containers within the scene
  • Adjust padding, scale, and watermark positioning
  • Markers & Labels — Add, remove, or edit markers and labels directly through the panel

Camera Controls

  • Fine-tune camera settings, including zoom levels, pitch, and center position
  • Set minimum and maximum zoom levels
  • Adjust the focus to a specific area or level

enable debug