运行环境与 SDK 集成

本页介绍杰理健康 SDK（iOS-JL_Health）的运行环境要求、SDK 框架（XCFramework）组成、工程集成步骤、权限与日志配置，以及示例工程的目录结构，帮助开发者在 iOS 应用中完成蓝牙健康功能开发的前置接入工作。

Purpose and Scope

本页覆盖「运行环境与 SDK 集成」这一能力边界内的全部内容：

• 支持的最低运行环境（iOS / Xcode / 硬件芯片 / 开发语言）
• SDK 各 XCFramework 库的职责划分与必须/可选导入策略
• 从克隆仓库到初始化 SDK 的完整集成流程
• Info.plist 蓝牙权限配置与日志管理配置
• 示例工程（code/ 目录）与文档资源（docs/ 目录）的导航

有意留给兄弟页面的话题：SDK 集成交付之后的具体功能开发（OTA 升级、表盘管理、健康数据同步、音频编解码、AI 云服务等）属于各功能模块页面的范畴，本页只说明这些模块对应导入哪个库以及如何接入，不展开其内部实现。

面向读者的提示：本仓库以二进制 XCFramework 形式发布 SDK，仓库内不包含 SDK 内部实现源码；因此本页的集成描述以仓库根目录 README.md 以及示例工程中的框架头文件为权威依据。

Overview

iOS-JL_Health 是珠海市杰理科技股份有限公司为杰理蓝牙穿戴类产品（智能手表、健康手环、智能徽章、智能戒指等）提供的 iOS 功能集成 SDK。SDK 以 XCFramework 二进制库的形式随仓库发布，并附带完整的 iOS 示例工程源码与开发文档。

SDK 按功能模块拆分为多个独立框架，形成「主业务库 + 可选功能库」的组合结构：

• 主业务库：JL_BLEKit（设备扫描连接与基础协议交互）、JL_AdvParse（广播包解析）、JL_HashPair（设备认证）、JLLogHelper（日志助手）——任何集成都必须导入。
• 可选功能库：JL_OTALib（OTA 升级）、JLDialUnit（表盘）、JLAudioUnitKit（音频编解码）、JLBmpConvertKit（图片转码）、JLPackageResKit（资源打包）——按业务需求按需导入。

这一设计意图是按需裁剪、降低包体：健康类应用只需主库即可完成连接与数据同步，只有涉及 OTA 或表盘等高级功能时才引入对应框架，避免全量导入带来的二进制体积与链接开销（参见 README「五、配置说明」中的必须/可选库划分）。

Architecture

下图展示 SDK 集成后的整体架构：应用层通过示例工程接入，SDK 层按必须/可选分组，底层依赖 iOS 系统 BLE 能力与杰理 RCSP 协议芯片。

flowchart TD
    subgraph sg_App["应用层 (iOS App)"]
        App["JL_Health 示例工程<br/>SDKTestHelper / 各功能 Demo"]
    end

    subgraph sg_SDK["SDK 层 (libs/ 目录, XCFramework)"]
        subgraph sg_Must["必须导入库"]
            BLE["JL_BLEKit.xcframework<br/>(主业务库：扫描/连接/协议)"]
            ADV["JL_AdvParse.xcframework<br/>(广播包解析)"]
            HASH["JL_HashPair.xcframework<br/>(设备认证)"]
            LOG["JLLogHelper.xcframework<br/>(日志助手)"]
        end
        subgraph sg_Opt["可选功能库"]
            OTA["JL_OTALib.xcframework<br/>(OTA 升级)"]
            DIAL["JLDialUnit.xcframework<br/>(表盘)"]
            AUDIO["JLAudioUnitKit.xcframework<br/>(音频编解码)"]
            BMP["JLBmpConvertKit.xcframework<br/>(图片转码)"]
            RES["JLPackageResKit.xcframework<br/>(资源打包)"]
            AI["AIKIT.framework<br/>(AI 云服务, 位于示例工程)"]
        end
    end

    subgraph sg_OS["系统与硬件层"]
        CORE["CoreBluetooth (BLE)"]
        CHIP["杰理 RCSP 协议芯片<br/>AC701N / AC707N / AC695N"]
    end

    App --> BLE
    BLE --> ADV
    BLE --> HASH
    App --> LOG
    App -.->|"按需导入"| OTA
    App -.->|"按需导入"| DIAL
    App -.->|"按需导入"| AUDIO
    App -.->|"按需导入"| BMP
    App -.->|"按需导入"| RES
    App -.->|"按需导入"| AI
    BLE --> CORE
    CORE -.->|"BLE 链路"| CHIP
    ADV -.->|"解析广播包"| CHIP
    HASH -.->|"设备认证握手"| CHIP

架构说明：

