工程导入与依赖配置

本文介绍 Android-JL_Health 仓库中示例工程（宜动健康 HealthAide 与手表测试工具 WatchTestTool）的导入方式、AAR 依赖库清单、Gradle 构建配置、权限声明与常见问题，帮助开发者快速将杰理健康 SDK 接入自有工程。

Purpose and Scope

本页覆盖以下内容：

• 仓库目录结构解析（code/、libs/、apk/、doc/ 各目录的作用）
• 将示例工程导入 Android Studio 的标准步骤
• 杰理健康 SDK 各 AAR 依赖库（核心库、蓝牙连接库、OTA 库、RCSP 协议库等）的功能与引入方式
• app/build.gradle 关键构建配置（SDK 版本、ABI、签名、BuildConfig 等）
• AndroidManifest 权限配置与示例工程运行方法

以下主题属于其他页面，不在本页展开：

• SDK 初始化与 WatchManager 的编写，见「SDK 初始化」相关章节
• 具体业务功能（OTA 升级、表盘管理、健康数据同步等）的 API 用法，见各功能页面
• 蓝牙连接库 / OTA 外接库的独立开发文档，见仓库 doc/ 目录对应文档

Overview

Android-JL_Health 是珠海杰理科技为蓝牙穿戴类产品提供的健康数据与设备管理开发平台，基于 RCSP 协议（远程控制系统协议） 实现设备控制，支持智能手表、健康手环等可穿戴设备。仓库本身既是 SDK 的发布载体，也携带了两个可编译运行的参考工程：

版本号命名规律为 V<应用版本>_SDK_V<SDK版本>，例如 HealthAide_V1.1.0_SDK_V1.14.0 表示应用版本 1.1.0、所依赖的 SDK 版本 1.14.0。SDK 本身以 AAR 文件形式随仓库 libs/ 目录发布，而非通过 Maven 远程仓库分发，因此导入工程的核心动作就是：把对应版本的 AAR 放进工程的 libs 目录，并在 build.gradle 中通过 fileTree 声明依赖。

运行环境要求（见 README.md）：

Architecture

下图展示仓库的物理结构、两个示例工程与 SDK 依赖库之间的组织关系：

flowchart TD
    subgraph sg_Repo["Android-JL_Health 仓库根目录"]
        subgraph sg_Code["code/ 参考源码工程"]
            App["HealthAide<br/>(app + wheelview)"]
            Tool["WatchTestTool"]
        end
        subgraph sg_Libs["libs/ 核心库文件夹"]
            JLWatch["JL_Watch Vxxx-release.aar<br/>健康SDK核心库"]
            BtConnect["jl_bluetooth_connect.aar<br/>蓝牙连接"]
            BtOta["jl_bt_ota.aar<br/>OTA升级"]
            Rcsp["jl_rcsp.aar<br/>RCSP基础协议"]
            HealthHttp["jl_health_http.aar<br/>健康服务器"]
            BmpConv["BmpConvert.aar<br/>图像转换"]
            GifConv["GifConvert.aar<br/>GIF转换"]
            AudioDec["jl_audio_decode.aar<br/>音频解码"]
        end
        subgraph sg_Other["其他目录"]
            Apk["apk/ 测试APK"]
            Doc["doc/ 开发文档"]
            Pdf["SDK发布记录 PDF"]
        end
    end

    App -->|"libs/ 目录 fileTree 依赖"| JLWatch
    App -->|"libs/ 目录 fileTree 依赖"| BtConnect
    App -->|"libs/ 目录 fileTree 依赖"| BtOta
    App -->|"libs/ 目录 fileTree 依赖"| Rcsp
    App -->|"libs/ 目录 fileTree 依赖"| HealthHttp
    Tool -->|"同构依赖"| JLWatch
    JLWatch -->|"基于"| Rcsp
    JLWatch -->|"调用"| BtConnect
    JLWatch -->|"调用"| BtOta

各层职责说明：

