Core concepts

Overview

The Client Integration Library (CIL) follows a client-server architecture.

Key architectural components:

• NavAppClient: Your main entry point for all CIL functionality
• Managers: Specialized components for different features (TripManager, GuidanceManager, etc.)
• Callbacks: Asynchronous handlers for receiving responses and updates

All operations are asynchronous, ensuring your application remains responsive while the application processes navigation requests.

The CIL uses AIDL (Android Interface Definition Language) based IPC (Inter-Process Communication) internally to enable communication between the client application and the navigation server process.

API Version

API Version is an integer value that uniquely identifies the framework API revision offered by a version of the CIL. Each API in the CIL is marked with an API version denoting in which version this API was introduced. Note the API version does not denote the CIL release version, but only the implemented and supported APIs. If the version is unreleased the API is not yet frozen and may change in subsequent releases. See SdkBuild.Version.API_LEVEL for the current version of the client library.

1
@Since(ApiVersions.VERSION_10)
2
fun getMapManagementManager(): MapManagementManager

Minimum client API Version

The ANA server is backwards compatible with clients that implement an older API version. Before version 9, this compatibility extended to every previously released API version.

Starting with version 9 however, compatibility with certain older API versions has been dropped. The minimum supported API version of clients is now specified, and will increase every time a breaking change is made. Clients using an older API version, will be unable to connect.

See SdkBuild.Version.MINIMUM_CLIENT_API_LEVEL for the currently applicable minimum client api version of the client library.

Manager-based organization

CIL organizes functionality into specialized managers, each responsible for a specific domain of navigation features.

Available managers

Accessing managers

Each manager is accessed through the NavAppClient:

1
val tripManager = navAppClient.getTripManager()
2
val guidanceManager = navAppClient.getGuidanceManager()
3
val searchManager = navAppClient.getSearchManager()
4
val currentPositionManager = navAppClient.getCurrentPositionManager()
5
// etc.

Managers are lightweight objects that can be retrieved multiple times.

Callbacks, listeners and releasables

SdkReleasable

Every API call in the CIL returns an SdkReleasable object. This represents the active operation and provides lifecycle control. This allows a client to release resources associated with performed actions and/or to stop receiving updates through callbacks.

Callback types

CIL uses two main callback patterns depending on the operation type.

One-shot callbacks

Used for single operations that complete once, such as planning a trip or performing a search.

1
tripManager.planTrip(
2
    parameters = parameters,
3
    callback = object : TripPlanningCallback {
4
        override fun onTripPlanned(response: Result<TripPlanningResponse, TripPlanningFailure>) {
5
            // Handle trip planning result
6
        }
7

8
        override fun onFunctionalityUnavailable(reason: Callback.Reason) {
9
            // Handle unavailability
10
        }
11
    }
12
)

Listener callbacks

Used for continuous updates that occur multiple times, such as receiving navigation instructions or position changes.

1
guidanceManager.observeNextInstruction(
2
    object : NextInstructionListener {
3
        override fun onNextInstructionChange(instructionInfo: InstructionInfo) {
4
            // Receives updates as instructions change during navigation
5
        }
6

7
        override fun onFunctionalityUnavailable(reason: Callback.Reason) {
8
            // Handle unavailability
9
        }
10
    }
11
)