在线状态订阅

---

功能简介

用户在线状态（ZIMUserOnlineStatus)，可分为在线、离线，和登出三种状态。

• 在线：主动调用 login 接口登录并保持网络连接的条件下，用户的状态变更为在线状态。
• 登出：主动调用 logout 接口后，用户的状态变更为登出状态。
• 离线：调用 login 接口登录后，用户杀死 app、锁屏或退后台等行为导致网络断开，用户的状态变更为离线状态。

本文介绍如何订阅、查询用户的在线状态。

订阅用户在线状态

如需持续关注某些人的在线状态时，可以调用 subscribeUsersStatus 接口，向参数 userIDs 批量传入目标用户 ID（至多 100 名已注册用户，不得包含订阅者自身），在 config 中传入 subscriptionDuration（订阅有效时长，在此时段内会持续关注目标用户的在线状态变更），进而添加目标用户在线状态的订阅到当前用户的在线状态订阅表中。

ZIMUserStatusSubscribeConfig config = ZIMUserStatusSubscribeConfig();
config.subscriptionDuration = 60; // 订阅有效时间，单位分钟，可填入的有效时间范围为 1 ～ 43200（即 30 天）

ZIM.getInstance()?.subscribeUsersStatus(["userIdA","userIdB"], config).then((ZIMUsersStatusSubscribedResult result) {
    for(ZIMErrorUserInfo errorUserInfo in result.errorUserList){
        errorUserInfo.userID; // 订阅失败的用户 ID
        errorUserInfo.reason; // 订阅失败的错误码
    }
}).catchError((onError){

});

事件通知

随后，在 subscriptionDuration 规定的时间内，目标用户的在线状态变更将会通过 ZIMEventHandler 中的 onUserStatusUpdated 事件回调返回。

ZIMEventHandler.onUserStatusUpdated = (ZIM zim, List<ZIMUserStatus> userStatusList){
    for (ZIMUserStatus userStatus in userStatusList) {
        userStatus.userID;            // 目标用户 ID
        userStatus.onlineStatus;      // 用户在线状态
        userStatus.onlinePlatforms;   // 用户在线平台列表
        userStatus.lastUpdateTime;    // 上次在线状态变更时间
    }
};

取消订阅用户在线状态

若无需关注某些用户的在线状态，可调用 unsubscribeUsersStatus 接口，向 userIDs 参数传入目标用户 ID（至多 100 名用户）。

ZIM.getInstance()?.unsubscribeUsersStatus(["userIdA","userIdB"]).then((ZIMUsersStatusUnsubscribedResult result) {
    for(ZIMErrorUserInfo errorUserInfo in result.errorUserList){
        errorUserInfo.userID;   // 取消订阅失败的用户 ID
        errorUserInfo.reason;   // 取消订阅失败的错误码
    }
}).catchError((onError){

});

查询用户在线状态

如仅需获取一次目标用户的在线状态，无需持续关注时，可以调用 queryUsersStatus 接口并传入目标用户的 userIDs（至多 200 名用户）。

ZIM.getInstance()?.queryUsersStatus(["userIdA","userIdB"]).then((ZIMUsersStatusQueriedResult result) {
    for (ZIMUserStatus userStatus in result.userStatusList) {
      userStatus.userID;          // 目标用户 ID
      userStatus.onlineStatus;    // 用户在线状态
      userStatus.onlinePlatforms; // 用户在线平台列表
      userStatus.lastUpdateTime;  // 上次在线状态变更时间
    }
    for (ZIMErrorUserInfo errorUserInfo in result.errorUserList){
      errorUserInfo.userID; // 查询失败的用户 ID
      errorUserInfo.reason; // 查询失败的错误码
    }
}).catchError((onError){

});

查询在线状态用户订阅列表

如果用户希望了解自己订阅了哪些用户的在线状态，可以通过 querySubscribedUserStatusList 接口，参数 config.userIDs 传空，即可获取到完整的订阅列表，包含订阅目标用户当前的状态、以及订阅有效时长。

如果用户希望确认是否订阅了某些用户的在线状态，参数 config.userIDs 传入查询目标的 userID 即可。

ZIMSubscribedUserStatusQueryConfig queryConfig = ZIMSubscribedUserStatusQueryConfig();
queryConfig.userIDs = ["userIdA","userIdB"];
// 查询目标用户 ID（单次查询至多包含 200 名用户）
// 当 userIDs 为 空，表示需要获取完整订阅表信息
// 当 userIDs 不为空，表示需要查询目标用户是否在订阅列表中
// 若存在，则结果回调会包含该用户状态信息
// 若不存在，则结果回调不包含相关信息
ZIM.getInstance()?.querySubscribedUserStatusList(queryConfig).then((ZIMSubscribedUserStatusListQueriedResult result) {

}).catchError((onError){

});

监听当前用户在当前设备的在线状态

如果需了解当前用户的在线状态，可通过监听 onConnectionStateChanged 回调获取用户当前的连接状态（ZIMConnectionState），并根据其判断当前用户的在线状态。

在 ZIMConnectionState 中，connected 表示用户在线，disconnected 表示用户离线；而剩余的 connecting 和 reconnecting 这两种连接状态，您可以自行根据业务逻辑判断为用户是否在线。

ZIMEventHandler.onConnectionStateChanged = (ZIM zim, ZIMConnectionState state,
    ZIMConnectionEvent event, Map extendedData){
    switch (state) {
        case ZIMConnectionState.connected:
        // 已连接，您可以映射当前用户状态为在线
            break;
        case ZIMConnectionState.connecting:
        // 连接中，您可以根据您的业务逻辑，映射当前用户状态为在线或者离线
            break;
        case ZIMConnectionState.reconnecting:
        // 重连中，您可以根据您的业务逻辑，映射当前用户状态为在线或离线
            break;
        case ZIMConnectionState.disconnected:
        // 已断开，您可以映射当前用户状态为离线
            break;
        default:
        // 处理其他可能的状态
            break;
    }
};

监听当前用户的在线平台列表

在多端登录场景下，当用户登录了第二个平台后，可通过监听 onUserStatusUpdated 回调，从 userStatus.onlinePlatforms 属性了解目前在线的平台，开发者可以借此展示用户在不同平台上的在线状态（例如：显示用户在 iOS 和 Windows 端在线）。

ZIMEventHandler.onUserStatusUpdated = (ZIM zim, List<ZIMUserStatus> userStatusList){
    for (ZIMUserStatus userStatus in userStatusList) {
        if (userStatus.userID == "myUserID"){
            userStatus.onlineStatus;       // 如果为当前用户，onlineStatus 将为 UNKNOWN
            userStatus.onlinePlatforms;    // 当前用户的在线平台列表
            userStatus.lastUpdateTime;     // 如果为当前用户，lastUpdateTime 将为 0
       }
    }
};