• 参考工程层（code/）：提供可直接编译运行的 App 源码，是开发者「照着改」的最佳起点。HealthAide 是完整演示，WatchTestTool 是轻量测试工具。
• 核心库层（libs/）：SDK 以 AAR 形态发布，其中 JL_Watch 是功能入口（健康数据、表盘、消息同步等），其内部基于 jl_rcsp 协议库，并通过 jl_bluetooth_connect 完成 BLE 通道收发，通过 jl_bt_ota 完成固件升级。
• 资源层（apk/、doc/）：apk/ 提供可直接安装的测试包用于验收 SDK 功能；doc/ 提供各库独立开发文档，与代码工程互补。

工程导入步骤

1. 克隆仓库

首先将仓库克隆到本地（README.md 3.1 节）：

git clone https://github.com/Jieli-Tech/Android-JL_Health.git
cd Android-JL_Health

注：仓库同时托管于 Gitee，国内开发者可将上面的地址替换为 Gitee 镜像地址以加速克隆。

2. 在 Android Studio 中打开工程

官方推荐流程（README.md 3.2 节）：

1. 打开 Android Studio
2. 选择 Open an existing project
3. 导航到克隆/解压后的 code/ 目录
4. 打开对应的示例工程文件（即 HealthAide_V1.1.0_SDK_V1.14.0/ 或 WatchTestTool_V0.9.0_SDK_V1.14.0/ 目录下的 build.gradle）

两个示例工程都是独立完整的 Gradle 工程，每个工程内部包含根 build.gradle 与模块级 app/build.gradle（HealthAide 另有 wheelview 模块），因此直接选择工程根目录即可被 Android Studio 识别。

3. 等待 Gradle 同步并构建

导入后 Android Studio 会自动执行 Gradle Sync。首次同步需要下载依赖并处理 libs 目录下的 AAR，耗时取决于网络环境。同步成功后可先构建一次 Debug 包验证环境。

完整导入与构建流程如下：

sequenceDiagram
    participant Dev as 开发者
    participant Git as Git 仓库
    participant AS as Android Studio
    participant Gradle as Gradle 构建
    participant Libs as libs/ AAR 依赖

    Dev->>Git: git clone 仓库
    Git-->>Dev: 本地源码 + libs/ AAR
    Dev->>AS: Open an existing project
    AS->>AS: 识别 settings.gradle / build.gradle
    AS->>Gradle: 触发 Gradle Sync
    Gradle->>Libs: 解析 fileTree 本地 AAR/JAR
    Libs-->>Gradle: 本地依赖就绪
    Gradle->>Gradle: 下载远程依赖(gson/androidx 等)
    Gradle-->>AS: Sync 完成
    Dev->>Gradle: 构建 Debug APK
    Gradle-->>Dev: 生成 APK / 安装到设备

依赖配置

SDK AAR 依赖库清单

杰理健康 SDK 由多个 AAR 组成，各库职责不同，接入时可按需引入（README.md 3.3 节）：

xxx 为版本号，各库版本需与 libs/ 目录下实际文件一致。仓库根目录 libs/ 还包含 ALi/（支付宝激活库）、JL/ui/（jl_dialog、jl-component-lib 等 UI 组件库）与 jldecryption_v0.4-release.aar（加解密库），示例工程会按功能需要拷贝到模块 libs 目录。

在 build.gradle 中声明依赖

将所需 AAR 放入模块的 libs 文件夹后，在模块级 build.gradle 中添加如下依赖（README.md 3.3 节）：

dependencies {
    //1.将上面的aar文件放入工程目录中的对应moudle的lib文件夹下
    //2.在moudlu的build.gradle中添加
    implementation fileTree(include: ['*.aar'], dir: 'libs')

    //SDK内部使用了gson进行数据解析，需自行引入
    implementation 'com.google.code.gson:gson:2.13.1'
}

Source: README.md

关键点：

