订阅用户在线状态
用户在线状态订阅是即时通讯服务端提供的回调服务,采用 Webhook 机制。您需要提前在控制台注册您的回调地址。注册完成后,即时通讯服务端会在每一次用户状态变更(上线、离线、登出)时,将用户状态变化事件实时通知您的服务器。
在应用中需要实时展示用户在线、离线状态时,可利用该 Webhook 返回的事件修改用户状态。如需直接查询某用户的在线状态,可以主动调用 Server API 接口查询用户在线状态。
开通服务
使用用户在线状态订阅功能前,您需要为应用和当前环境的 App Key 开通服务。详见用户服务配置。
开通服务时,请配置可正常访问的回调接收地址。如果您的网络有 IP 访问限制,请务必配置 IP 白名单,否则无法正常接收服务端回调。
回调方法
请求方法: POST
数据格式: application/json
即时通讯服务端会在 POST 请求 URL 中添加签名参数,您可通过签名验证调用者身份和数据有效性,详细参见 服务端回调签名。
回调正文参数
该回调服务的 HTTP 请求正文数据格式为 application/json
,包含具有以下结构的 JSON 对象:
参数 | 类型 | 说明 |
---|---|---|
userid | String | 用户 ID。 |
status | String | 用户状态变更事件。0 - 用户已上线。1 - 用户已离线。2 :用户已登出。 |
os | String | 操作系统:iOS、Android、Websocket、PC、MiniProgram(小程序),用户上线时同步。 |
time | long | 发生时间。 |
clientIp | String | 用户当前的 IP 地址及端口。 |
sessionId | String | 一个连接的唯一 ID。如果同一用户在多端同时在线,则会有多个连接,可使用此 ID 进行区分。 |
用户状态变更事件(status
)参数说明:
0
- 用户已上线,该事件表示客户端成功连接到即时通讯服务,即应用程序调用了connect
方法,并连接成功。1
- 用户已离线,该事件表示客户端已经断开与即时通讯服务的连接,即应用程序调用了disconnect
方法,或因异常情况断开连接。部分极端情况下,离线状态会延迟 5 分钟同步,例如应用程序连接了代理网络,应用异常断网,但此时代理服务与即时通讯服务的连接缓存仍然存在,这种情况下会导致用户离线事件延迟同步。2
- 用户已登出,该事件表示客户端已经注销登录状态,即应用程序主动调用了注销方法(logout
)注销登录,注销登录后即时通讯服务不会为该用户触发远程推送通知。
用户已离线事件(1
)默认还覆盖以下场景:
- 多设备互踢场景:App 用户在 A 设备登录后,又在 B 设备上登录,B 将 A 踢下线后,用户在 A 设备的离线状态也会触 发服务端同步用户已离线事件(
1
)。 - 多平台登录场景:App 用户在不同平台登录,在任意平台上断开连接后会触发服务端同步用户已离线事件(
1
)。
重要
回调请求示例
假设您在开通服务页面配置的接收地址:http://example.com/online_status.php
POST /online_status.php?appKey=someappKey×tamp=1408710653491&nonce=14314&signature=45beb7cc7307889a8e711219a47b7cf6a5b000e8 HTTP/1.1
Host: example.com
Content-Type: application/json
[
{
"userid": "apert60541",
"status": "1",
"os": "iOS",
"time": 1437982625625,
"clientIp":"172.20.10.94:41748",
"sessionId":"0O6Bvfvik_L9R_NxR6GqQb"
},
{
"userid": "apert60592",
"status": "1",
"os": "Android",
"time": 1437982625625,
"clientIp":"172.20.10.94:41748",
"sessionId":"0O9Fvfvik_L9R_NaR3GqYz"
},
{
"userid": "apert60533",
"status": "2",
"os": "Android",
"time": 1437982625625,
"clientIp":"172.20.10.94:41748",
"sessionId":"0O4Hvfvik_L3B_XaR7GxAf"
}
]
响应回调请求
提示
- 只要有 HTTP
200 OK
成功响应,服务端会认为状态已经同步。 - 如果应答超时 5 秒,服务端会再尝试推送 2 次,如果仍然失败,将不再同步此条状态。
- 如短时间内有大面积超时,将暂时停止请求您的服务器,1 分钟后会继续发送回调请求。异常断网情况下的会延迟 5 分钟同步。