## 一套 BLE 代码，五端通用

想把蓝牙接进 Unity，最头疼的往往是平台差异：iOS 要配 plist，Android 要处理权限，Windows

又是另一套 API……Jauuyoo Bluetooth 把这些差异都收进了同一套接口里。你只要在 iOS、Android、

macOS、Windows 和 OpenHarmony 上调用一样的扫描、连接、读写与订阅方法，平台相关的事交给模块

处理，业务代码里不会冒出任何 #if 分支。

所有原生实现（iOS 的 .mm、Android 的 .java、macOS 的 .bundle、Windows 的 .dll、

OpenHarmony 的 .etslib + .so）全部随包提供，不依赖任何第三方蓝牙

中间件。这意味着你拿到的是一个完整、可控、好排查的方案，不用担心某个库哪天突然不维护了。

## 核心特性

**五端统一 API** —— 同一套调用覆盖五个平台。写一次，到处跑。

**和你的项目零耦合** —— 日志、权限弹窗、前后台状态这些「外部依赖」都通过接口注入。运行时

不会引用你工程的任何类型，直接拖进既有项目也不会产生依赖冲突。

**权限全自动，你几乎不用管** —— 构建时，模块自动往各平台工程注入权限声明和用途文案；

运行时统一封装系统弹窗、永久拒绝后的引导，以及跳转系统设置的入口。你不需要手写任何构建

后处理脚本。

💡 小提示：Android 12 及以上已经不再需要定位权限来做 BLE 扫描；Android 11 及以下的设备

仍按系统要求需要定位权限，模块会按平台自动处理，你无需操心。

**息屏也能保活** —— 针对息屏、切后台的场景做了连接保活。iOS 上依赖系统自带的

bluetooth-central 后台模式，按需在构建设置里开启即可。在该模式下，原生层会在后台线程

直接把数据回传 Unity，所以即便熄屏或切到后台，连接仍在、数据也能持续送达，无需额外做

前台服务来保活。

**事件驱动，好接入** —— 连接状态、设备发现、数据到达、信号强度（RSSI）变化，都通过一条

事件总线派发。只需订阅自己关心的事件，不用轮询，不用忙等。

**开箱即用的 GATT 服务层** —— 心率、骑行功率、踏频与速度、健身机、电量、设备信息……标准

服务都封装好了，解析逻辑直接可用；想加自己的服务，继承一个干净的基类就行。

**贴心的编辑器工具** —— 自带依赖校验窗口和构建设置面板，所有菜单收在

Tools/Jauuyoo/Bluetooth/ 下，不会和你的其它工具打架。没有真机时，也能在编辑器里模拟权限

流程，先把 UI 逻辑调通。

## 怎么装

Package Manager → + → Add package from disk → 选中包里的 package.json 即可。

## 几分钟跑起来

先告诉模块你的前后台状态和权限弹窗策略（实现 IBLEEnvironment），然后：

var center = new SampleBLEConnectCenter(environment);

bool ready = await center.InitializeBluetoothPluginsWithPermission();

if (!ready) return;

await center.StartDeviceScan(timeout: 10, isBackground: false);

就这么几行，扫描就启动了。包里还附带一个可以直接运行的完整演示场景（扫描 → 连接 →

服务发现 → 订阅通知 → 数据展示），以及五个外部依赖接口的最小实现——可以整段复制到项目里

当起点，省去从零搭建的麻烦。

💡 小提示：示例里的服务和特征值 ID 是留空的占位符，记得换成你目标设备的标准 GATT UUID，

再验证实际读写。

## 平台支持

| 平台        | 最低版本    | 说明                                                         |

|-------------|-------------|--------------------------------------------------------------|

| iOS         | 13.0        | 用途文案构建期自动注入；后台连接依赖 bluetooth-central        |

| Android     | API 21+     | 自动声明 BLE 权限；Android 12+ 已免除定位权限依赖             |

| macOS       | 10.13+      | 用途文案自动注入；随宿主 App 分发时由宿主签名流程统一重签     |

| Windows     | Win10 1809+ | 自研 x64 原生库，不依赖第三方库                               |

| OpenHarmony | arm64       | 权限与后台模式构建期注入                                      |

## 为什么鸿蒙对中国市场很关键

鸿蒙系统在国内设备的占比越来越高。如果你的应用需要蓝牙、又有面向中国市场发行（例如通过

团结引擎构建鸿蒙包、上架国内应用市场）的计划，那么由插件提供「鸿蒙端原生 BLE 支持」正好

能满足这个需求，而不必专门组建一支原生团队。你在 iOS、Android、macOS、Windows 上用的那套

统一 API，在鸿蒙端同样适用。

## 已知的限制

- Windows 只提供 x64（即 Win10/11 的 64 位）原生库，Win7/8 和 32 位系统用不了。

- OpenHarmony 原生库是 arm64 单架构（这也是鸿蒙平台的硬性要求）。

- Android 11 及以下的设备，按系统要求做 BLE 扫描需要定位权限；Android 12+ 已经没有这个依赖。

- iOS 息屏后连接能不能保住，取决于具体机型和系统的蓝牙省电策略——模块做了保活，但没法替

所有机型打保票。

- macOS 如果单独分发原生 bundle，需要自己走一遍公证；跟着宿主 App 分发的话，交给宿主的

签名流程。

- 示例里的服务和特征值 ID 是空占位，替换成你设备的标准 GATT UUID 即可。

## 需要帮忙？

遇到问题或想要新功能，随时来信：support@cheeryoo.com。来信时附上 Unity 版本、目标平台与

系统版本、包版本号和完整的 Console 日志，我们能更快帮你定位。

This asset uses Source Han Sans SC under the SIL Open Font License 1.1;

see the Third-Party Notices.txt file in the package for details.

> 💡 末尾这段第三方声明保留英文原文（这是规范要求的写法，不要翻译成中文版替换它）。

> 中文商店页如需中文说明，可在英文声明**前面**另起一行加「本资源使用思源黑体

> （SIL Open Font License 1.1），详见包内 Third-Party Notices.txt」，但英文原文必须保留。

---