Skip to content

Android SDK Setup#

Prerequisites#

  • Minimum Android SDK version 24
  • The inbuilt map components use a Google map, so you'll need to set up an API key

Installation#

The Citymapper SDK must be downloaded directly from Citymapper servers via Maven.

In your root-level build.gradle (or settings.gradle) file, add the Citymapper SDK download servers as a source:

allprojects {
  repositories {
      google()
      mavenCentral()
      maven {
          url 'https://downloads.external.citymapper.com/sdk/android/releases/maven'
      }
  }
}
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven { 
          url 'https://downloads.external.citymapper.com/sdk/android/releases/maven' 
        }
    }
}

The SDK is made up of two modules and you can decide which one you want to include based on your needs

Add dependencies#

One of the following artifacts should be added into your module's build.gradle.

The citymapper-ui artifact contains complete drop-in UI components for displaying directions and turn-by-turn navigation

dependencies {
  implementation 'com.citymapper.sdk:citymapper-ui:2.2.1'
}

Alternatively, the citymapper-navigation artifact includes no UI components, and allows building a custom navigation experience on top of the Citymapper navigation engine

dependencies {
  implementation 'com.citymapper.sdk:citymapper-navigation:2.2.1'
}

Check build settings#

The SDK requires the -Xjvm-default kotlin compiler option, to make use of default methods in interfaces. Add these compiler arguments in your module's build.gradle.

android {
    //...
    kotlinOptions {
        jvmTarget = '1.8' // You probably already have this
        freeCompilerArgs += [
                '-Xjvm-default=all', // or all-compatibility
        ]
    }
}

Configuration#

Implement the CitymapperSdkConfguration.Provider interface somewhere in your codebase. This supplies the API Key and API URL information to the Citymapper SDK. This class must have a no-argument constructor:

import android.content.Context
import com.citymapper.sdk.configuration.CitymapperSdkConfiguration

class MyCitymapperSdkConfigProvider : CitymapperSdkConfiguration.Provider {

    override fun provideCitymapperSdkConfiguration(context: Context): CitymapperSdkConfiguration {
        return CitymapperSdkConfiguration(
            endpointUrl = "api.external.citymapper.com/api",
            apiKey = "<<Your API Key>>"
          )
    }
}

So that the SDK can discover your configuration provider, add a meta-data element within the <application> tag of your AndroidManifest.xml pointing to your configuration provider class, with the name com.citymapper.sdk.configuration_provider. If using the UI module, you must also add your Google Maps API key into the meta-data.

<application>
    <meta-data
        android:name="com.citymapper.sdk.configuration_provider"
        android:value="my.package.name.MyCitymapperSdkConfigProvider" />
    <meta-data
        android:name="com.google.android.geo.API_KEY"
        android:value="my-google-maps-api-key" />
</application>

Permissions#

For the navigation functionality to work, you'll need to enable the fine location permission in your manifest file

<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />