状态变更回调

最后更新时间:2020-07-29 17:58:18

    功能说明

    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 必填 错误信息

    参考

    Was this page helpful?

    本页内容是否解决了您的问题?

    • 完全没帮助
    • 文档较差
    • 文档一般
    • 文档不错
    • 文档很好
    反馈
    帮助