Skip to content

Android Integration Guide for EH SDK

Overview

The EH SDK for Android enables your application to seamlessly access and interact with EH services, such as real-time data delivery and messaging capabilities. This guide walks you through the process of integrating the SDK into your Android project. It encompasses the following steps:

  • Setting up your development environment
  • Adding necessary dependencies
  • Initializing the SDK
  • Implementing core features like EH data service and message service

System Requirements

To ensure your app runs smoothly, make sure it is compatible with the following device specifications:

  • Supported Architectures: ARM or x86_64
  • Minimum Android Version: Android 6.0 (API level 23)

Add SDK Dependencies

To start using the EH SDK in your Android app, add the required dependencies by following these steps:

  1. Open your Android Studio project.
  2. Add the repositories and dependencies to your build.gradle file.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
repositories {
    // aliyun maven repo
    maven {
        url 'https://maven.aliyun.com/repository/public'
    }

    maven {
        url 'https://packages.aliyun.com/maven/###'
        credentials {
            username '#REPO_USER_NAME#'
            password '#REPO_PASSWD#'
        }
    }
}

dependencies {
    implementation("com.telenav.sdk:telenav-android-ehservice-r15c:${sdkVersion}")
    implementation("com.telenav.sdk:telenav-android-ngx-r15c:${ngxVersion}")
}

The repositories block ensures that your project is connected to the correct artifact repositories.

Initialize the SDK

This step is mandatory.

Before you can start using any of the services, you must initialize an SDK instance with your API credentials and other configuration settings.

Regardless of how many different services are used, the SDK instance should only be initialized once.

1
2
3
4
5
6
7
8
9
val sdkOptions = SDKOptions.builder()
    .setApiKey("#YOUR_API_KEY")
    .setApiSecret("#YOUR_API_SECRET")
    .setCloudEndPoint("#END_POINT")
    .setRegion("#Region")
    .setSdkDataDir("#ONBOARD_MAP_DATA_PATH")
    .build()

SDK.getInstance().initialize(getApplication(), NavSDKOptions.builder(sdkOptions).build())

EH Data Service

The EH Data Service provides core EH data functionalities, such as path and intersection information along the Most Probable Path (MPP). To initialize the EH Data Service:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
// Create EH data service
val ehDataService = EHService.Factory.createEHDataService(
    EHServiceOption.Builder()
        .setMainPathLength(4000)    // Set the main path length
        .setSubPathLevel(0)   // Set the sub path level, 0 means no sub path will be generated
        .setIntersectionDetectDistance(1000)    // Set the intersection detection distance
        .enableLog(true)  // Enable or disable the log
        .setLogStorePath("#The path to store log")
        .build()
)

ehDataService.addEHDataListener(object : EHDataListener {
    override fun onDataUpdated(dataList: List<EHData>) {
        // Handle information of MPP or sub path
    }

})

EH Message Service

EH Message Service is used to receive messages as per ADASIS 2.0.4 specification, as well as location feedback. Here’s how you initialize it:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
// Create EH message service
val ehMessageService = EHService.Factory.createEHMessageService(
    EHServiceOption.Builder()
        .setMainPathLength(4000)    // Set the main path length
        .setSubPathLevel(0)   // Set the sub path level, 0 means no sub path will be generated
        .enableLog(true)  // Enable or disable the log
        .setLogStorePath("#The path to store log")
        .build()
)

ehMessageService.addEHMessageListener(object : EHMessageListener {
    override fun onMessageUpdated(message: List<EHMessage>) {
        // Handle ADAS messages
    }

})

ehMessageService.addEHLocationListener(object : EHLocationListener{
    override fun onLocationFeedback(feedback: EHLocationFeedback) {
        // Handle map matching feedback
    }
})

Use Customized Location Provider to Update Location

By default, the EH SDK is integrated with the built-in Android location provider and can automatically receive location updates of the device/vehicle. Optionally, if you need to use your own customized location provider, you can inject it through the injectLocationProvider API of SDK.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
val locationProvider = object : LocationProvider("Demo") {
    override fun onStart() {
        // This method will be called when location provider is been used
    }

    override fun onStop() {
        // This method will be called when location provider is no longer needed
    }

    fun setLocation(location: Location) {
        this.updateLocation(location)
    }
}
// inject a location provider for test
SDK.getInstance().injectLocationProvider(locationProvider)
The LocationProvider is a custom class used to update the location in the EH SDK.

1
2
// Update the location
locationProvider.setLocation(location)

Enable AFFILIATE Mode

If you want the MPP (Most Probable Path) to be influenced by the Navigation guidance route, you can use the AFFILIATE mode. To enable the AFFILIATE mode (which can be used for specific service behaviors), use the following configuration:

1
2
3
4
5
6
val navigationService = NavigationService.Factory.createInstance()
val ehService = EHService.Factory.createEHDataService(
    EHServiceOption.Builder().setServiceMode(EHServiceMode.AFFILIATE).build()
)

navigationService.addExtension(ehService)

For detailed integration with the NavigationService, please refer to the Navigation Integration guideline.

Dispose of SDK Resources

Finally, don't forget to dispose of the SDK resources when your app is being destroyed:

1
2
3
ehMessageService.dispose()
ehDataService.dispose()
SDK.getInstance().dispose()
This step ensures that all SDK resources are cleaned up properly to avoid memory leaks or unnecessary resource consumption.