心健康测量SDK产品文档

Appearance

小阳心健康测量 Web SDK ​

安装 SDK ​

  • 安装

    bash
    npm install xiaoyang-health-measurement

  • 引用

    js
    import { Measurement, MeasurementCategory, FaceDetectorMarker } from 'xiaoyang-health-measurement'

初始化 ​

初始化测量对象以进行后续健康测量。

IMPORTANT

每次测量均需创建一个独立 Measurement 对象，对象内部包含单次测量完整过程数据，不可复用。

方法 ​

js
new Measurement({videoId:'', token:'', measurementUrl: '',  measurementDuration: 30000}, ...[categories])

参数说明 ​

名称类型必需示例值描述
videoIdstring是视频源ID（video标签）
tokenstring是测量服务令牌
measurementUrlstring否测量服务域名（用于私有化部署或调试）
measurementDurationnumber否30000测量时长（毫秒）
categoriesArray否MeasurementCategory.ANXIETY测量类型

  • token

    测量服务令牌(token)需要通过请求许可证(APP_ID/APP_KEY) 认证API获得。

    IMPORTANT

    为防止 SDK 许可证信息泄露，建议 Web SDK 用户将许可证认证操作部署在自身应用服务端，根据自身业务需要（如限制仅付费用户可访问）进行鉴权操作。

  • categories

    • 该参数指定本次测量关注的所有测量类型指标。
    • 默认提供“生理测量”和“情绪测量”两种预设类型。
    • 生理测量包括 心率报告(心率、心率变异率)、房颤报告（房颤）、血压报告（舒张压、收缩压）、血氧报告（血氧饱和度）、风险报告（心脏病风险、中风风险、心血管疾病风险、心脏压力、血管功能）、基础报告（性别、皮肤年龄、体重指数）、综合心健康风险报告（综合心健康风险）。
    • 情绪测量包含 心率报告（心率）、攻击性报告（攻击性）、焦虑度报告（焦虑度）、活力度报告（活力度）、抑郁度报告（抑郁度）、疲劳度报告（疲劳度）、压力度报告（压力度）、情绪综合分报告（情绪综合分）。
    • 如果预设类型不满足，您也可以根据MeasurementCategory类型传入关注的指标分类。

测量类型(SDK内部包含)定义如下：

ts
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

测量类型参数将受限于您所购许可证绑定的测量类型，这意味着该参数应为许可证所授权测量类型的子集。

示例代码 ​

js
videoId = "video elementId"
const token = "get token from your authorize api"
const measurement = new Measurement({videoId:videoId, token:token}, MeasurementCategory.ALL)
js
const token = "get token from your authorize api"
const measurement = new Measurement({videoId:videoId, token:token}, MeasurementCategory.PHYSIOLOGY)
js
const token = "get token from your authorize api"
const measurement = new Measurement({videoId:videoId, token:token}, MeasurementCategory.EMOTION)
js
const token = "get token from your authorize api"
//仅关注 “血氧/焦虑” 指标
const measurement = new Measurement({videoId:videoId, token:token}, MeasurementCategory.BLOODOXYGEN, MeasurementCategory.ANXIETY)

摄像头就绪 ​

调用start()后，SDK 会自动初始化摄像头，摄像头成功打开并准备就绪时会触发cameraStarted事件。此时可以更新 UI 状态（如隐藏加载遮罩、开始倒计时等）。

示例代码 ​

js
//监听摄像头就绪事件
measurement.addEventListener("cameraStarted", sender => {
    //隐藏加载遮罩，开始倒计时等
})

启动测量 ​

启动测量，成功会触发started事件并返回measurementId(本次测量唯一标识)，失败则会触发crashed事件。

测量要求参阅 健康测量条件及要求。

方法 ​

js
await measurement.start()

示例代码 ​

js
//监听启动测量事件
measurement.addEventListener("started", (sender,measurementId) => {
  console.log(measurementId)
})


await measurement.start()

采集数据 ​

测量成功开始后，程序自动从摄像头采集实时视频帧并提供给 SDK，帧率不能太低，建议15-30帧每秒。 数据采集过程中会定期触发captureProgressUpdated事件，如有必要此时可以更新采集进度，如进度条等。 数据采集满足条件后会触发collected事件，此时可以停止采集数据。

示例代码 ​

js
//监听采集进度事件
measurement.addEventListener("captureProgressUpdated", (sender, data) => {
    const { progress, elapsed, totalDuration, frameCount, requiredFrames } = data
    console.log(`采集进度: ${(progress * 100).toFixed(1)}%`)
})

//监听视频帧采集完成事件
measurement.addEventListener("collected", sender => {
    //停止采集视频帧
})

状态监测 ​

测量过程中 SDK 会自动检测数据质量（如人脸姿态、距离、晃动等）并通过stateUpdated事件发布，用户可以按需订阅此事件，以获得告警信息并处理。

示例代码 ​

js
//监听状态更新事件
measurement.addEventListener("stateUpdated", (sender, state) => {
    const { code, level, msg } = state
    console.log(code, level, msg)
})

IMPORTANT

未处理的告警累计可能会导致测量中断（触发crashed事件）。

订阅报告 ​

测量成功开始后，SDK 会在接收到足够数据的情况下请求测量服务生成健康报告。测量过程中会产生阶段性报告并通过chunkReportGenerated事件发布，测量结束后会产生完整健康报告并通过wholeReportGenerated事件发布。

用户可以按需订阅chunkReportGenerated和wholeReportGenerated事件以获得健康报告。

示例代码 ​

js
//监听阶段性报告
measurement.addEventListener("chunkReportGenerated", (sender,report) => {
  // hrbpm:心率 hrv:心率变异性
  const { hrbpm, hrv } = report
})

//监听完整报告
measurement.addEventListener("wholeReportGenerated", (sender,report) => {
  const {afReport, bpReport, essentialReport, healthScoreReport, hrReport, riskReport, spo2HReport, calculatedReport } = report 
})

报告解读 ​

请参见 健康报告解读。

中断测量 ​

在测量过程中可以随时终止测量。测量中断后会触发interrupted事件。

方法 ​

js
measurement.addEventListener("interrupted", sender => {
  //清理资源
})

await measurement.interrupt()

摄像头释放 ​

无论是正常完成测量，被手动interrupt中断，还是因为生命周期异常（crashed）结束，最终 SDK 均会释放所占用的设备摄像头资源，释放完成后将会触发cameraStopped事件。建议依赖此事件执行最终的 UI 清理或状态重置。

示例代码 ​

js
//监听摄像头释放事件
measurement.addEventListener("cameraStopped", sender => {
    //摄像头资源已释放，可返回上一页或显示总结信息等
})

异常处理 ​

启动测量后，任意环节出现异常均会通过crashed事件发布，用户可以按需订阅此事件，以获得错误信息并处理。

示例代码 ​

js
const handleCrash = (sender, exception) => {
  const { code, level, msg } = exception
  console.log(code, level, msg)
}

// 监听异常事件
measurement.addEventListener("crashed", handleCrash)

// 移除事件监听
measurement.removeEventListener("crashed", handleCrash)

示例程序 ​

参见示例项目。

Released under the MIT License.

Copyright © xymind.cn 2018