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:

build.gradle

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

settings.gradle

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:3.0.0-beta01'
}

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:3.0.0-beta01'
}

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" />