状态变更回调

最近更新时间:2019-05-09 11:15:35

功能说明

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

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

注意事项

  • 要启用回调,必须配置回调 URL,并打开本回调对应的开关,配置方法详见 第三方回调配置 文档。
  • 回调的方向是云通信后台向 App 后台发起 HTTP POST 请求。
  • App 后台在收到回调请求之后,务必校验请求 URL 中的参数 SdkAppid 是否是自己的 SdkAppid。
  • 其他安全相关事宜请参考 第三方回调简介:安全考虑 文档。
  • 可能会有大量的心跳超时包(Crash、kill 后台等),业务需注意回调响应服务器性能。

可能触发该回调的场景

  • 用户通过客户端发起上线请求。
  • 用户通过客户端发起退出的下线请求。
  • 客户端 kill 后台进程,云服务器检测到客户端网络断开后触发下线回调。
  • 客户端心跳超时,包括客户端 Crash、关闭网络 400 秒后,云服务器检测到客户端的心跳超时触发下线回调。

回调发生时机

IM 云服务器收到客户端的 TCP 连接建立、TCP 连接断开、若干心跳包无法收到后发生。

接口说明

请求 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 创建应用时在云通信控制台分配的 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 App 上线或者下线的动作, Login:上线(TCP 建立),Logout 下线(TCP 断开)
To_Account String 用户 Identifier
Reason String App 上下线触发的原因:
上线的原因有 Register:App TCP 连接建立;
下线的原因有 Unregister:App 用户注销帐号导致 TCP 断开; LinkClose:云通信检测到 App TCP 连接断开;Timeout:云通信检测到 App 心跳包超时,认为 TCP 已断开(客户端杀后台或 Crash)

应答包示例

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

应答包字段说明

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

参考