Getting started

Introduction

This document explains how an integrator can use the Client Integration Library (CIL) to interface and control the Automotive Navigation Application (ANA). It covers setting up the library and using the library.

Project setup

• Install Android Studio if you don’t already have it.
• To set up CIL, you first need an existing Android project.
  • If you don’t have one, follow this guide to create a new Android project .
• Ensure that the minimum SDK API level is set to 31 (Android 12 “S”) or higher.
• Ensure that the minimum Kotlin version used is 1.9.25 or higher.

Configuring project dependencies

Step 1. Add the Artifactory repository URL to the repositories block (settings.gradle.kts):

1
dependencyResolutionManagement {
2
    repositories {
3
        google()
4
        mavenCentral()
5
        maven {
6
            url = uri("https://repositories.tomtom.com/artifactory/automotive-maven-release")
7
            credentials {
8
                username = "your-username" // Replace with your Artifactory username
9
                password = "your-password" // Replace with your Artifactory password
10
            }
11
        }
12
    }
13
}

Step 2. Update your app-level Gradle file (for example, app/build.gradle.kts) to include the maven package as a dependency.

1
dependencies {
2
    implementation("com.tomtom.automotive:client-integration-library:0.8.0")
3
    ...
4
}

Using CIL

Instantiating the NavAppClient

To use the Client Integration Library, you need to create an instance of NavAppClient, using the NavAppClientFactory().create(Context, ErrorCallback) method. The returned instance is used to access the individual APIs. As instantiating the NavAppClient requires some background initialization, it’s best to create the NavAppClient once per application, e.g. in the Activity onCreate callback. Once this call returns, the NavAppClient instance is ready to use.

Multiple applications can connect to the CIL simultaneously, each with their own NavAppClient instance.

1
override fun onCreate() {
2
    super.onCreate()
3

4
    // Instantiate the NavAppClient passing in a Context and an ErrorCallback.
5
    navAppClient = NavAppClientFactory().create(this, object : ErrorCallback {
6
        override fun onError(error: NavAppError) {
7
            // Handle error
8
        }
9
    })
10
}

And closed in the Activity onDestroy callback, using NavAppClient close() method.

1
override fun onDestroy() {
2
    // Clean up when activity is destroyed
3
    navAppClient.close()
4

5
    super.onDestroy()
6
}

In case the NavAppClient instance is used in some other components (eg. ViewModels, Singleton, etc.), make sure the close() method is called at some point when it doesn’t need to be used anymore, to prevent leaking the service connection.

Accessing the APIs

After creation, the NavAppClient instance can be used to access the APIs. Note that all callbacks from the SDK are done on the UI Thread.

Example of planning a trip:

1
val currentPositionManager = navAppClient.getCurrentPositionManager()
2
val observePositionReleasable = currentPositionManager.observeCurrentPosition(object : CurrentPositionListener {
3
    override fun onCurrentPosition(info: CurrentPositionInfo) {
4
        // Handle current position update
5
    }
6
    override fun onFunctionalityUnavailable(reason: Callback.Reason) {
7
        // Handle functionality unavailable
8
    }
9
})