4. 基础能力 API 4.1 APP 版本检查【基础探测通过，待数据联调】

Table of Contents

4.1 APP 版本检查【基础探测通过，待数据联调】

根据客户端当前构建号，判断指定渠道和平台是否存在更高的正式版本。

GET /tieup/api/v1/app/version-check

完整请求示例：

GET /tieup/api/v1/app/version-check?build=10001
X-App-Channel: main
X-App-Platform: android

兼容旧客户端的 Header 请求示例：

GET /tieup/api/v1/app/version-check
X-App-Channel: main
X-App-Platform: android
X-App-Build: 10001

请求参数：

位置 参数 类型 必填 说明
Query build integer 条件必填 当前 APP 正整数构建号；与 X-App-Build 至少传一个，同时传入时以本参数为准
Header X-App-Build integer 条件必填 兼容构建号请求头；未传 build 时读取本字段
Header X-App-Channel string 是 APP 渠道代码，必须对应启用渠道
Header X-App-Platform string 是 客户端平台，仅支持 ios、android，大小写不敏感

鉴权：公开接口，不需要 Authorization。接口不接收请求体。

完整响应示例：

{
  "code": 200,
  "message": "成功",
  "data": {
    "need_update": true,
    "force_update": false,
    "latest_version": "1.1.0",
    "download_url": "https://example.com/app"
  }
}

响应字段：

字段 类型 说明
need_update boolean 是否需要更新；当前构建号低于当前渠道、平台的最高正式构建号时为 true
force_update boolean 是否强制更新；仅 need_update=true 且最高正式版本配置为强制更新，或当前构建号低于其最低支持构建号时为 true
latest_version string 最高正式版本的展示版本号，对应 tieup_app_version.version_name；没有正式版本配置时返回空字符串
download_url string 最高正式版本的下载地址；没有正式版本配置或 iOS 版本未上传 IPA 时返回空字符串

判断规则：

  • 服务端按 channel_code + platform + release_status=2 查询 version_code 最大的正式版本，版本新旧只比较整数构建号，不比较展示版本字符串。
  • 当前构建号等于或高于最高正式构建号时，need_update=false、force_update=false；测试包或审核包构建号高于线上版本时不会被误判为需要更新。
  • 当前构建号低于最高正式构建号时，need_update=true；最高正式版本 update_type=2，或其 min_support_version_code>0 且当前构建号低于该值时，force_update=true。
  • 当前渠道、平台没有正式版本配置时，返回 need_update=false、force_update=false、latest_version=""、download_url=""，不阻断 APP 启动。
  • iOS 后台版本允许不上传 IPA，版本检查仍正常返回 need_update、force_update 和 latest_version，此时 download_url=""。iOS 客户端不能依赖该字段跳转 App Store，应使用客户端内置的 App Store 地址或 StoreKit 更新入口。
  • Android 版本必须由后台上传并经七牛回调确认 APK/AAB，正式版本需要更新时 download_url 返回已确认的安装包地址。
  • build 或 X-App-Build 缺失、为 0、负数、小数、非数字或超过 4294967295 时返回 422；渠道缺失、停用或不存在，以及平台不是 ios/android 时同样返回 422。
  • 测试状态：已完成代码实现和 PHP 语法检查，待 APP 使用真实渠道和版本配置联调。