Integrate the SDK

_|

This guide describes the steps to install the most recent version of the Maps SDK for Android and configure your Android app to use the SDK.

Prerequisites

Download and install Android Studio from the official Android Developer website.

Note

The procedures described in this document are valid for Android Studio Narwhal | 2025.1.1.

Add the dependency

Magic Lane provides the Maps SDK for Android via Maven.

Add the code below to settings.gradle.kts declare the endpoint in the repositories block:

...
val GEM_SDK_REGISTRY_TOKEN: String? by settings
...

val gemSdkRegistryToken = GEM_SDK_REGISTRY_TOKEN
    ?: System.getenv("GEM_SDK_REGISTRY_TOKEN").takeIf { !it.isNullOrBlank() }
repositories {
    google()
    mavenCentral()
    maven {
        url = uri("https://issuetracker.magiclane.com/api/v4/packages/maven")
        credentials(HttpHeaderCredentials::class) {
            name = "Private-Token"
            value = gemSdkRegistryToken
        }
        authentication {
            create<HttpHeaderAuthentication>("header")
        }
    }
}

A personal access token (gemSdkRegistryToken) needs to be generated at (Generate Personal Access Token](https://issuetracker.magiclane.com/-/user_settings/personal_access_tokens) in order to access Maven repository with read_api and read_repository scope. The generated token should be saved in ~/.gradle/gradle.properties with the following content:

GEM_SDK_REGISTRY_TOKEN=<your_personal_access_token>

In your module-level build.gradle.kts file, add:

dependencies {
    implementation("com.magiclane:maps-kotlin:<X.Y.Z>")
}

note

Optionally you can Download the Maps SDK for Android .aar file then copy it to the myproject/app/libs/ directory. If you choose to use a local .aar file you must also comment or delete the MagicLane Maven repository from your module build.gradle.kts file.

Build and run a sample app

Example applications for the Maps SDK for Android are available on IssueTracker. You can clone the repository and launch the applications by following the setup instructions provided in the README file.

If you don't already have an API key, you can Create an API key. This is not mandatory but highly recommended in order to be able to use all the functionalities of the SDK.

Load the example application in Android Studio and open the AndroidManifest.xml file of an example and replace ${GEM_TOKEN} with your actual Magic Lane API key.

Select desired Active Build Variant (debug/release) in Build Variants menu and deploy to device as usual.