Developer

Vehicle integration basics

Request Access
Version: 0.5.0

介绍

本文档说明了集成者如何使用 Vehicle Integration Library (VIL) 将 Automotive Navigation Application (ANA) 与车辆集成。内容涵盖了库的设置、使用及集成测试。

注意：
本文档重点介绍在新的 Android 应用中使用 VIL。
也可以在 Android Automotive OS 的更深层次实现 VIL 客户端。

项目设置

  • 如果尚未安装，请安装 Android Studio。
  • 要设置 VIL，您首先需要一个现有的 Android 项目。
  • 确保最低 SDK API 级别设置为 27（Android 8.1 "Oreo"） 或更高。
  • 确保使用的最低 kotlin 版本为 1.9.25 或更高。

配置项目依赖

步骤 1. 将 Artifactory 仓库 URL 添加到 repositories 块（settings.gradle.kts）：

1dependencyResolutionManagement {
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" // 替换为您的 Artifactory 用户名
9                password = "your-password" // 替换为您的 Artifactory 密码
10            }
11        }
12    }
13}

步骤 2. 更新您的应用级 Gradle 文件（例如 app/build.gradle.kts），将 maven 包作为依赖添加：

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

使用 VIL

实例化 Vehicle Integration API 客户端

通常在应用初始化时实例化 VIL，此时 Android Context 可用，例如在主应用类的 onCreate 方法中：

步骤 1. 如果您还没有应用类，请创建一个（例如 MyVilApplication），在项目中新建文件 MyVilApplication.kt，并按如下方式初始化 VIL：

1import com.tomtom.automotive.integration.vehicle.client.api.VehicleIntegrationApiClient
2import com.tomtom.automotive.integration.vehicle.client.api.error.NavAppError
3import com.tomtom.automotive.integration.vehicle.client.api.status.NavAppConnectionStatus
4import com.tomtom.automotive.integration.vehicle.client.api.status.NavAppConnectionStatusType
5import com.tomtom.automotive.integration.vehicle.client.api.status.StatusCallback
6import com.tomtom.automotive.integration.vehicle.client.lib.VehicleIntegrationApiClientFactory
7

8...
9

10class MyVilApplication : Application() {
11    lateinit var vilClient: VehicleIntegrationApiClient
12

13    override fun onCreate() {
14        super.onCreate()
15

16        vilClient = VehicleIntegrationApiClientFactory.create(
17            context = this,
18            statusCallback = object : StatusCallback {
19                override fun onConnectionStatus(connectionStatus: NavAppConnectionStatus) {
20                    if (connectionStatus.connectionStatusType == NavAppConnectionStatusType.CONNECTED) {
21                        // 设置参数
22                    }
23                }
24

25                override fun onError(error: NavAppError) {
26                    // 处理错误
27                }
28            }
29        )
30    }
31}

步骤 2. 在 AndroidManifest.xml 中声明您的应用类：

1<application
2    android:name=".MyVilApplication"
3    ...
4      <!-- 其他设置 -->
5</application>

一旦创建了 VehicleIntegrationApiClient（使用 VehicleIntegrationApiClientFactory）并收到“已连接”回调，即可开始调用 API 函数。VIL API 参考文档见 VIL API Reference。

设置参数

例如，您可以通过 VehicleIntegrationApiClient 实例的 getVehicleInfoManager() 函数设置 Vehicle Specifications 参数：

1import com.tomtom.automotive.integration.vehicle.client.api.VehicleIntegrationApiClient
2import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.vehiclespecs.VehicleSpecsCallback
3import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.vehiclespecs.VehicleSpecsFailure
4import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.vehiclespecs.VehicleSpecsParameters
5import com.tomtom.automotive.integration.vehicle.client.api.vehicleinfo.vehiclespecs.VehicleType
6import com.tomtom.automotive.integration.vehicle.client.lib.VehicleIntegrationApiClientFactory
7import com.tomtom.automotive.integration.vehicle.common.Callback
8import com.tomtom.automotive.integration.vehicle.common.Result
9

10...
11

12vilClient.getVehicleInfoManager().setVehicleSpecs(
13    VehicleSpecsParameters(VehicleType.CAR),
14    object : VehicleSpecsCallback {
15        override fun onResult(result: Result<VehicleSpecsParameters, VehicleSpecsFailure>) {
16            if (result is Result.Failure) {
17                if (result.reason == VehicleSpecsFailure.FAILED_TO_SET_VEHICLE_SPECS) {
18                    // 服务器端设置车辆规格失败
19                } else {
20                    // 意外的失败原因
21                }
22            } else {
23                // 车辆规格设置成功
24            }
25        }
26

27        override fun onFunctionalityUnavailable(reason: Callback.Reason) {
28            // 处理功能不可用
29            if (reason is Callback.Reason.IncompatibilityError) {
30                // VIL 客户端与运行中的导航应用版本不兼容
31            }
32        }
33    }
34)

必需参数

本节列出了您的应用应设置的必需参数，以成功启动 ANA。如果未设置所有必需参数，ANA 的启动画面将保持可见。
要设置这些参数，请使用 VehicleIntegrationApiClient 中相应的 API 函数，详见 VIL API Reference 指南：

  • VehicleSpecsParameters。表示通用车辆规格，如车辆类型。ANA 需要此数据以调整其行为，且在应用运行期间不应更改。详见 VIL API Reference。
  • OnlineServicesConfigurationParameters。表示在线服务配置信息。详见 VIL API Reference。指定一个完全限定域名（FQDN），格式为 subdomain.domain.tld。ANA 需要此 FQDN 以了解如何连接 TomTom 在线服务。有关如何获取 FQDN，请参阅 Set up online services。
  • OnlineServicesTokenParameters。包含在线服务的身份验证令牌，格式为 JSON Web Token (JWT)。JWT 令牌用于认证和授权访问 TomTom 在线服务。令牌是动态的，会根据令牌的过期时间在应用生命周期内变化。详见 VIL API Reference。有关如何设置 JWT 令牌，请参阅 Set up online services。
  • ResourcesParameters。表示 ANA 可访问的平台资源，如包含车载地图文件、密钥库、许可证和缓存的文件夹路径。ANA 需要此参数以了解车载地图相关文件的位置及缓存存储位置。详见 VIL API Reference。

错误处理

您的应用可能会收到以下错误情况，必须适当处理。

错误描述提示
ErrorCallback.NavAppError.SECURITY_ERRORVehicleIntegrationClient 权限不足，无法建立连接。确保您的应用具有使用 socket 通信的正确 Android 权限。
ErrorCallback.NavAppError.BIND_SERVICE_TIMEOUTVehicleIntegrationClient 无法与导航应用建立连接。确保导航应用已安装并正在运行。
ErrorCallback.NavAppError.EXCEPTION_WHEN_INVOKE_REQUESTVehicleIntegrationClient 无法完成请求。这表明导航应用存在问题；请联系支持寻求帮助。
ErrorCallback.NavAppError.VERSION_MISMATCHVehicleIntegrationClient 库版本与您的应用不兼容。确保为导航应用版本配置了正确的库版本。检查日志中的 isVersionMismatch。
ErrorCallback.NavAppError.NO_CONNECTIONVehicleIntegrationClient 不再与导航应用连接。确保导航应用仍在运行。
Result.Failure.UNHANDLEDVehicleIntegrationClient 库版本与您的应用不兼容。确保为导航应用版本配置了正确的库版本。
Callback.Reason.IncompatibilityErrorVehicleIntegrationClient 库版本与您的应用不兼容。确保为导航应用版本配置了正确的库版本。