42 lines
No EOL
2.7 KiB
Markdown
42 lines
No EOL
2.7 KiB
Markdown
### 在线状态
|
||
|
||
每个用户都有在线状态信息的概念。该信息包含以下内容：
|
||
|
||
- 用户当前是否在线
|
||
- 用户最近一次活跃的时间（由服务器检测）
|
||
- 某客户端是否认为用户当前处于空闲状态
|
||
- 关于用户当前状态的任意信息（例如“正在开会”）
|
||
|
||
这些信息既包括设备级（`online`、`idle`、`last_active`），也包括用户级（status）数据，由用户的宿主服务器聚合后，通过 `m.presence` 事件传输。在线状态事件会发送给有房间成员关系的相关用户。
|
||
|
||
用户的在线状态通过 `presence` 键表示，该键枚举以下几种状态之一：
|
||
|
||
- `online` ：用户连接到事件流时的默认状态。
|
||
- `unavailable` ：此时用户不可达，例如用户处于空闲状态。
|
||
- `offline` ：用户未连接到事件流，或有意禁止发送其个人信息。
|
||
|
||
#### 事件
|
||
|
||
{{% event-group group_name="m.presence" %}}
|
||
|
||
#### 客户端行为
|
||
|
||
客户端可以通过下述 HTTP API 手动设置/获取自身的在线状态。
|
||
|
||
{{% http-api spec="client-server" api="presence" %}}
|
||
|
||
##### 距离上一次活跃时长
|
||
|
||
服务器会维护一次记录“最后一次检测到用户主动事件”的时间戳。主动事件可能是向房间发送消息，或将在线状态更改为 `online`。这个时间戳通过名为 `last_active_ago` 的键呈现，表示自上次主动事件以来的相对毫秒数。
|
||
|
||
为减少服务器向客户端发送的在线状态更新数量，当在线状态为 `online` 时，服务器可能会包含一个布尔字段 `currently_active`。如果该字段为 true，服务器将不会继续发送活跃时间的更新，直到向客户端发送的更新中 a) `currently_active` 变为 false，或 b) 状态变为非 `online`。在此期间，客户端应始终认为该用户处于活跃状态，而不考虑 `last_active_ago` 的具体值。
|
||
|
||
每当服务器向客户端推送在线状态事件时，最新的活跃时间必须是当前的。`currently_active` 机制仅用于服务器停止持续推送在线状态更新，而不应禁用活跃时间的追踪。因此，客户端可以通过显式请求某用户的在线状态来获取最新的活跃持续时长。
|
||
|
||
##### 空闲超时
|
||
|
||
如果用户的最后一次活跃时间超过了设定的阈值（比如 5 分钟），服务器会自动将用户状态设置为 `unavailable`。客户端也可以手动将用户状态设置为 `unavailable`。只要用户任意一个客户端有新的活动导致活跃时间刷新，服务器会自动将其在线状态设置为 `online`。
|
||
|
||
#### 安全性注意事项
|
||
|
||
在线状态信息会与所有目标用户的房间成员共享。在大型公共房间中，这种共享可能并不理想。 |