更新记录

1.0.0（2026-08-20）

• 首发：基于 star-link-ring-sdk（CRPBle AAR）封装 Android 端
• 首发：基于 Manridy 微信小程序插件封装 MP-WEIXIN 端
• 统一 API：扫描、连接、电量、步数、睡眠、心率、血氧、用户信息、时间同步

平台兼容性

uni-app(5.0)

uni-app x(5.0)

Manridy 智能戒指 SDK（UTS）

智能戒指 BLE 能力的 UniApp / uni-app x 插件。统一封装 App-Android 与 微信小程序，提供扫描连接、电量、步数、睡眠、心率、血氧等常用接口。

• 插件类型：UTS
• 最低 HBuilderX：3.6.8+
• Vue2 / Vue3：均支持

功能列表

• 蓝牙扫描、连接、断开
• 时间同步、用户信息下发
• 电量 / 固件版本查询
• 今日步数（距离、卡路里）
• 睡眠数据查询
• 心率测量（开始 / 停止）
• 血氧测量（开始 / 停止）
• 统一事件回调：连接态、电量、步数、睡眠、心率、血氧、原始数据

安装

方式一：插件市场

在 HBuilderX 中从插件市场导入本插件到项目 uni_modules。

方式二：手动拷贝

将 ajun-manridy-sdk 目录放到工程：

你的项目/
└─ uni_modules/
   └─ ajun-manridy-sdk/

权限说明（必读）

一、Android 清单权限

插件已内置权限声明，云打包一般会自动合并。若自定义权限或离线打包，请在 manifest.json → app-plus → distribute → android → permissions 中配置：

[
  "<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\"/>",
  "<uses-permission android:name=\"android.permission.INTERNET\"/>",
  "<uses-permission android:name=\"android.permission.ACCESS_NETWORK_STATE\"/>",
  "<uses-permission android:name=\"android.permission.BLUETOOTH_SCAN\"/>",
  "<uses-permission android:name=\"android.permission.BLUETOOTH_CONNECT\"/>"
]

原生 AndroidManifest.xml 等价写法：

<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" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission
  android:name="android.permission.BLUETOOTH_SCAN"
  android:usesPermissionFlags="neverForLocation" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />

<uses-feature
  android:name="android.hardware.bluetooth_le"
  android:required="true" />

可选（仅 OTA / 读写固件文件时需要）：

[
  "<uses-permission android:name=\"android.permission.READ_EXTERNAL_STORAGE\"/>",
  "<uses-permission android:name=\"android.permission.WRITE_EXTERNAL_STORAGE\"/>",
  "<uses-permission android:name=\"android.permission.FOREGROUND_SERVICE\"/>"
]

二、Android 运行时动态权限

扫描前必须动态申请，并引导用户打开系统蓝牙；Android 6–11 还需打开定位服务。

function requestRingPermissions() {
  return new Promise((resolve, reject) => {
    // #ifdef APP-PLUS
    const permissions = [
      'android.permission.ACCESS_FINE_LOCATION',
      'android.permission.ACCESS_COARSE_LOCATION',
      'android.permission.BLUETOOTH_SCAN',
      'android.permission.BLUETOOTH_CONNECT'
    ]
    plus.android.requestPermissions(
      permissions,
      (result) => {
        const denied = (result.deniedAlways || []).concat(result.deniedPresent || [])
        if (denied.length) {
          reject(new Error('权限被拒绝: ' + denied.join(',')))
          return
        }
        resolve(result)
      },
      (err) => reject(err)
    )
    // #endif
    // #ifndef APP-PLUS
    resolve()
    // #endif
  })
}

三、微信小程序权限与插件

1. 在微信公众平台为当前小程序申请使用插件：

插件 AppID（provider）：wxfedd2dfd173a9f40
插件名称：Manridy
版本：1.0.8

2. 在 manifest.json → 微信小程序配置 → 插件配置：

{
  "Manridy": {
    "version": "1.0.8",
    "provider": "wxfedd2dfd173a9f40"
  }
}

3. 小程序需开通：蓝牙、位置（用于 BLE 扫描，部分安卓机型依赖定位服务）。

四、隐私与数据说明

• 本插件不含广告
• 本插件不采集、不上报用户数据
• 蓝牙数据仅在手机与戒指之间本地传输

快速使用

1. 引入

