208 lines
7.3 KiB
Markdown
208 lines
7.3 KiB
Markdown
# MeetingIM App 版本更新前后端对接文档
|
||
|
||
## 1. 适用范围
|
||
|
||
本文档用于 iOS、Android、Web 客户端检查新版本，以及执行推荐更新和强制更新。
|
||
|
||
- 版本策略为全局配置，存储在 `hotgo.im_app_releases`，不区分租户。
|
||
- iOS 安装包由 App Store 托管，客户端通过 `store_url` 跳转。
|
||
- Android APK 由发布人员上传到专用 OSS 发布目录，客户端通过 `package_url` 下载。
|
||
- Web 端没有安装包时，`store_url` 和 `package_url` 可以为空，使用 `update_type`、`min_supported_version` 和 `release_notes` 控制强刷、兼容提醒或维护提示。
|
||
- 客户端不直接访问数据库，也不自行拼接 OSS 地址。
|
||
|
||
## 2. 检查版本接口
|
||
|
||
```http
|
||
GET https://api.118im.com/v1/im/app/releases/latest
|
||
```
|
||
|
||
该接口允许未登录调用。
|
||
|
||
### 2.1 请求 Header
|
||
|
||
| Header | 必填 | 示例 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `X-IM-Schema` | 是 | `1` | MeetingIM HTTP 协议版本 |
|
||
| `X-Client-Platform` | 建议 | `ios` / `android` / `web` | 客户端平台 |
|
||
|
||
### 2.2 Query 参数
|
||
|
||
| 参数 | 必填 | 示例 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `apikey` | 是 | `AQAAAA...` | 应用 API Key |
|
||
| `platform` | 是 | `android` | 仅支持 `ios`、`android`、`web` |
|
||
| `current_version` | 是 | `1.2.0` | 当前版本，使用数字点分格式 |
|
||
| `channel` | 否 | `stable` | 发布渠道，默认 `stable` |
|
||
|
||
Android 请求示例：
|
||
|
||
```bash
|
||
curl -H 'X-IM-Schema: 1' \
|
||
-H 'X-Client-Platform: android' \
|
||
'https://api.118im.com/v1/im/app/releases/latest?apikey=AQAAAA...&platform=android¤t_version=1.2.0&channel=stable'
|
||
```
|
||
|
||
## 3. 成功响应
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": {
|
||
"platform": "android",
|
||
"channel": "stable",
|
||
"current_version": "1.2.0",
|
||
"latest_version": "1.3.0",
|
||
"min_supported_version": "1.1.0",
|
||
"has_update": true,
|
||
"force_update": false,
|
||
"update_type": "recommended",
|
||
"release_notes": "优化消息稳定性并修复已知问题。",
|
||
"store_url": "",
|
||
"package_url": "https://download.example.com/app-releases/android/stable/1.3.0/meetingim-1.3.0.apk",
|
||
"checksum": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
|
||
"remind_after_seconds": 86400,
|
||
"published_at": "2026-09-12T08:00:00Z"
|
||
},
|
||
"request_id": "req_xxx",
|
||
"server_time": "2026-09-12T08:10:00Z"
|
||
}
|
||
```
|
||
|
||
### 3.1 响应字段
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| `current_version` | string | 客户端传入的当前版本 |
|
||
| `latest_version` | string | 后台发布的最新版本 |
|
||
| `min_supported_version` | string | 最低可继续使用的版本 |
|
||
| `has_update` | boolean | 是否存在更高版本 |
|
||
| `force_update` | boolean | 是否必须完成更新后才能继续使用 |
|
||
| `update_type` | string | `none`、`recommended`、`force` |
|
||
| `release_notes` | string | 更新说明 |
|
||
| `store_url` | string | iOS App Store 地址 |
|
||
| `package_url` | string | Android APK 的 OSS/CDN HTTPS 下载地址 |
|
||
| `checksum` | string | Android APK 的 SHA-256，小写十六进制 |
|
||
| `remind_after_seconds` | number | 推荐更新关闭后再次提醒的间隔 |
|
||
| `published_at` | string | 发布时间，UTC RFC 3339 |
|
||
|
||
## 4. 更新判断规则
|
||
|
||
客户端以服务端返回结果为准，不自行重新计算强制更新规则。
|
||
|
||
| 条件 | 客户端行为 |
|
||
| --- | --- |
|
||
| `has_update=false` | 不弹更新窗口；手动检查时提示已是最新版本 |
|
||
| `has_update=true, force_update=false, update_type=recommended` | 弹推荐更新窗口，允许取消或稍后更新 |
|
||
| `has_update=true, force_update=true` | 弹强制更新窗口，不允许关闭，不允许进入主业务 |
|
||
| `update_type=none` | 不主动弹窗，可展示版本信息 |
|
||
|
||
当 `current_version < min_supported_version` 时，服务端无条件返回强制更新：
|
||
|
||
```json
|
||
{
|
||
"has_update": true,
|
||
"force_update": true,
|
||
"update_type": "force"
|
||
}
|
||
```
|
||
|
||
## 5. Android APK 与 OSS
|
||
|
||
### 5.1 OSS 对象路径
|
||
|
||
建议使用独立于聊天附件的发布目录：
|
||
|
||
```text
|
||
app-releases/android/{channel}/{version}/meetingim-{version}.apk
|
||
```
|
||
|
||
示例：
|
||
|
||
```text
|
||
app-releases/android/stable/1.3.0/meetingim-1.3.0.apk
|
||
```
|
||
|
||
### 5.2 下载地址要求
|
||
|
||
1. `package_url` 必须使用 HTTPS。
|
||
2. 地址必须长期稳定，至少覆盖该版本的完整支持周期。
|
||
3. 可以使用 OSS 公共读地址，或绑定 OSS/CDN 的固定下载域名。
|
||
4. 不得把有效期只有几分钟的 OSS 签名 URL 保存到版本表。
|
||
5. 如果 Bucket 必须私有，应提供固定公开下载接口，由接口实时生成签名并返回 302；版本表保存该固定接口地址。
|
||
6. APK 响应建议设置 `Content-Type: application/vnd.android.package-archive`。
|
||
7. 文件名、对象路径和 URL 必须包含版本号，禁止覆盖旧版本对象。
|
||
|
||
聊天附件接口 `/v0/file/s/{file_id}` 需要用户鉴权，不作为 Android 安装包的默认下载地址。
|
||
|
||
### 5.3 发布步骤
|
||
|
||
1. Android 构建正式签名 APK。
|
||
2. 计算 APK 的 SHA-256。
|
||
3. 上传到 OSS 的 `app-releases/android/{channel}/{version}/` 目录。
|
||
4. 使用浏览器或 `curl -I` 验证 HTTPS 地址可以下载。
|
||
5. 在 Admin 的“IM 全局版本更新”中编辑 Android 策略。
|
||
6. 填写最新版本、最低支持版本、更新类型、更新说明、`package_url` 和 SHA-256。
|
||
7. 保存后由 Kafka `app.release.updated` 事件通知 IM Server 清理缓存。
|
||
8. 使用旧版本号请求检查接口，确认下载地址、校验值和强更状态。
|
||
|
||
计算 SHA-256 示例：
|
||
|
||
```bash
|
||
shasum -a 256 meetingim-1.3.0.apk
|
||
```
|
||
|
||
## 6. Android 客户端处理
|
||
|
||
1. 调用版本检查接口。
|
||
2. `has_update=false` 时结束检查。
|
||
3. 根据 `force_update` 展示推荐更新或不可关闭的强更弹窗。
|
||
4. 使用系统下载组件请求 `package_url`，支持进度展示和失败重试。
|
||
5. 下载完成后计算本地文件 SHA-256，并与 `checksum` 比较。
|
||
6. 校验 APK 包名和签名证书必须与已安装应用一致。
|
||
7. 通过 Android `FileProvider` 发起安装，不使用 `file://` URI。
|
||
8. 未授予“安装未知应用”权限时，引导用户进入系统授权页。
|
||
9. 强更下载或安装失败时保留重试、网络设置和退出应用入口，不能绕过进入主业务。
|
||
|
||
客户端不得在 SHA-256 或应用签名校验失败后继续安装。
|
||
|
||
## 7. iOS 客户端处理
|
||
|
||
1. iOS 只读取 `store_url`，忽略 `package_url` 和 `checksum`。
|
||
2. `store_url` 必须是 `https://apps.apple.com/...` 地址。
|
||
3. 推荐更新允许取消；强制更新不得进入主业务。
|
||
4. 点击更新后使用系统能力打开 App Store。
|
||
|
||
## 8. 错误响应
|
||
|
||
缺少或错误的 `current_version`：
|
||
|
||
```json
|
||
{
|
||
"code": 30000,
|
||
"reason": "MALFORMED_REQUEST",
|
||
"message": "malformed request",
|
||
"details": {
|
||
"field": "current_version"
|
||
}
|
||
}
|
||
```
|
||
|
||
| HTTP 状态 | 原因 |
|
||
| --- | --- |
|
||
| 400 | 缺少 `X-IM-Schema: 1` |
|
||
| 400 | 缺少或错误的 `current_version` |
|
||
| 400 | `platform` 不是 `ios`、`android` 或 `web` |
|
||
| 500 | Admin 版本配置缺失、格式错误或内部配置接口不可用 |
|
||
|
||
## 9. 当前测试环境
|
||
|
||
```text
|
||
Base URL: https://api.118im.com
|
||
版本接口: /v1/im/app/releases/latest
|
||
API Key: AQAAAAABAAAoeOI7tA3HsYvdzDhYhZJy
|
||
协议版本: X-IM-Schema: 1
|
||
默认渠道: stable
|
||
```
|
||
|
||
当前测试库已配置 iOS、Android、Web `1.0.0` 默认策略。正式验证 Android 更新前，需要先上传测试 APK，并在 Admin 填写对应 `package_url` 与 SHA-256。
|