89 lines
2.8 KiB
Markdown
89 lines
2.8 KiB
Markdown
# Flutter 麦上心跳接口
|
||
|
||
## 地址
|
||
|
||
```http
|
||
POST /api/v1/rooms/mic/heartbeat
|
||
Authorization: Bearer <access_token>
|
||
Content-Type: application/json
|
||
```
|
||
|
||
## 参数
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `room_id` | string | 是 | 房间 ID。 |
|
||
| `command_id` | string | 是 | 本次心跳命令 ID。同一次请求重试复用同一个值，下一次心跳换新的值。 |
|
||
| `target_user_id` | int64 | 否 | 传 `0` 或不传表示当前登录用户自己。 |
|
||
| `mic_session_id` | string | 是 | 当前麦位会话 ID，必须使用上麦返回的 `mic_session_id`。 |
|
||
|
||
请求示例：
|
||
|
||
```json
|
||
{
|
||
"room_id": "lalu_xxx",
|
||
"command_id": "cmd_mic_heartbeat_lalu_xxx_123_001",
|
||
"target_user_id": 0,
|
||
"mic_session_id": "mic_xxx"
|
||
}
|
||
```
|
||
|
||
## 返回值
|
||
|
||
```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,
|
||
"seat_status": "publishing"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
| 字段 | 说明 |
|
||
| --- | --- |
|
||
| `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` 表示当前会话已确认发流，可以继续心跳。 |
|
||
| `data.room.mic_seats[].seat_status` | 展示状态，常见值为 `publishing`、`muted`、`occupied`、`empty`、`locked`。 |
|
||
|
||
## 相关 IM
|
||
|
||
| IM | 是否新增 | 说明 |
|
||
| --- | --- | --- |
|
||
| 无 | 否 | 麦上心跳不广播独立 IM。 |
|
||
| `room_mic_publish_confirmed` | 已有 | 发流确认成功后进入 `publishing`，Flutter 收到后可以开始麦上心跳。 |
|
||
| `room_mic_down` | 已有 | 用户下麦、离房、被踢、发流超时或 RTC 停止后释放麦位，Flutter 收到后停止麦上心跳。 |
|
||
|
||
## Flutter 调用规则
|
||
|
||
1. `POST /api/v1/rooms/mic/up` 成功后保存 `mic_session_id`。
|
||
2. RTC 发流成功后调用 `POST /api/v1/rooms/mic/publishing/confirm`。
|
||
3. 确认成功且当前麦位 `publish_state=publishing` 后，周期调用 `POST /api/v1/rooms/mic/heartbeat`。
|
||
4. `pending_publish` 状态不能调用麦上心跳开始计时。
|
||
5. 返回 `mic session mismatch` 时，本地保存的是旧 `mic_session_id`，需要刷新房间详情。
|
||
6. 收到 `room_mic_down` 或接口返回用户不在麦上时，停止本地麦上心跳。
|