180 lines
4.0 KiB
Markdown
180 lines
4.0 KiB
Markdown
# Flutter 心跳接口对接
|
||
|
||
## 1. APP 心跳
|
||
|
||
### 接口地址
|
||
|
||
```http
|
||
POST /api/v1/app/heartbeat
|
||
Authorization: Bearer <access_token>
|
||
```
|
||
|
||
### 参数
|
||
|
||
Body 不需要传参数。
|
||
|
||
Header：
|
||
|
||
| 字段 | 必填 | 说明 |
|
||
| --- | --- | --- |
|
||
| `Authorization` | 是 | 登录 token。 |
|
||
| `X-Device-ID` | 否 | 设备 ID；有就传，服务端只做会话审计。 |
|
||
|
||
### 返回值
|
||
|
||
```json
|
||
{
|
||
"code": "OK",
|
||
"message": "ok",
|
||
"request_id": "req_xxx",
|
||
"data": {
|
||
"accepted": true,
|
||
"heartbeat_at_ms": 1778000005000,
|
||
"server_time_ms": 1778000005000
|
||
}
|
||
}
|
||
```
|
||
|
||
| 字段 | 说明 |
|
||
| --- | --- |
|
||
| `data.accepted` | 是否接受本次 APP 心跳。 |
|
||
| `data.heartbeat_at_ms` | 本次 APP 心跳写入时间，UTC epoch milliseconds。 |
|
||
| `data.server_time_ms` | 服务端时间，UTC epoch milliseconds。 |
|
||
|
||
相关 IM：无。
|
||
|
||
## 2. 房间心跳
|
||
|
||
### 接口地址
|
||
|
||
```http
|
||
POST /api/v1/rooms/heartbeat
|
||
Authorization: Bearer <access_token>
|
||
Content-Type: application/json
|
||
```
|
||
|
||
### 参数
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `room_id` | string | 是 | 房间 ID。 |
|
||
| `command_id` | string | 是 | 本次心跳命令 ID。同一次请求重试复用同一个值，下一次心跳换新的值。 |
|
||
|
||
请求示例：
|
||
|
||
```json
|
||
{
|
||
"room_id": "lalu_xxx",
|
||
"command_id": "cmd_room_heartbeat_lalu_xxx_123_001"
|
||
}
|
||
```
|
||
|
||
### 返回值
|
||
|
||
```json
|
||
{
|
||
"code": "OK",
|
||
"message": "ok",
|
||
"request_id": "req_xxx",
|
||
"data": {
|
||
"result": {
|
||
"applied": true,
|
||
"room_version": 18,
|
||
"server_time_ms": 1778000005000
|
||
},
|
||
"user": {
|
||
"user_id": 123,
|
||
"role": "audience",
|
||
"joined_at_ms": 1778000000000,
|
||
"last_seen_at_ms": 1778000005000
|
||
},
|
||
"room": {
|
||
"room_id": "lalu_xxx",
|
||
"version": 18,
|
||
"online_users": []
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
| 字段 | 说明 |
|
||
| --- | --- |
|
||
| `data.result.applied` | 本次心跳是否写入成功。 |
|
||
| `data.result.room_version` | 房间版本。 |
|
||
| `data.user.last_seen_at_ms` | 当前用户房间 presence 最近刷新时间。 |
|
||
| `data.room` | 刷新后的房间快照。 |
|
||
|
||
相关 IM：无。房间心跳只刷新 room-service presence，不会广播独立 IM。
|
||
|
||
## 3. 麦位心跳
|
||
|
||
### 接口地址
|
||
|
||
```http
|
||
POST /api/v1/rooms/mic/heartbeat
|
||
Authorization: Bearer <access_token>
|
||
Content-Type: application/json
|
||
```
|
||
|
||
### 参数
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `room_id` | string | 是 | 房间 ID。 |
|
||
| `command_id` | string | 是 | 本次麦位心跳命令 ID。同一次请求重试复用同一个值，下一次心跳换新的值。 |
|
||
| `mic_session_id` | string | 是 | 当前麦位会话 ID，必须使用上麦返回的 `mic_session_id`。 |
|
||
| `target_user_id` | int64 | 否 | 传 `0` 或不传表示当前登录用户自己。 |
|
||
|
||
请求示例：
|
||
|
||
```json
|
||
{
|
||
"room_id": "lalu_xxx",
|
||
"command_id": "cmd_mic_heartbeat_lalu_xxx_123_001",
|
||
"mic_session_id": "mic_xxx",
|
||
"target_user_id": 0
|
||
}
|
||
```
|
||
|
||
### 返回值
|
||
|
||
```json
|
||
{
|
||
"code": "OK",
|
||
"message": "ok",
|
||
"request_id": "req_xxx",
|
||
"data": {
|
||
"result": {
|
||
"applied": true,
|
||
"room_version": 18,
|
||
"server_time_ms": 1778000005000
|
||
},
|
||
"seat_no": 1,
|
||
"mic_heartbeat_at_ms": 1778000005000,
|
||
"room": {
|
||
"room_id": "lalu_xxx",
|
||
"version": 18,
|
||
"mic_seats": [
|
||
{
|
||
"seat_no": 1,
|
||
"user_id": 123,
|
||
"publish_state": "publishing",
|
||
"mic_session_id": "mic_xxx",
|
||
"mic_heartbeat_at_ms": 1778000005000
|
||
}
|
||
]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
| 字段 | 说明 |
|
||
| --- | --- |
|
||
| `data.seat_no` | 当前用户所在麦位。 |
|
||
| `data.mic_heartbeat_at_ms` | 服务端接受本次麦位心跳的时间，UTC epoch milliseconds。 |
|
||
| `data.room` | 刷新后的房间快照。 |
|
||
| `data.room.mic_seats[].mic_heartbeat_at_ms` | 麦位最近一次服务端接受心跳的时间。 |
|
||
| `data.room.mic_seats[].publish_state` | `publishing` 表示当前会话已确认发流，可以继续麦位心跳。 |
|
||
|
||
相关 IM：无独立心跳 IM。收到 `room_mic_down` 后停止麦位心跳。
|