小阳心健康测量 Web SDK
安装 SDK
安装
bashnpm install xy-health-measurement
引用
jsimport { Measurement, MeasurementCategory } from 'xy-health-measurement'
初始化
初始化测量对象以进行后续健康测量。
IMPORTANT
每次测量均需创建一个独立 Measurement
对象,对象内部包含单次测量完整过程数据,不可复用。
方法
new Measurement(token, categories)
参数说明
名称 | 类型 | 必需 | 示例值 | 描述 |
---|---|---|---|---|
token | string | 是 | 测量服务令牌 | |
categories | MeasurementCategory | 否 | MeasurementCategory.ANXIETY | 测量类型 |
token
测量服务令牌(
token
)需要通过请求许可证(APP_ID/APP_KEY
) 认证API获得。IMPORTANT
为防止 SDK 许可证信息泄露,建议 Web SDK 用户将许可证认证操作部署在自身应用服务端,根据自身业务需要(如限制仅付费用户可访问)进行鉴权操作。
categories
- 该参数指定本次测量关注的所有测量类型指标。
- 默认提供“生理测量”和“情绪测量”两种预设类型。
- 生理测量包括 心率报告(心率、心率变异率)、房颤报告(房颤)、血压报告(舒张压、收缩压)、血氧报告(血氧饱和度)、风险报告(心脏病风险、中风风险、心血管疾病风险、心脏压力、血管功能)、基础报告(性别、皮肤年龄、体重指数)、综合心健康风险报告(综合心健康风险)。
- 情绪测量包含 心率报告(心率)、攻击性报告(攻击性)、焦虑度报告(焦虑度)、活力度报告(活力度)、抑郁度报告(抑郁度)、疲劳度报告(疲劳度)、压力度报告(压力度)、情绪综合分报告(情绪综合分)。
- 如果预设类型不满足,您也可以根据
MeasurementCategory
类型传入关注的指标分类。
测量类型(SDK内部包含)定义如下:
enum MeasurementCategory {
//心率房颤
HEARTRATE = 1,
//血压
BLOODPRESSURE = 2,
//血氧
BLOODOXYGEN = 4,
//健康风险
RISK = 8,
//攻击性
AGGRESSIVITY = 16,
//焦虑度
ANXIETY = 32,
//压抑度[已废弃]
DEPRESSION = 64,
//活力度
VITALITY = 128,
//积极性[已废弃]
POSITIVITY = 256,
//抑郁度
SUPPRESSION = 512,
//疲劳度
FATIGUE = 1024,
//生理测量
PHYSIOLOGY = 15,
//情绪测量
EMOTION = 1713,
//全部指标
ALL = 1727
}
WARNING
测量类型参数将受限于您所购许可证绑定的测量类型,这意味着该参数应为许可证所授权测量类型的子集。
示例代码
const token = "get token from your authorize api"
const measurement = new Measurement(token, MeasurementCategory.ALL)
const token = "get token from your authorize api"
const measurement = new Measurement(token, MeasurementCategory.PHYSIOLOGY)
const token = "get token from your authorize api"
const measurement = new Measurement(token, MeasurementCategory.EMOTION)
const token = "get token from your authorize api"
//仅关注 “血氧/焦虑” 指标
const measurement = new Measurement(token, MeasurementCategory.BLOODOXYGEN, MeasurementCategory.ANXIETY)
启动测量
启动测量,成功会触发started
事件并返回measurementId
(本次测量唯一标识),失败则会触发crashed
事件。
测量要求参阅 健康测量条件及要求。
方法
measurement.start(frame)
参数说明
名称 | 类型 | 必需 | 描述 |
---|---|---|---|
frame | canvas | 是 | Dom元素 |
- 图像仅用于校验是否满足基本测量条件并匹配测量模型,测量服务不会保存用户数据。
- 图像中必须包含清晰人脸,人脸需要保持正脸,光线明亮均匀。
示例代码
//监听启动测量事件
measurement.addEventListener("started", (sender,measurementId) => {
console.log(measurementId)
})
measurement.start("base64_frame")
采集数据
测量成功开始后,用户需要从摄像头采集实时视频帧并提供给 SDK,视频帧需要保持连续,且帧率不能太低,建议15-30帧每秒。视频帧采集满足条件后会触发collected
事件,此时可以停止采集数据。
方法
measurement.enqueue({frame, timestamp})
参数说明
名称 | 类型 | 必需 | 描述 |
---|---|---|---|
frame | canvas | 是 | Dom元素 |
timestamp | number | 是 | 视频帧时间戳 |
frame
视频帧中必须包含清晰人脸,人脸需要保持正脸,光线明亮均匀。视频帧务必保持连续,切勿跳帧。
timestamp
拿到视频帧瞬间的时间戳,务必在获得视频帧的第一时间记录时间戳,切勿在操作视频帧后再记录时间戳。格式为
Unix 时间戳(精确到毫秒)
,使用Date.now()
获得即可。
示例代码
//监听视频帧采集完成事件
measurement.addEventListener("collected", sender => {
//停止采集视频帧
})
//入队视频帧
measurement.enqueue({"canvas", 1709151805475})
订阅报告
测量成功开始后,SDK 会在接收到足够数据的情况下请求测量服务生成健康报告。测量过程中会产生阶段性报告并通过chunkReportGenerated
事件发布,测量结束后会产生完整健康报告并通过wholeReportGenerated
事件发布。
用户可以按需订阅chunkReportGenerated
和wholeReportGenerated
事件以获得健康报告。
示例代码
//监听阶段性报告
measurement.addEventListener("chunkReportGenerated", (sender,report) => {
// hrBpm:心率 hrv:心率变异性
const { data:{hrBpm,hrv} } = report
})
//监听完整报告
measurement.addEventListener("wholeReportGenerated", (sender,report) => {
const {afReport, bpReport, essentialReport, healthScoreReport, hrReport, riskReport, spo2HReport, calculatedReport } = report
})
报告解读
请参见 健康报告解读。
中断测量
在测量过程中可以随时终止测量。测量终端后会触发interrupted
事件。
方法
measurement.addEventListener("interrupted", sender => {
//清理资源
})
measurement.interrupt()
异常处理
启动测量后,任意环节出现异常均会通过crashed
事件发布,用户可以按需订阅此事件,以获得错误信息并处理。
示例代码
//监听异常事件
measurement.addEventListener("crashed", (sender,exception) => {
const { errorMessage } = exception
console.log(errorMessage)
})
性能问题
测量过程中需要定时从摄像头获取视频帧数据,setInterval
在使用小间隔重复调用时可能存在性能问题,推荐使用更加高效的requestAnimationFrame
因为它由浏览器专门优化,更流畅同时减少性能消耗。
示例程序
NOTE
改版中,将于近期发布,敬请期待!