工程搭建

本章节用于指导 Android 端完成 Telenav SDK 的工程接入，包含环境要求、仓库与依赖配置、以及权限声明。本文中的 SDK 组件同时覆盖 Navigation 与 Entity 模块。

环境要求

Android Studio（建议使用稳定版）
Android 6.0（API 23）及以上
Java 8 及以上
Kotlin 1.6.10 及以上
设备架构：ARM 或 x86_64
访问凭据：API Key、API Secret、云端地址等

NDK 版本说明

Android 端当前支持的 NDK 版本如下：

ndk-r15c
ndk-r19c
ndk-r21c
ndk-r25c
ndk-r28c

使用示例工程快速开始

如果希望快速验证 SDK 集成效果，也可以直接参考 Telenav 对外发布的 Android 示例工程：nav-sdk-demo。

该示例工程包含基础的 SDK 依赖配置、初始化、地图显示、路线请求和导航启动流程。开发者可以先运行示例工程确认开发环境、访问凭据和云端配置可用，再参考下文将相同配置迁移到自己的 Android 工程中。

Gradle 基础编译选项

在模块 build.gradle 的 android 块中配置 Java/Kotlin 编译目标：

android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
    kotlinOptions {
        jvmTarget = "1.8"
    }
}

配置 SDK 仓库与依赖

1) 配置 Maven 仓库

按 SDK 分发渠道配置 Maven 仓库账号：

repositories {
    maven { url "https://maven.aliyun.com/repository/public" }
    maven {
        credentials {
            username = "<REPO_USER_NAME>"
            password = "<REPO_PASSWD>"
        }
        url "https://packages.aliyun.com/maven/<YOUR_PATH>"
    }
    maven {
        credentials {
            username = "<REPO_USER_NAME>"
            password = "<REPO_PASSWD>"
        }
        url "https://telenav.jfrog.io/artifactory/telenav-maven-releases/"
    }
}

在同一个 dependencies 块中同时声明 Navigation 与 Entity 依赖：

dependencies {
    // Navigation
    implementation("com.telenav.sdk:telenav-android-mapview-r28c:${tasdk_version}")
    implementation("com.telenav.sdk:telenav-android-navigation-r28c:${tasdk_version}")
    implementation("com.telenav.sdk:telenav-android-datacollector-r28c:${tasdk_version}")
    implementation("com.telenav.sdk:telenav-android-ngx-r28c:${plugin_version}")

    // Entity
    implementation("com.telenav.sdk:telenav-sdk-base:#SDK_BASE_VERSION#")
    implementation("com.telenav.sdk:telenav-entity-cloud:#ENTITY_SDK_VERSION#")
    // 若使用 Hybrid，请替换为：
    // implementation("com.telenav.sdk:telenav-entity-hybrid:#ENTITY_SDK_VERSION#")
    // 若使用 Onboard，请替换为：
    // implementation("com.telenav.sdk:telenav-entity-onboard:#ENTITY_SDK_VERSION#")
}

如果使用 Onboard/Hybrid 模式，需要提前下载并解压对应 SDK 数据，并将目录配置到初始化参数 sdkDataDir。

AndroidManifest 权限

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.INTERNET" />

混淆与 R8 配置建议

建议在接入阶段同步配置 SDK 混淆规则。Release 构建默认启用 R8，若缺少必要 keep 规则，可能导致反射、JNI 或序列化相关类被错误裁剪/重命名，引发运行时异常。

推荐做法

在应用模块新增专用规则文件（例如 proguard-telenav-sdk.pro）。
在 build.gradle 的 release 构建类型中显式引入该规则文件。
规则内容以 SDK 发布的官方建议为准。

build.gradle 接入示例：

android {
    buildTypes {
        release {
            minifyEnabled true
            shrinkResources true
            proguardFiles getDefaultProguardFile("proguard-android-optimize.txt"),
                "proguard-rules.pro",
                "proguard-telenav-sdk.pro"
        }
    }
}

Proguard 文件参考：

############################################
# TASDK Android Unified 
############################################

##########
# Global
##########
-keepattributes SourceFile,LineNumberTable
-renamesourcefileattribute SourceFile
-keepattributes Exceptions,InnerClasses,Signature,Deprecated,EnclosingMethod,*Annotation*
-keepparameternames
-ignorewarnings

################################
# Simplified TASDK keep strategy
################################
-keep class com.telenav.** { *; }

# Keep Android dispatcher factory for map coroutines integration.
-keep class kotlinx.coroutines.android.AndroidDispatcherFactory {*;}

# gson
-keepattributes Signature
-keepattributes *Annotation*
-keep class sun.misc.Unsafe { *; }
-dontwarn com.telenav.address.**
-dontwarn com.telenav.onboard.**

# lucene
-keep class org.apache.lucene.** { *; }

# other
-keep class opennlp.tools.** { *; }
-keep class com.spatial4j.** { *; }
-keep class org.apache.solr.** { *; }
-dontwarn com.mysql.**
-dontwarn com.spatial4j.**
-dontwarn opennlp.**
-dontwarn org.postgresql.**

常见注意事项

依赖版本需与发布说明匹配，避免 tasdk_version 与 plugin_version 组合不兼容。
初始化步骤请参考下一章节初始化。
若使用手动引入 AAR/JAR（非 Gradle 自动拉取），需同时补齐传递依赖（如 okhttp/okio 等）。