氦闪中台文档

# 用户版本上报

# 目录

# 接口说明

本接口用于客户端上报「用户当前使用的版本信息」，服务端按「用户 + 平台 + 设备」维度幂等保存，用于版本覆盖率、活跃版本、升级情况等统计分析。

# 接口介绍

该接口面向需要统计版本分布的应用场景。客户端在启动或登录后调用本接口，将当前版本号、数字版本号、设备信息、下载渠道、网络类型等上报至平台：

  • 平台可按版本维度统计用户数与设备数，分析版本覆盖率与升级进度（可在开发者平台「版本管理模块 - 用户版本信息」页面查看，支持圆形统计图展示各版本占比）；

幂等规则：同一 userId + platform + deviceId 只保留一条记录，重复上报时更新该记录（不会产生重复数据）；未传 deviceId 时按 userId + platform 维度判定。

# 接口配置入口

  • 登录氦闪 开发者平台 (opens new window)
  • "接口管理" 》 "平台接口" 》 "模块API" 》 "版本管理模块"
  • 选择 "用户版本上报"
  • 右上角选择开启

提示：此接口数据持久化使用 MongoDB 数据库，请确保已配置相关数据源。 多租户数据源按请求头 APPID 自动切换，请求体无需传 appid。

# 接口调用

# 用户版本上报

  • 接口地址：https://lb/business-service/hiasoon-versionmanagercenter/open/report
  • 返回格式：json
  • 请求方式：POST
  • 请求示例：
{
  "userId": "UID202604160001",
  "platform": "ANDROID",
  "versionNumber": "2.1.0",
  "versionCode": 20100,
  "versionid": "6650f2b8c1a2b3d4e5f60718",
  "deviceId": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "deviceName": "Xiaomi 14",
  "deviceType": "PHONE",
  "osVersion": "Android 14",
  "channel": "HuaweiStore",
  "networkType": "WIFI"
}

# 请求头：

参数名称 类型 说明 是否必填
APPID string 开发者平台分配的应用APPID 是
_t number 请求时间戳（毫秒级） 是
_s string 签名信息，用于接口安全验证 是
_n string 随机数 是
Authorization string Bearer {token}，访问令牌（本接口必须登录） 是

注意：本接口需要登录态，必须携带有效的 Authorization 请求头。

# 请求体（json）：

参数名称 类型 说明 是否必填
userId string 用户唯一标识（用户ID） 是
platform string 平台类型：WEB/ANDROID/IOS/WINDOWS/MACOS/LINUX/SDK/PLUGIN 是
versionNumber string 版本号，格式 x.x.x 或 v.x.x.x，如 2.1.0 否 ※
versionCode number 数字版本号，如 20100 否 ※
versionid string 版本ID（开发者平台的版本记录主键，可选，便于精确关联版本） 否
deviceId string 设备唯一标识（IDFA/OAID/设备指纹哈希等） 否
deviceName string 设备名称/型号，如 Xiaomi 14、iPhone 15 Pro 否
deviceType string 设备类型：PHONE/TABLET/PC/WEB/UNKNOWN 否
osVersion string 操作系统版本，如 Android 14、iOS 17.5 否
channel string 下载渠道，如 AppStore、HuaweiStore、OfficialSite 否
networkType string 网络类型：WIFI/4G/5G/UNKNOWN 否

※ 说明：versionNumber 与 versionCode 至少填写一个，两者都为空时接口返回「版本号(versionNumber)或数字版本号(versionCode)不能为空」。

# 响应头：

参数名称 类型 说明 是否必填
connectionid string 本次请求的唯一标识 是
_t number 响应时间戳（毫秒级） 是
_s string 响应签名信息，用于防篡改校验 是
_n string 随机数（与本次请求的值一致） 是

# 返回参数（json）

参数名称 类型 说明
code number 返回状态码，200 表示成功，其他表示失败
message string 返回信息描述（成功时为「版本信息上报成功」）
data string 上报记录的 MongoDB 主键 ID
info object 附加信息，一般为 null

返回参数示例：

{
  "code": 200,
  "message": "版本信息上报成功",
  "data": "6650f2b9c1a2b3d4e5f60719",
  "info": null
}

失败示例（缺少必填参数）：

{
  "code": 18000,
  "message": "业务处理失败:平台类型不能为空",
  "data": null,
  "info": null
}

← 检查更新 →