接入流程

从零到完整接入，通常只需 2–3 个工作日。以下五步按顺序执行。

① 商务开通

联系晓葆商务，提供宿主小程序 AppID 完成审批，获取以下凭证（沙箱与生产各一套）：

② 小程序声明插件

在微信公众平台 → 设置 → 第三方设置 → 插件管理，添加晓葆检测插件，然后在 app.json 声明：

{
  "plugins": {
    "xiaobao-measure": {
      "version": "latest",
      "provider": "wx46730944cdee7d21"
    }
  }
}

③ 服务端实现签名接口

宿主服务端需对外暴露一个「跳转参数接口」，宿主前端调用后获取加密档案和签名， 再传给插件。详细算法见服务端实现，以下为接口规范：

请求（前端 → 宿主服务端）

POST /your-api/xiaobao/plugin-params
Content-Type: application/json

{
  "thirdUserId": "user_10086",
  "deviceKey": "HOME_MULTI_BIO_MONITOR",
  "measureMode": "BP"
}

响应（宿主服务端 → 前端）

{
  "code": 0,
  "data": {
    "appKey":      "your_app_key",
    "thirdUserId": "user_10086",
    "userProfile": "<base64(iv + ciphertext)>",
    "timestamp":   "1720000000",
    "nonce":       "a1b2c3d4e5f60011",
    "sign":        "<hmac-sha256-hex>",
    "deviceKey":   "HOME_MULTI_BIO_MONITOR",
    "measureMode": "BP"
  }
}

同时实现 Webhook 接收端（接收 plugin.report.ready 事件）， 详见 Webhook 事件。

④ 前端唤起插件

// pages/health/index.js
Page({
  async onStartMeasure() {
    const res = await this.fetchPluginParams({
      thirdUserId: this.data.userId,
      deviceKey: 'HOME_MULTI_BIO_MONITOR',
      measureMode: 'BP',
    })
    const p = res.data
    const query = [
      `appKey=${p.appKey}`,
      `thirdUserId=${encodeURIComponent(p.thirdUserId)}`,
      `userProfile=${encodeURIComponent(p.userProfile)}`,
      `timestamp=${p.timestamp}`,
      `nonce=${p.nonce}`,
      `sign=${p.sign}`,
      `deviceKey=${p.deviceKey}`,
      `measureMode=${p.measureMode}`,
      // 沙箱联调时取消注释：
      // 'env=sandbox',
    ].join('&')

    wx.navigateTo({ url: `plugin://xiaobao-measure/bind?${query}` })
  },

  // 插件返回后读取结果
  onShow() {
    const result = wx.getStorageSync('xiaobao_measure_result')
    if (!result) return
    wx.removeStorageSync('xiaobao_measure_result')  // 读一次后清除

    if (result.status === 'success') {
      console.log('检测成功，measureId:', result.measureId)
    } else if (result.status === 'cancel') {
      console.log('用户取消检测')
    } else {
      console.log('检测失败:', result.errorCode)
    }
  },
})

完整跳转参数说明（字段、是否纳入签名、各设备差异）见唤起插件。

⑤ 沙箱联调

不需要真实设备，通过 Mock 接口触发完整链路：

POST https://test-openapis.xiaobaotop.com/sandbox/mock/measure
Content-Type: application/json
X-App-Key: {sandbox_appKey}
X-Timestamp: {timestamp}
X-Nonce: {nonce}
X-Signature: {sign}

{
  "appKey": "{sandbox_appKey}",
  "thirdUserId": "test_user_001",
  "deviceKey": "HOME_MULTI_BIO_MONITOR",
  "measureMode": "BP"
}

调用后沙箱在 ≤1s 内向配置的 Webhook URL 推送 plugin.report.ready， 验证 Webhook 接收与业务写入是否正常。

联调自查清单

• appKey / appSecret / webhookSecret 已配置到服务端环境变量，未写入前端代码
• app.json 已声明晓葆插件 AppID
• 服务端签名使用管道符格式：HMAC_SHA256(appSecret, appKey + "|" + thirdUserId + "|" + timestamp + "|" + nonce)
• timestamp 为 10 位 Unix 秒，非毫秒
• 体脂秤（BCA）userProfile 中已包含 height / gender / birth_date
• 沙箱联调跳转参数含 env=sandbox；生产发布前已移除
• Webhook 已实现验签 + 幂等（X-Webhook-Id 去重）+ 10s 内响应
• 沙箱 Mock 检测可触发 Webhook 并正确写入业务数据