import {
  init,
  startScan,
  stopScan,
  connect,
  disconnect,
  onDeviceFound,
  onConnectionStateChange,
  onBatteryChange,
  onStepsChange,
  onSleepChange,
  onHeartRateChange,
  onBloodOxygenChange,
  onData,
  syncTime,
  queryBattery,
  queryFirmwareVersion,
  queryCurrentSteps,
  queryHistorySleep,
  startMeasureHeartRate,
  stopMeasureHeartRate,
  startMeasureBloodOxygen,
  stopMeasureBloodOxygen,
  sendUserInfo
} from '@/uni_modules/ajun-manridy-sdk'

2. 推荐调用顺序

init()
  → 申请权限 / 打开蓝牙（及定位服务）
  → 注册 onXxx 回调
  → startScan()
  → connect({ deviceId })
  → syncTime() / sendUserInfo()
  → queryXxx() / startMeasureXxx()

3. 完整示例

init()

onDeviceFound((device) => {
  console.log('发现设备', device.name, device.deviceId, device.rssi)
})

onConnectionStateChange((res) => {
  // res.state: connecting | connected | disconnected | disconnecting
  console.log('连接状态', res.state, res.code)
})

onBatteryChange((res) => {
  console.log('电量', res.battery)
})

onStepsChange((res) => {
  console.log('步数', res.steps, res.distance, res.calories)
})

onSleepChange((res) => {
  console.log('睡眠', res.totalTime, res.deepTime, res.lightTime)
})

onHeartRateChange((res) => {
  console.log('心率', res.heartRate)
})

onBloodOxygenChange((res) => {
  console.log('血氧', res.bloodOxygen)
})

onData((res) => {
  // Android：原生事件透传；微信：含 command 的业务解析包
  console.log('原始事件', res)
})

// App 端请先 await requestRingPermissions()
startScan({
  timeout: 10000,
  success() {},
  fail(err) {
    console.error(err)
  }
})

// 用户从列表选择设备后
connect({
  deviceId: 'XX:XX:XX:XX:XX:XX',
  success() {
    syncTime()
    sendUserInfo({
      height: 170,
      weight: 65,
      gender: 1, // 0 女 / 1 男
      age: 28,
      stepLength: 70
    })
    queryBattery()
    queryCurrentSteps()
  },
  fail(err) {
    console.error(err)
  }
})

API 说明

方法

sendUserInfo 字段

事件回调

健康类接口请先注册对应 onXxx，再调用 query / measure。

混淆配置（Android 发行包）

-keep class com.crrepa.ble.** { *; }
-dontwarn com.crrepa.ble.**

注意事项

1. 必须真机调试：模拟器无法完成 BLE 扫描与连接。
2. 先权限后扫描：未授权或未开定位服务时，Android 常见现象是“扫不到设备”。
3. 先监听后查询：queryBattery、queryCurrentSteps、测量类接口的结果通过 onXxx 回调返回。
4. 两端底层不同：Android 走 CRPBle；微信走厂商插件 Manridy。统一 API 已对齐常用能力，部分指令细节以各端固件为准。
5. 微信插件授权：未在公众平台申请 Manridy 插件时，小程序端无法 requirePlugin。
6. 断开重连：Android 建议 disconnect 后稍候再 connect，提高成功率。
7. 不支持 iOS / H5：当前版本仅 Android App 与微信小程序。
8. 进阶能力：OTA、SOS、遥控、消息推送等可在 Android 侧按 CRPBle 继续扩展（后续版本逐步开放）。

常见问题

Q：扫描列表一直为空？
A：检查蓝牙开关、定位权限、定位服务；Android 12+ 检查 BLUETOOTH_SCAN / BLUETOOTH_CONNECT；尽量靠近设备并摘下戒指充电座。

Q：已连接但无心率/步数回调？
A：确认已先 onHeartRateChange / onStepsChange，再调用测量或查询接口。

Q：微信端报找不到插件？
A：确认 manifest.json 已配置 plugins，且小程序 AppID 已通过厂商插件授权。

Q：云打包后崩溃 / 找不到类？
A：确认发行包已配置 ProGuard keep；确认插件 libs 内 AAR 已随插件提交。

兼容性

版本

详见 changelog.md

反馈

使用中如遇问题，请提供：系统版本、机型、戒指型号/固件版本、复现步骤与日志，便于排查。