• 应用层是唯一与 SDK 直接交互的入口。仓库提供了完整示例（code/JL_Health，宜动健康）与轻量测试工程（code/SDKTestHelper），演示从连接到数据回调的标准用法。
• SDK 层中，JL_BLEKit 是核心枢纽：设备扫描、连接、RCSP 协议交互、健康/运动数据模型均由其承载；JL_AdvParse 与 JL_HashPair 配合完成广播解析与设备认证；JLLogHelper 贯穿所有库提供统一日志。
• 可选库彼此独立、按需组合，例如 OTA 升级依赖 JL_BLEKit 的传输通道，但表盘、音频、图片转码等库之间没有强制依赖，这是 SDK 在 V1.8.0 版本「对 SDK 库进行功能模块分离」重构后的结果。
• 系统层依赖 iOS 的 CoreBluetooth 能力，硬件侧要求芯片支持杰理 RCSP 协议（AC701N、AC707N、AC695N 等），双方通过 BLE 链路完成协议交互。

运行环境要求

以下要求来自 README「二、运行环境」一节，是集成前的硬性前置条件：

设计意图解读：

• iOS 10.0 基线与 BLE 能力绑定——所有杰理穿戴设备通过 CoreBluetooth 通信，SDK 面向的部署环境必须具备完整 BLE 栈；低于该版本的系统不在支持范围内。
• Xcode 14.0+ 是 XCFramework 格式的配套要求。SDK 以 XCFramework 分发（这是 Apple 官方推荐的多架构二进制格式，同时包含真机 arm64 与模拟器切片），旧版 Xcode 无法正确链接该格式。
• 硬件芯片约束意味着集成方必须确认目标设备采用杰理 RCSP 协议栈，广播包解析（JL_AdvParse）与设备认证（JL_HashPair）都基于该协议实现。
• Objective-C / Swift 双语支持：SDK 头文件以 Objective-C 编写，Swift 工程可通过桥接直接调用，仓库示例 code/JL_Health 即演示了完整的 Swift/OC 混合用法。

SDK 库清单与职责

必须导入的库（5.1 节）

可选导入的库（5.2 节）

设计意图解读：必须库是任何杰理设备连接的前置依赖，它们构成「解析广播 → 认证握手 → 协议交互 → 日志支撑」的完整连接闭环；可选库则按产品功能裁剪，例如仅做健康监测的 App 不需要导入 JL_OTALib 与 JLDialUnit，从而控制安装包体积并减少不必要的系统权限面。

集成步骤

README「三、快速开始」给出了从零开始的集成路径，分为仓库获取与 SDK 接入两个阶段。

3.1 克隆仓库

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

Source: README.md

3.2 集成 SDK 的四步流程

1. 导入框架：将 libs/ 目录下的 XCFramework 添加到项目中
2. 配置权限：在 Info.plist 中添加蓝牙使用权限描述
3. 初始化 SDK：参考示例工程的初始化代码进行集成
4. 开始开发：使用 SDK 提供的 API 进行健康功能开发

README「3.4 快速集成步骤」进一步强调了两个操作要点：

• 集成必要的 XCFramework 库并设置 Embed & Sign——XCFramework 属于动态/嵌入式框架，必须在 Xcode 的 Framework 设置中勾选 Embed & Sign，否则真机运行时会出现找不到库或签名错误。
• 核心调用流程固定为：设备连接 → 协议交互 → 功能调用 → 数据回调，所有功能模块都遵循这一异步回调范式。

下图是集成与运行的整体流程：

flowchart TD
    Start([开始集成]) --> Clone["git clone 仓库"]
    Clone --> Import["导入 libs/ 下 XCFramework<br/>并设置 Embed & Sign"]
    Import --> Perm["配置 Info.plist 蓝牙权限"]
    Perm --> Init["参考示例初始化 SDK"]
    Init --> Scan["扫描并连接杰理设备<br/>JL_BLEKit"]
    Scan --> Auth{"设备认证通过?<br/>JL_HashPair"}
    Auth -->|"否"| Fail["认证失败, 检查广播/配对流程"]
    Auth -->|"是"| Proto["RCSP 协议交互<br/>JL_BLEKit"]
    Proto --> Feature{"需要哪个功能?"}
    Feature -->|"OTA"| OTA["导入 JL_OTALib 执行升级"]
    Feature -->|"表盘"| DIAL["导入 JLDialUnit 管理表盘"]
    Feature -->|"音频"| AUDIO["导入 JLAudioUnitKit"]
    Feature -->|"健康数据"| Health["JL_BLEKit 数据回调"]
    OTA --> Callback["数据/事件回调返回 App"]
    DIAL --> Callback
    AUDIO --> Callback
    Health --> Callback
    Callback --> Done([功能开发完成])
    Fail --> Done

