Vehicle integration basics

介绍

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

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

项目设置

如果尚未安装，请安装 Android Studio 。
要设置 VIL，首先需要一个现有的 Android 项目。
- 如果没有，请参照此指南创建新的 Android 项目。
确保最低 SDK API 级别设置为 27（Android 8.1 “Oreo”） 或更高。
确保使用的最低 kotlin 版本为 1.9.25 或更高。

配置项目依赖

步骤 1. 将 Artifactory 仓库 URL 添加到 repositories 块（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" // 替换为您的 Artifactory 用户名
9
                password = "your-password" // 替换为您的 Artifactory 密码
10
            }
11
        }
12
    }
13
}

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

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

使用 VIL

实例化 Vehicle Integration API 客户端

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

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

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

8
...
9

10
class 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 参数：

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

10
...
11

12
vilClient.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。FQDN 是 ANA 理解如何连接 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_ERROR`	VehicleIntegrationClient 权限不足，无法建立连接。	确保您的应用具有使用套接字通信的正确 Android 权限。
`ErrorCallback.NavAppError.BIND_SERVICE_TIMEOUT`	VehicleIntegrationClient 无法与导航应用建立连接。	确保导航应用已安装并正在运行。
`ErrorCallback.NavAppError.EXCEPTION_WHEN_INVOKE_REQUEST`	VehicleIntegrationClient 无法完成请求。	这表示导航应用存在问题；请联系支持人员协助。
`ErrorCallback.NavAppError.VERSION_MISMATCH`	VehicleIntegrationClient 库版本与您的应用不兼容。	确保为导航应用版本配置了正确的库版本。检查日志中的 `isVersionMismatch`。
`ErrorCallback.NavAppError.NO_CONNECTION`	VehicleIntegrationClient 不再连接到导航应用。	确保导航应用仍在运行。
`Result.Failure.UNHANDLED`	VehicleIntegrationClient 库版本与您的应用不兼容。	确保为导航应用版本配置了正确的库版本。
`Callback.Reason.IncompatibilityError`	VehicleIntegrationClient 库版本与您的应用不兼容。	确保为导航应用版本配置了正确的库版本。