初始化

本章节说明 Android 端 SDK 集成的完整初始化流程，共包含 5 个部分：

序号	模块	入口	说明
1	主 SDK	SDK.getInstance().initialize(...)	必选，应用启动时完成
2	Entity	EntityService.initialize(...)	按需，主 SDK 成功后调用
3	DataCollector	DataCollectorService.initialize(...)	按需，主 SDK 成功后调用
4	NavigationService	NavigationService.Factory.createInstance(...)	主 SDK 成功后创建；可在主线程或后台线程；退出前 dispose()
5	MapView	MapView.initialize(...)	按需，在地图页面中初始化，并绑定页面生命周期

1. 前置条件

• 已完成工程搭建与依赖接入
• 已配置 API Key、API Secret、CloudEndPoint
• 已准备可写缓存目录（用于 setSdkCacheDataDir）
• 若使用 Onboard/Hybrid，已准备本地地图数据目录（用于 setSdkDataDir）
• setSdkCacheDataDir、setSdkDataDir 设置的目录需具备读写权限

2. 初始化顺序

应用启动
  └─ 1. 主 SDK 初始化
       └─ 2. Entity 初始化（按需）
       └─ 3. DataCollector 初始化（按需）
  └─ 进入导航 / 地图业务
       └─ 4. NavigationService 创建（路线规划、定位、沿途信息、播报等）
  └─ 进入地图页面
       └─ 5. MapView 初始化（绑定页面生命周期）

• 第 1～3 步在 启动页 完成，全局只需初始化一次；建议在后台线程（Worker Thread）执行，避免阻塞主线程。
• 第 4 步在 主 SDK 初始化成功之后 创建；createInstance 可在主线程或后台线程调用（不强制与主 SDK 同线程）；可在 Application 或导航相关页面持有一个实例。
• 第 5 步在 包含地图的 Activity / Fragment 的主线程中完成；页面销毁时配合 onPause 暂停渲染，避免资源泄漏。

2.1 应用启动初始化示例（后台线程）

主 SDK、Entity、DataCollector 的 initialize 均为耗时操作，建议在 Dispatchers.IO 或独立 Worker Thread 中顺序执行，完成后切回主线程更新 UI。

// 在启动页调用
fun initSdkServices(context: Context, onComplete: (Boolean) -> Unit) {
  thread { // 或使用 lifecycleScope.launch(Dispatchers.IO) { ... }
    val sdkOptions = SDKOptions.builder()
        .setApiKey("<YOUR_API_KEY>")
        .setApiSecret("<YOUR_API_SECRET>")
        .setSdkCacheDataDir("<YOUR_CACHE_DIR>")
        .setCloudEndPoint("<YOUR_CLOUD_ENDPOINT>")
        .setLocale(<YOUR_LOCALE>)
        .setUserId("<YOUR_USER_ID>")
        .setDeviceGuid("<YOUR_DEVICE_GUID>")
        .setRegion("<YOUR_REGION>")
        .setSdkDataDir("<YOUR_MAP_DATA_DIR>")
        .build()

    val vehicleInfoConfig = VehicleInfoConfig.Builder().build()
    val navSDKOptions = NavSDKOptions.builder(sdkOptions, vehicleInfoConfig)
        .setTrafficRefreshTime(120)
        .setTrafficExpireTime(120)
        .enableDownloadMapData(true)
        .enableHDMap(true)
        .setMapStreamingSpaceLimit(1024 * 1024 * 1024L)
        .build()

    // 1) 主 SDK
    val success = SDK.getInstance().initialize(context, navSDKOptions) == 0

    if (success) {
      // 2) Entity
      try {
        EntityService.initialize(sdkOptions)
      } catch (e: IllegalArgumentException) {
        // 检查 API Key / Secret、CloudEndPoint 等配置
      } catch (e: EntityException) {
        // 检查本地数据目录或 Entity 依赖是否完整
      }

      // 3) DataCollector（按需）
      DataCollectorService.initialize(context, sdkOptions)
    }

    // 完成后切回主线程更新 UI
    Handler(Looper.getMainLooper()).post { onComplete(success) }
  }
}

---

3. 主 SDK 初始化

主 SDK 负责引擎、地图数据、导航等核心能力，是整个集成的第一步。

入口： SDK.getInstance().initialize(context, navSDKOptions)

返回值： 0 表示成功，非 0 表示失败。

线程要求： 建议在后台线程调用，勿在主线程执行。

关键配置：

配置类	主要字段
SDKOptions	apiKey、apiSecret、cloudEndPoint、locale、region、sdkCacheDataDir、sdkDataDir
NavSDKOptions	交通信息刷新频率、Map Streaming 空间上限、车辆信息

完整配置与调用示例见 2.1 应用启动初始化示例（后台线程）。

---

4. Entity 初始化

Entity 服务提供收藏点、历史记录等实体数据能力。

入口： EntityService.initialize(sdkOptions)

调用时机： 主 SDK 初始化成功后，复用同一份 sdkOptions。

线程要求： 与主 SDK 相同，建议在后台线程调用。

异常处理： 建议捕获 IllegalArgumentException（参数配置错误）与 EntityException（业务初始化失败）。

---

5. DataCollector 初始化

DataCollector 用于事件采集与上报，为可选模块。

入口： DataCollectorService.initialize(context, sdkOptions)

调用时机： 主 SDK 初始化成功后；若业务不需要数据采集，可跳过。

线程要求： 与主 SDK 相同，建议在后台线程调用。

---

6. NavigationService 初始化

NavigationService 是路线规划、开始/停止导航、定位回调、沿途信息、语音引导等能力的统一入口。必须在主 SDK initialize 成功之后 再创建。