流程要点：认证（JL_HashPair）是连接后、功能调用前的必经关卡，失败时不会进入协议交互阶段；功能库的导入决策应在编译期完成（静态链接），运行期只需按模块 API 发起调用并接收回调。

工程结构

README「四、工程结构」展示了仓库布局，这是理解示例代码与库文件位置的基础：

iOS-JL_Health/
├── code/                           # 示例程序源码
│   ├── JL_Health/                  #   宜动健康源码（完整示例）
│   ├── SDKTestHelper/              #   简单功能源码（测试示例）
│   ├── JLAudioUnitKitDemo/         #   音频编解码业务库示例
│   ├── HealthAide_ALi_IOT_V0.1.2(iOS)/ # 阿里支付宝集成示例
│   └── 杰理iOS音频编解码V1.1.0/      #   手表录音数据编解码示例
├── libs/                           # 核心 SDK 库 (XCFramework 格式)
│   ├── JL_AdvParse.xcframework     #   广播包解析库
│   ├── JL_BLEKit.xcframework       #   主业务库（基础协议相关）
│   ├── JL_HashPair.xcframework     #   设备认证库
│   ├── JL_OTALib.xcframework       #   OTA 升级业务库
│   ├── JLAudioUnitKit.xcframework  #   音频编解码业务库
│   ├── JLBmpConvertKit.xcframework #   图片转码业务库
│   ├── JLDialUnit.xcframework      #   表盘相关库
│   ├── JLLogHelper.xcframework     #   日志助手库
│   └── JLPackageResKit.xcframework #   健康功能业务库
└── docs/                           # 文档资源
    ├── Jieli_Health_SDK_iOS_Releases.pdf #   版本发布记录
    ├── 杰理OTA升级(iOS)开发说明.url      #   在线文档：OTA开发说明
    ├── 杰理健康SDK开发说明.url           #   在线文档：开发说明
    └── 自定义蓝牙接入方式.url             #   在线文档：接入方式介绍

Source: README.md

关键目录速览：

除上述库外，示例工程 code/JL_Health/ 中还内置了 AIKIT.framework（AI 云服务库），其公开头文件包括 AIKIT.h、AiHelper.h、AiHandle.h、AIKITDataBuilder.h、AIKITAudioBuilder.h、AIKITDataModel.h、AIKITParameters.h、AIKITError.h、AIKITConstant.h 等——这是 V1.9.0 引入 AI 云服务、V1.10.0 引入 AI 表盘功能后在示例层交付的配套框架，用于语音/对话类 AI 能力的接入。

核心调用流程

所有杰理健康功能统一遵循「设备连接 → 协议交互 → 功能调用 → 数据回调」的异步模型。以健康数据同步为例，时序如下：

sequenceDiagram
    participant App as iOS App (JL_Health)
    participant BLE as JL_BLEKit (主业务库)
    participant ADV as JL_AdvParse
    participant HASH as JL_HashPair
    participant Dev as 杰理设备 (RCSP)

    App->>BLE: 开始扫描设备
    BLE->>ADV: 解析设备广播包
    ADV-->>BLE: 设备信息 (名称/协议/地址)
    BLE-->>App: 扫描结果回调
    App->>BLE: 发起连接
    BLE->>Dev: BLE 连接建立
    BLE->>HASH: 设备认证握手
    HASH-->>BLE: 认证结果
    BLE-->>App: 连接成功回调
    App->>BLE: 功能调用 (如: 同步健康数据)
    BLE->>Dev: RCSP 协议命令下发
    Dev-->>BLE: 数据/ACK 上报
    BLE-->>App: 数据回调 (心率/血氧/睡眠等)

时序要点：

• 广播解析先行：JL_AdvParse 在扫描阶段即识别设备身份，帮助 App 过滤出杰理协议设备，避免误连。
• 认证是硬门槛：JL_HashPair 的握手失败会导致连接流程中断，App 应处理认证失败回调并给出重试或引导提示。
• 命令/回调分离：功能调用（下行命令）与数据上报（上行回调）走不同通道，App 侧通过 block/delegate 接收结果，这正是示例工程中所有功能模块的统一编程范式。

权限与日志配置

Info.plist 蓝牙权限

SDK 依赖 CoreBluetooth，必须在 Info.plist 中声明蓝牙使用权限，否则首次连接会被系统拦截：

<key>NSBluetoothAlwaysUsageDescription</key>
<string>需要使用蓝牙功能连接杰理设备</string>
<key>NSBluetoothPeripheralUsageDescription</key>
<string>需要作为蓝牙外设连接杰理设备</string>

Source: README.md

其中 NSBluetoothAlwaysUsageDescription 是 iOS 13+ 的常驻蓝牙权限，NSBluetoothPeripheralUsageDescription 用于兼容旧系统；两者同时声明可覆盖 iOS 10.0 到最新系统的权限弹窗要求。

