SDK 文档

服务端 API

状态变更回调

最近更新时间:2020-07-29 09:55:38

功能说明

App 后台可以通过该回调实时监控用户上、下线的行为,包括:

  • 用户上线(TCP 连接建立)
  • 用户注销下线或者用户网络断开(TCP 连接断开)
  • App 心跳超时(App 异常被 kill 或者 Crash)

注意事项

  • 要启用回调,必须配置回调 URL,并打开本回调对应的开关,配置方法详见 第三方回调配置 文档。
  • 回调的方向是即时通信 IM 后台向 App 后台发起 HTTP POST 请求。
  • App 后台在收到回调请求之后,务必校验请求 URL 中的参数 SDKAppID 是否是自己的 SDKAppID。
  • 其他安全相关事宜请参考 第三方回调简介:安全考虑 文档。

可能触发该回调的场景

  • 用户通过客户端发起登录的上线请求。
  • 用户通过客户端发起登出的下线请求。
  • 用户主动 kill 客户端进程,或者切后台后进程被手机操作系统 kill 掉,或者 crash 导致进程异常退出,云服务器检测到客户端网络断开后触发网络断开回调。
  • 客户端心跳超时,如关闭网络,或网络完全不可用,云服务器检测到客户端的心跳超时触发连接断开回调。心跳超时时间为 400 秒。

回调的实时性

Android/iOS/PC

对于绝大多数情况,用户状态的变化都能实时感知,从而实时地触发回调。例如:

  • 用户主动登录,触发Login + Register回调。
  • 用户主动登出,触发Logout + Unregister回调。
  • 用户主动 kill 客户端进程,或者用户切后台后,客户端进程被手机操作系统 kill 掉,触发Disconnect + LinkClose回调。

只有以下一种特殊情况,IM 云服务器需要等待400秒的心跳超时时间才能感知状态变更:
当网络完全不可用时,客户端连 TCP 协议层的 FIN 包或 RST 包都无法发出时,IM 云服务器需要等待 400 秒的心跳超时时间才能触发 Disconnect + TimeOut 回调。常见的场景有用户主动关闭客户端的网络(例如开启手机的飞行模式),或者进入完全没有网络信号的隧道。

Web

用户主动登录 Web 端时,IM 云服务器可以实时感知,实时触发回调。
用户网络不可用,或者直接关闭 Web 页面时,IM 云服务器需要等待400秒的心跳超时时间才能触发回调。

接口说明

请求 URL 示例

以下示例中 App 配置的回调 URL 为 https://www.example.com
示例:

https://www.example.com?SdkAppid=$SDKAppID&CallbackCommand=$CallbackCommand&contenttype=json&ClientIP=$ClientIP&OptPlatform=$OptPlatform

请求参数说明

参数 说明
https 请求协议为 HTTPS,请求方式为 POST
www.example.com 回调 URL
SdkAppid 创建应用时在即时通信 IM 控制台分配的 SDKAppID
CallbackCommand 固定为:State.StateChange
contenttype 固定值为 JSON
ClientIP 客户端 IP,格式如:127.0.0.1
OptPlatform 客户端平台,取值参见 第三方回调简介:回调协议 中 OptPlatform 的参数含义

请求包示例

{
    "CallbackCommand": "State.StateChange",
    "Info": {
        "Action": "Logout",
        "To_Account": "testuser316",
        "Reason": "Unregister"
    }
}

请求包字段说明

字段 类型 说明
CallbackCommand String 回调命令
Info Object 用户上下线的信息
Action String 用户上线或者下线的动作,Login 表示上线(TCP 建立),Logout 表示下线(TCP 断开),Disconnect 表示网络断开(TCP 断开)
To_Account String 用户 UserID
Reason String 用户上下线触发的原因:
  • Login 的原因有 Register:App TCP 连接建立
  • Logout 的原因有 Unregister:App 用户注销帐号导致 TCP 断开
  • Disconnect 的原因有 LinkClose:即时通信 IM 检测到 App TCP 连接断开(例如 kill App,客户端发出 TCP 的 FIN 包或 RST 包);TimeOut:即时通信 IM 检测到 App 心跳包超时,认为 TCP 已断开(例如客户端网络异常断开,未发出 TCP 的 FIN 包或 RST 包,也无法发送心跳包)。心跳超时时间为400秒
  • 各种具体场景触发的回调 Reason 请参考 可能触发该回调的场景
  • 如果用户的上线请求和下线请求同时到来,此时只会触发 Logout + Unregister 回调,不会触发 Login + Register 回调

应答包示例

{
    "ActionStatus": "OK",
    "ErrorCode": 0,
    "ErrorInfo": ""
}

应答包字段说明

字段 类型 属性 说明
ActionStatus String 必填 请求处理的结果,OK 表示处理成功,FAIL 表示失败
ErrorCode Integer 必填 错误码,0表示 App 后台处理成功,1表示 App 后台处理失败
ErrorInfo String 必填 错误信息

参考

目录