跳到主要内容

订阅用户在线状态

用户在线状态订阅是即时通讯服务端提供的回调服务，采用 Webhook 机制。您需要提前在控制台注册您的回调地址。注册完成后，即时通讯服务端会在每一次用户状态变更（上线、离线、登出）时，将用户状态变化事件实时通知您的服务器。

在应用中需要实时展示用户在线、离线状态时，可利用该 Webhook 返回的事件修改用户状态。如需直接查询某用户的在线状态，可以主动调用 Server API 接口查询用户在线状态。

开通服务​

使用用户在线状态订阅功能前，您需要为应用和当前环境的 App Key 开通服务。详见用户服务配置。

开通服务时，请配置可正常访问的回调接收地址。如果您的网络有 IP 访问限制，请务必配置 IP 白名单，否则无法正常接收服务端回调。

回调方法​

请求方法： POST

数据格式： application/json

即时通讯服务端会在 POST 请求 URL 中添加签名参数，您可通过签名验证调用者身份和数据有效性，详细参见 服务端回调签名。

回调正文参数​

该回调服务的 HTTP 请求正文数据格式为 application/json，包含具有以下结构的 JSON 对象：

参数类型说明
useridString用户 ID。
statusString用户状态变更事件。0 - 用户已上线。1 - 用户已离线。2：用户已登出。
osString操作系统：iOS、Android、HarmonyOS、Websocket、PC、MiniProgram（小程序），用户上线时同步。
timeLong发生时间。
clientIpString用户当前的 IP 地址及端口。
sessionIdString一个连接的唯一 ID。如果同一用户在多端同时在线，则会有多个连接，可使用此 ID 进行区分。

用户状态变更事件（status）参数说明：

  • 0 - 用户已上线，该事件表示客户端成功连接到即时通讯服务，即应用程序调用了 connect 方法，并连接成功。
  • 1 - 用户已离线，该事件表示客户端已经断开与即时通讯服务的连接，即应用程序调用了 disconnect 方法，或因异常情况断开连接。部分极端情况下，离线状态会延迟 5 分钟同步，例如应用程序连接了代理网络，应用异常断网，但此时代理服务与即时通讯服务的连接缓存仍然存在，这种情况下会导致用户离线事件延迟同步。
  • 2 - 用户已登出，该事件表示客户端已经注销登录状态，即应用程序主动调用了注销方法（logout）注销登录，注销登录后即时通讯服务不会为该用户触发远程推送通知。

用户已离线事件（1）默认还覆盖以下场景：

  • 多设备互踢场景：App 用户在 A 设备登录后，又在 B 设备上登录，B 将 A 踢下线后，用户在 A 设备的离线状态也会触发服务端同步用户已离线事件（1）。
  • 多平台登录场景：App 用户在不同平台登录，在任意平台上断开连接后会触发服务端同步用户已离线事件（1）。

重要

  • 回调正文中的 status 参数代表用户状态变更事件，其取值与 查询用户在线状态 API 接口返回结果中代表用户当前状态的 status 取值（在线或不在线）不同，请注意区分。
  • 部分早期开通订阅用户在线状态服务的客户可能发现同步行为与上述描述不一致。如有需要，请提交工单申请调整在线状态订阅-离线状态全通知开关状态。

回调请求示例​

假设您在开通服务页面配置的接收地址：http://example.com/online_status.php

HTTP
POST /online_status.php?appKey=someappKey&timestamp=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 分钟内同步此用户的在线状态回调。