本页目录
Android：通过蓝牙连接（原生）
在 WebView 中运行 @onekeyfe/hd-common-connect-sdk，通过底层传输插件桥接到原生 BLE。以原生 Android 示例 和底层传输插件契约为起点。
原生层负责权限、配对、GATT 连接、特征读写和清理；SDK 负责协议探测、帧处理和签名。不要在原生桥中再实现一套 V1/V2 解码器。
权限
面向 Android 12 及以上版本的应用，需要在运行时请求 BLUETOOTH_SCAN 和 BLUETOOTH_CONNECT。仅扫描和连接的客户端不需要 BLUETOOTH_ADVERTISE。
只有应用不通过 BLE 扫描推断位置时，才能使用 neverForLocation。较旧的 Android 版本需要相应的旧版蓝牙和位置权限；不要在旧设备上无条件请求 Android 12 才提供的权限。按目标 SDK 和位置用途核对 Android 蓝牙权限指南 。
权限请求未完成前不要开始扫描。用户拒绝时，应向 JS 调用方返回权限失败结果，并允许用户之后主动重试。
构建并加载 JavaScript 包
在 hardware-js-sdk 仓库中运行：
cd packages/connect-examples/native-android-example/web
yarn
yarn build将 web_dist/ 复制到 app/src/main/assets/web_dist/。加载 file:///android_asset/web_dist/index.html 前，先注册原生桥接处理器。保持资源相对路径不变；具有设备桥接能力的 WebView 只加载应用自己可信的资源包。
演示包含所需依赖和完整桥接实现。以它的 package 和 Gradle 配置为起点，不要混用不同 Nordic BLE 版本的零散代码。
完成 BLE 连接后再返回成功
固定延迟不能证明配对、GATT 连接、服务发现或通知订阅已经成功。应等待回调或 BLE 库提供的异步完成接口：
- 完成所需配对，处理用户拒绝和超时。
- 等待 GATT 连接成功。
- 发现 OneKey 服务及所需的写入、通知特征。
- 启用通知，并等待描述符写入或订阅完成。
- 只有连接具备实际收发能力后，才完成桥接的
connect请求。
Android 通过 BluetoothGattCallback 返回操作结果。成功发起操作不等于操作已完成。为每个待处理操作设置超时；失败时关闭连接，并拒绝其待处理桥接请求。
| 用途 | UUID |
|---|---|
| 服务 | 00000001-0000-1000-8000-00805f9b34fb |
| 写入 | 00000002-0000-1000-8000-00805f9b34fb |
| 通知 | 00000003-0000-1000-8000-00805f9b34fb |
桥接契约
| 方法 | 完成条件 |
|---|---|
enumerate() | 返回去重后的候选设备快照；停止扫描，每个请求只完成一次。 |
connect(uuid) | 连接、特征及通知均已就绪。 |
send(uuid, data, options) | 校验十六进制数据，按顺序写入字节，遵守 withoutResponse，传回写入失败。 |
receive(uuid) | 返回队列中的下一个原始通知块，格式为十六进制；读者开始等待前收到的块也必须保留。 |
disconnect(uuid) | 取消订阅、关闭所选连接、拒绝待处理读取，并丢弃旧通知数据。 |
每条连接独立维护队列和回调。缺少特征时应返回失败，不能把可空写入当作成功。WebView 桥接回调应切换到所需的 UI 线程。
实现 Protocol V2 时，通过 getProtocolV2PacketCapacity 暴露真实的 BLE 写入容量，不要返回包含 ATT 开销的 MTU。完整接口见底层传输插件。
SDK 与 UI 生命周期
资源包用 env: 'lowlevel' 和你的插件初始化 SDK。检查初始化结果，发现连接后调用 getDeviceState(connectId) 读取种子生命周期内的 deviceId。
受保护调用前注册 UI 事件处理器。只回答输入请求，并转发其响应关联字段。REQUEST_BUTTON 和设备端 PIN 提示是通知；原生界面的“确定”按钮不能代替硬件确认。
标准钱包的地址和签名调用传 useEmptyPassphrase: true；隐藏钱包传入所选钱包的 passphraseState。同一设备的调用按顺序执行。
验证集成
在真机上覆盖权限拒绝、配对取消、发现失败、通知订阅失败、锁定设备输入、断连和重连。让用户在设备上确认地址，并检查 SDK 结果。仅发现 BLE 广播不代表端到端流程通过。
超时后不要自动重放签名或固件升级。参见断线与重连。