日志管理（JLLogHelper）

JLLogHelper.xcframework 提供统一的日志管理能力，可通过其接口控制日志输出与存储。集成与调试建议：

• 集成阶段保持日志全开，通过日志确认广播解析、认证、协议交互是否按预期执行；
• 发布阶段可通过 JLLogHelper 关闭或降级日志级别，避免敏感协议数据落盘；
• 真机调试时使用 Xcode 的 Console 查看器实时查看 SDK 日志输出（README「六、调试技巧」）。

配置选项汇总

下表汇总集成本 SDK 所需的全部配置项（依据 README「五、配置说明」）：

API 入口参考

SDK 以二进制 XCFramework 交付，仓库内不包含实现源码；本页列出从仓库可验证的公开 API 入口（框架头文件），具体方法签名请以框架内头文件或在线文档中心为准。

主业务库 JL_BLEKit.xcframework

• 职责：设备扫描、连接、RCSP 协议交互、健康/运动数据模型、消息/天气/联系人/闹钟等数据同步。
• 典型入口：扫描与连接 API、健康数据回调协议、各功能模块管理器（参考 code/JL_Health 示例调用方式）。

配套库入口

AI 云服务库 AIKIT.framework（示例工程内置）

code/JL_Health/AIKIT.framework/Headers/ 下公开的头文件构成 AI 能力的入口集合：

• AIKIT.h — 库总入口；AIKITConstant.h — 常量定义；AIKITError.h — 错误码
• AiHelper.h / AiHandle.h / AiHelperMaker.h — AI 助手实例的创建、管理与交互
• AIKITDataBuilder.h / AIKITAudioBuilder.h / AIKITDataModel.h / AIKITInputData.h / AIKITParameters.h — 请求数据构造与参数模型
• AIKITCtxContent.h / AIKITUsrContext.h / AIKITCustomData.h / ChatParam.h — 上下文与对话参数
• AiAudioDefine.h — 音频相关类型定义

说明：以上头文件仅列举文件名与职责分类；各方法的参数、返回类型与回调语义需在 Xcode 中打开对应框架查看，或查阅在线 SDK 文档。

失败模式、边界情况与并发注意

基于 README 与示例工程结构，可识别的失败模式与注意事项如下：

并发与异步注意：SDK 采用命令下发/回调上报的异步模型，App 侧应避免在回调线程中同步执行耗时操作；多功能并发调用（如 OTA 过程中同步健康数据）可能产生协议时序竞争，建议按示例工程的串行调用方式组织业务逻辑。

性能与运维考虑

• 按需裁剪框架：只导入实际使用的可选库，减少链接体积与启动加载时间；这是 SDK 功能模块分离（V1.8.0 起）的直接收益。
• 日志分级：JLLogHelper 支持控制输出与存储；发布包建议关闭协议级日志，避免数据敏感信息与 IO 开销。
• 调试手段：Xcode Console 实时查看日志；code/SDKTestHelper 作为最小复现工程，可在反馈问题时快速定位是 SDK 问题还是业务代码问题。
• 版本管理：SDK 版本迭代记录见 docs/Jieli_Health_SDK_iOS_Releases.pdf 与 README「八、版本历史」；升级 SDK 时替换 libs/ 下对应 XCFramework 并保持 Embed & Sign 设置。

扩展点

• 自定义命令：SDK 支持客户自定义命令扩展，用于对接私有协议功能（README「一、概述」功能表中的「自定义命令」）。
• 功能库组合：可选库可自由组合，例如「OTA + 表盘」产品只导入 JL_OTALib 与 JLDialUnit，不影响主链路。
• AI 能力扩展：AIKIT.framework 的 Builder/Parameters/Context 系列头文件为 AI 表盘与 AI 云服务提供了参数化扩展接口，可在示例工程中按业务定制请求内容。
• 接入方式文档：docs/自定义蓝牙接入方式.url 提供了非标准场景下的蓝牙接入方式介绍。

版本历史（与集成相关的关键节点）

README「八、版本历史」记录了 SDK 版本演进，与集成直接相关的要点如下：

集成提示：升级 SDK 时重点核对「必须导入库」清单是否变化（历史上图像转换库在 V1.12.0 从主库分离为 JLBmpConvertKit），以及新版本对 iOS/Xcode 最低版本要求是否提高。

Related Links

• README.md（中文总览与集成指南）
• README_EN.md（英文版说明）
• LICENSE（Apache License 2.0）
• 在线文档中心（SDK 开发说明）
• 杰理官网
• 问题反馈（GitHub Issues）

相关目录页提示：OTA 升级流程、表盘管理、健康数据同步、音频编解码等具体功能模块分别属于各自的功能页；本页仅覆盖它们的接入前置条件与库选择。