• fileTree(include: ['*.aar'], dir: 'libs') 会把 libs 目录下所有 AAR 一并引入，无需逐个写 implementation files(...)，这也是示例工程统一使用的方式。
• Gson 是 SDK 的数据解析依赖，必须自行引入，且建议使用较新版本（示例使用 2.13.1）。
• 若同时存在 JAR 依赖，可再补充 implementation fileTree(include: ['*.jar'], dir: 'libs')，示例工程两者都声明了。

示例工程的实际依赖配置

HealthAide 的 app/build.gradle 完整展示了本地 AAR 与远程开源依赖的混用方式（app/build.gradle）：

dependencies {

    implementation fileTree(include: ['*.jar'], dir: 'libs')
    implementation fileTree(include: ['*.aar'], dir: 'libs')

    implementation 'androidx.multidex:multidex:2.0.1'
    implementation 'androidx.appcompat:appcompat:1.4.2'
    implementation 'com.google.android.material:material:1.6.1'
    implementation 'androidx.constraintlayout:constraintlayout:2.1.4'
    implementation 'androidx.legacy:legacy-support-v4:1.0.0'
    implementation 'androidx.lifecycle:lifecycle-livedata-ktx:2.5.1'
    implementation 'androidx.lifecycle:lifecycle-viewmodel-ktx:2.5.1'
    implementation 'androidx.navigation:navigation-fragment:2.3.5'
    implementation 'androidx.navigation:navigation-ui:2.3.5'
    implementation 'androidx.activity:activity:1.11.0'
    testImplementation 'junit:junit:4.+'
    androidTestImplementation 'androidx.test.ext:junit:1.1.3'
    androidTestImplementation 'androidx.test.espresso:espresso-core:3.4.0'
    implementation 'com.kyleduo.switchbutton:library:2.0.0'
}

Source: app/build.gradle

该文件后续还引入了图表库（MPAndroidChart）、Room 持久化、Glide 图片加载、Retrofit/OkHttp 网络库、二维码扫描等第三方库，均为业务演示所需，并非 SDK 强制要求——接入 SDK 时最小依赖集为「AAR 核心库 + gson + androidx 基础组件」。

构建配置详解（app/build.gradle）

示例工程的模块级构建脚本是整个仓库的「配置权威」，接入自有工程时可对照此文件逐项迁移。以下按块解析。

Android 块与 defaultConfig

android {
    namespace 'com.jieli.healthaide'
    compileSdk 36
    buildToolsVersion '36.0.0'

    signingConfigs {
        debug {
            storeFile file('debug.keystore')
            storePassword 'android'
            keyAlias 'androiddebugkey'
            keyPassword 'android'
        }
    }

    defaultConfig {
        applicationId "com.jieli.healthaide"
        minSdk 21
        targetSdk 35
        versionCode 909
        versionName "1.1.0"
        archivesBaseName = getAppName("JLHealthAide", versionName, versionCode)

        multiDexEnabled true
        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
        ...
        ndk {
            // 设置支持的SO库架构
            abiFilters 'armeabi-v7a', 'arm64-v8a'
        }
    }
}

Source: app/build.gradle

要点解读：

• minSdk 21（Android 5.1）：与 README「运行环境」一节要求的 Android 5.1+ 一致，SDK 最低支持 Android 5.1。
• compileSdk 36 / targetSdk 35：使用较新的编译 SDK；targetSdk 35 意味着示例已适配 Android 15 的行为变更。
• multiDexEnabled true：SDK 与演示代码体积较大，方法数可能超 64K，必须开启 multidex（README 与 androidx.multidex:multidex:2.0.1 依赖配套）。
• abiFilters 'armeabi-v7a', 'arm64-v8a'：SDK 内置 SO 库仅提供 32/64 位 ARM 架构，过滤掉 x86 等架构可显著减小 APK 体积；注意接入后无法在 x86 模拟器上直接运行原生部分。
• archivesBaseName = getAppName(...)：通过脚本函数生成带版本号的 APK 输出名（如 JLHealthAide_V1.1.0_909.apk），便于发布归档。