入口： NavigationService.Factory.createInstance(navigationServiceOptions)

反初始化： navigationService.dispose()（幂等，可重复调用）

线程要求： 须在主 SDK initialize 成功之后调用。createInstance 可在主线程或后台线程执行，无强制线程限制；常与主 SDK 同在后台线程顺序创建，以减少切换，也可在主线程单独创建。

与主 SDK 的关系： NavigationService 为独立 Native 服务实例，不随主 SDK initialize 自动创建；退出或切换账号时，若已创建则须调用 dispose()，且 dispose 之后不得再使用该实例。

6.1 创建示例

// 主 SDK 已成功 initialize 之后
val navigationService = NavigationService.Factory.createInstance(
    NavigationServiceOptions.Builder()
        // .disableAlert()              // 不需要沿途信息 / 语音引导时关闭（见「沿途信息」）
        // .disableAudioGuidance()      // 仅关闭播报，Alert 仍可用
        .build()
)

// 注册监听（定位、导航、沿途信息等，回调在 Message 线程）
navigationService.eventHub.addPositionEventListener(positionListener)
navigationService.eventHub.addAlertEventListener(alertListener)

NavigationServiceOptions 的详细配置见开发指南各专题（如 沿途信息、播报、定位 等）。

6.2 反初始化示例

在 导航模块退出、ViewModel.onCleared() 或 应用退出 时释放：

// 若正在导航，可先显式停止（dispose 内部也会结束当前会话）
navigationService.stopNavigation()

// 移除已注册的 eventHub 监听（传入具体 listener 实例，勿传 null）
navigationService.eventHub.removePositionEventListener(positionListener)
navigationService.eventHub.removeAlertEventListener(alertListener)

navigationService.dispose()

dispose() 会结束当前导航会话、清空 eventHub 监听并释放底层 DriveSession 资源。dispose 之后不得再调用该实例上的任何 API；若仍需导航能力，须重新 createInstance。

---

7. MapView 初始化

MapView 在地图页面中展示地图，必须在主 SDK 初始化成功之后 再调用。

与第 1～3 步不同，MapView 的初始化和销毁与 页面生命周期 强相关：页面可见时渲染，页面不可见时暂停。

7.1 布局配置

在 Activity 或 Fragment 布局中加入 TnMapView：

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:layout_width="match_parent"
    android:layout_height="match_parent">

    <com.telenav.map.views.TnMapView
        android:id="@+id/mapView"
        android:layout_width="0dp"
        android:layout_height="0dp"
        app:layout_constraintBottom_toBottomOf="parent"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toTopOf="parent" />
</androidx.constraintlayout.widget.ConstraintLayout>

7.2 代码示例

private fun initMapView() {
    val config = MapViewInitConfig(
        context = requireContext().applicationContext,
        lifecycleOwner = viewLifecycleOwner,
        readyListener = MapViewReadyListener<MapView> { mapView ->
            // 地图就绪后，再操作车标、相机等（勿在 initialize 调用后立即执行）
            mapView.vehicleController().setLocation(initialLocation)
        }
    )
    binding.mapView.initialize(config)
}

// --- 与页面生命周期配对调用 ---

override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
    super.onViewCreated(view, savedInstanceState)
    initMapView() // SDK 已初始化成功后再调用
}

override fun onResume() {
    super.onResume()
    binding.mapView.onResume() // 页面可见，恢复渲染
}

override fun onPause() {
    super.onPause()
    binding.mapView.onPause() // 页面不可见，暂停渲染
}

7.3 生命周期对照

页面回调	MapView 调用	作用
onViewCreated	initialize(MapViewInitConfig)	创建地图，绑定 lifecycleOwner
onResume	onResume()	页面进入前台，恢复地图渲染
onPause	onPause()	页面进入后台，暂停地图渲染

initialize 与 onResume / onPause 缺一不可。缺少生命周期转发会导致地图黑屏、卡顿或资源未释放。

MapViewInitConfig 常用参数：

参数	说明
context	使用 applicationContext，避免 Activity 泄漏
lifecycleOwner	当前 Activity 或 Fragment，用于自动感知生命周期
readyListener	地图就绪后触发，可安全调用各 Controller API
defaultLocation	可选，地图初始中心点
defaultZoomLevel	可选，初始缩放级别
createCvp	可选，是否创建默认车标（默认 true）

---

8. 释放资源

应用退出或切换账号时释放已初始化的模块（dispose 建议在后台线程执行）：

// 地图页面 onPause 中已调用 mapView.onPause()

// NavigationService（若已创建）
navigationService.stopNavigation()  // 可选，正在导航时建议先停止
navigationService.eventHub.removePositionEventListener(positionListener)
navigationService.eventHub.removeAlertEventListener(alertListener)
navigationService.dispose()

// 主 SDK 与子模块
SDK.getInstance().dispose(true)
EntityService.shutdown()
DataCollectorService.shutdown()

---

9. 常见问题排查

现象	排查方向
主 SDK initialize 失败	检查 Key/Secret、CloudEndPoint、Region 是否匹配
Onboard/Hybrid 无法工作	检查 setSdkDataDir 路径是否存在、是否具备读写权限
DataCollector 无数据	确认已调用 initialize，且业务侧已触发上报请求
地图黑屏或卡顿	确认主 SDK 已成功初始化；onResume/onPause 是否与页面生命周期配对
地图 API 调用无效	在 readyListener 回调中操作，而非 initialize 调用后立即执行
导航 API 抛 NAVIGATION_SERVICE_DISPOSED	确认未在 NavigationService.dispose() 之后继续调用该实例
创建 NavigationService 失败	确认主 SDK 已成功 initialize