buildTypes 与构建脚本函数

    buildTypes {
        release {
            minifyEnabled false
            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
            buildConfigField("String", "IFLYTEK_APP_ID", getProps("IFLYTEK_APP_ID"))
            buildConfigField("String", "IFLYTEK_API_KEY", getProps("IFLYTEK_API_KEY"))
            buildConfigField("String", "IFLYTEK_API_SECRET", getProps("IFLYTEK_API_SECRET"))
        }
        debug {
            signingConfig signingConfigs.debug
            buildConfigField("String", "IFLYTEK_APP_ID", getProps("IFLYTEK_APP_ID"))
            buildConfigField("String", "IFLYTEK_API_KEY", getProps("IFLYTEK_API_KEY"))
            buildConfigField("String", "IFLYTEK_API_SECRET", getProps("IFLYTEK_API_SECRET"))
        }
    }
    sourceSets {
        main {
            jniLibs.srcDirs = ['libs']
        }
    }
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
    buildFeatures {
        dataBinding = true
        viewBinding = true
        buildConfig = true
    }

Source: app/build.gradle

要点解读：

• minifyEnabled false：示例工程 release 未开启混淆，便于调试；正式接入时应在 proguard-rules.pro 中为 SDK 相关类补充 keep 规则（SDK 文档的混淆章节会给出规则）。
• sourceSets.main.jniLibs.srcDirs = ['libs']：把模块 libs 目录同时作为 SO 库（JNI）目录，AAR 内 SO 与外部 SO 都能被正确打包。
• buildFeatures.buildConfig = true + getProps()：从 local.properties 读取讯飞（IFLYTEK）密钥等私有配置注入 BuildConfig 字段，避免密钥入库。getProps 在文件缺失时返回空字符串 ""，不会导致构建失败（app/build.gradle）。
• Java 8 编译兼容：SDK 使用 Java 8 语法特性（如 lambda），compileOptions 与 Java 8 对齐可避免 desugar 问题。

权限配置

接入 SDK 需在 AndroidManifest.xml 中申请蓝牙与定位权限（README.md 3.4 节）：

<!-- 使用蓝牙权限 -->
<uses-permission android:name="android.permission.BLUETOOTH"/>
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN"/>

<!-- 定位权限，官方要求使用蓝牙或网络开发，需要位置信息 -->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

<!-- Android 12+ 需要增加蓝牙连接权限 -->
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />

Source: README.md

设计意图说明：

• 传统 BLUETOOTH / BLUETOOTH_ADMIN 权限仅覆盖 Android 11 及以下；Android 12（API 31）起扫描/连接 BLE 需要运行时权限 BLUETOOTH_SCAN 与 BLUETOOTH_CONNECT，因此目标版本升级后必须同步补充。
• 定位权限是 BLE 扫描的隐性要求——Android 将 BLE 扫描视为位置相关操作，不授予定位权限将无法发现设备；ACCESS_FINE_LOCATION 可提升扫描命中率。
• 运行时权限（尤其是 Android 6.0+ 的定位、Android 12+ 的蓝牙）需要在代码中动态申请，示例工程的主界面流程中有完整示范。

工程结构速览

仓库根目录布局（README.md 四、工程结构）：

Android-JL_Health/
├── apk/                                     # 测试APK文件夹
│   ├── app                                  # 宜动健康测试APK，建议在应用商店下载
│   └── tool                                 # 手表测试工具，用于测试手表功能
├── code/                                    # 参考源码工程文件夹
│   ├── app                                  # 宜动健康开放源码
│   └── tool                                 # 手表测试工具开放源码
├── doc/                                     # 开发文档文件夹
│   ├── 杰理健康SDK(Android)开发说明
│   ├── 杰理OTA外接库(Android)开发文档
│   └── 杰理连接库(Android)开发文档
├── libs/                                    # 核心库文件夹
│   ├── ALi/                                 # 支付宝相关库
│   ├── JL/ui/                               # UI组件库
│   ├── jldecryption_v0.4-release.aar        # 加密解密相关
│   ├── jl_bluetooth_connect_Vxxx-release.aar# 蓝牙连接相关
│   ├── jl_bt_ota_Vxxx-release.aar           # 杰理OTA相关
│   ├── jl_rcsp_Vxxx-release.aar             # 基础协议相关
│   ├── JL_Watch_Vxxx-release.aar            # 杰理健康SDK核心库
│   ├── BmpConvert_Vxxx-release.aar          # 图像转换
│   ├── GifConvert_Vxxx-release.aar          # GIF动态图片转换
│   └── jl_audio_decode_Vxxx-release.aar     # Opus和Speex音频解码
├── Jieli_Health_SDK_Android_Releases.pdf    # SDK发布记录
└── ReadMe.txt                               # 说明文件

对照本页「Architecture」一节的图可以更直观地理解：libs/ 是依赖的来源仓库，code/ 是依赖的消费示例，apk/ 是开箱即用的验收工具。开发者接入 SDK 时，通常从 libs/ 拷贝所需 AAR 到自有工程的 app/libs，再按本页「依赖配置」小节声明即可。

配置选项汇总

接入 SDK 时涉及的配置项可归纳为下表（默认值以示例工程为准）：

常见问题与失败模式

根据构建脚本与 README 文档可以推断出以下典型接入故障及其成因：

边界情况与注意事项

• AAR 版本与 SDK 版本强绑定：工程目录名中的 SDK_V1.14.0 即 AAR 的发布版本，升级 SDK 时应整体替换 libs/ 下的所有 AAR，避免混用不同版本导致协议不兼容。
• Gson 版本冲突：若宿主工程已引入其他版本 Gson，应以较高版本为准；SDK 仅要求可用 Gson 完成 JSON 解析。
• NDK/ABI 过滤：abiFilters 同时作用于 AAR 内 SO，过滤后 APK 不再包含 x86/x86_64 原生库，若需在模拟器验证请改用 ARM 镜像。
• 签名差异：debug 构建使用仓库自带的 debug.keystore（密码 android），release 发布时务必替换为自有签名。

性能与运维提示

• APK 体积控制：abiFilters 只保留 armeabi-v7a 与 arm64-v8a 可削减约一半原生库体积；若产品仅面向 64 位设备，可进一步只留 arm64-v8a。
• 首次构建耗时：首次 Sync 需下载大量 androidx 与第三方依赖，建议配置国内 Maven 镜像（阿里云等）加速；本地 AAR 的 fileTree 解析开销极小。
• 版本归档：archivesBaseName 自动生成带版本号的 APK 名，配合 versionCode/versionName 便于在 CI 中区分产物。
• 验收流程：导入成功后，可先安装 apk/ 目录下的官方测试 APK 验证设备连通，再用源码工程复现，以隔离「SDK 问题」与「集成问题」。

扩展点

• 多模块复用：HealthAide 中的 wheelview 是独立库模块（自带 build.gradle），可作为「如何把 SDK 相关代码封装成自研库模块」的参考范式。
• 密钥注入机制：getProps() + buildConfigField 提供了一种从 local.properties 注入私有配置的模式，可推广到任意第三方密钥（如讯飞、支付宝），保证密钥不进版本库。
• 自定义协议能力：SDK 基于 jl_rcsp 协议库，支持客户自定义命令扩展，接入时保留 JL_Watch 核心库即可在其上叠加自有命令实现。
• 按需裁剪依赖：并非所有 AAR 都必须引入——只用健康数据可跳过 GifConvert/jl_audio_decode；不用支付宝可跳过 libs/ALi。按功能裁剪可显著减小包体。

Related Links

• README.md（快速开始 / 工程结构 / 配置说明）
• HealthAide app/build.gradle
• HealthAide 根 build.gradle
• WatchTestTool app/build.gradle
• README_en.md（英文版说明）
• 文档中心：https://doc.zh-jieli.com/Apps/Android/health/zh-cn/master/index.html