logo
当前页

在线状态订阅


说明

如需使用本功能,请开通旗舰版套餐。

功能简介

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

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

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

订阅用户在线状态

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

说明
  • 单个用户最多可以订阅 3000 人,当订阅用户超过 3000 人时,将会覆盖订阅时间最早的用户。
  • 订阅其他用户的在线状态后,即便用户在 subscriptionDuration 时限内登出并重新登录 ZIM SDK,订阅仍然有效,无需再次调用订阅方法。
Untitled
ZIMUserStatusSubscribeConfig config = new ZIMUserStatusSubscribeConfig();
config.subscriptionDuration = 60; // 订阅有效时间,单位为分钟,可填入的有效时间范围为 1 ~ 43200(即 30 天)

ArrayList<String> userIDs = new ArrayList<>();
userIDs.add("userIdA");
userIDs.add("userIdB");

zim.subscribeUsersStatus(userIDs, config, new ZIMUsersStatusSubscribedCallback() {
    @Override
    public void onUsersStatusSubscribed(ArrayList<ZIMErrorUserInfo> errorUserList, ZIMError errorInfo) {
        // 处理订阅回调
        for (ZIMErrorUserInfo errorUserInfo : errorUserList) {
            System.out.println("订阅失败的用户 ID: " + errorUserInfo.userID);
            System.out.println("订阅失败的错误码: " + errorUserInfo.reason);
        }
    }
});
1
Copied!

结果回调

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

说明

如果用户在订阅后重新登录,ZIM SDK 会通过此回调向用户主动通知其订阅的目标用户在其登出期间的最后一次状态变化。

Untitled
zim.setEventHandler(new ZIMEventHandler(){
    public void onUserStatusUpdated(ZIM zim, ArrayList<ZIMUserStatus> userStatusList) {
        for (ZIMUserStatus userStatus : userStatusList) {
            String userID = userStatus.userID; // 目标用户 ID
            String onlineStatus = userStatus.onlineStatus; // 用户在线状态
            ArrayList<String> onlinePlatforms = userStatus.onlinePlatforms; // 用户在线平台列表
            long lastUpdateTime = userStatus.lastUpdateTime; // 上次在线状态变更时间
        }
    }
});
1
Copied!

取消订阅用户在线状态

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

Untitled
ArrayList<String> userIDs = new ArrayList<>();
userIDs.add("userIdA");
userIDs.add("userIdB");

zim.unsubscribeUsersStatus(userIDs, new ZIMUsersStatusUnsubscribedCallback() {
    @Override
    public void onUsersStatusUnsubscribed(ArrayList<ZIMErrorUserInfo> errorUserList, ZIMError errorInfo) {
        for (ZIMErrorUserInfo errorUserInfo : errorUserList) {
            System.out.println("取消订阅失败的用户 ID: " + errorUserInfo.userID);
            System.out.println("取消订阅失败的错误码: " + errorUserInfo.reason);
        }
    }
});
1
Copied!

查询用户在线状态

如仅需获取一次目标用户的在线状态,无需持续关注时,可以调用 queryUsersStatus 接口并传入目标用户的 userIDs(至多 200 名用户,不得包括当前用户)。

Untitled
ArrayList<String> userIDs = new ArrayList<>();
userIDs.add("userIdA");
userIDs.add("userIdB");

zim.queryUsersStatus(userIDs, new ZIMUsersStatusQueriedCallback() {
    @Override
    public void onUsersStatusQueried(ArrayList<ZIMUserStatus> userStatusList,
                                        ArrayList<ZIMErrorUserInfo> errorUserList, ZIMError errorInfo) {
        for (ZIMUserStatus userStatus : userStatusList) {
            System.out.println("User ID: " + userStatus.userID); // 目标用户 ID
            System.out.println("Online Status: " + userStatus.onlineStatus); // 用户在线状态
            System.out.println("Online Platforms: " + userStatus.onlineStatus); // 用户在线平台列表
            System.out.println("Last Update Time: " + userStatus.lastUpdateTime); // 上次在线状态变更时间
        }
        
        for (ZIMErrorUserInfo errorUserInfo : errorUserList) {
            System.out.println("查询失败的用户 ID: " + errorUserInfo.userID);
            System.out.println("查询失败的错误码: " + errorUserInfo.reason);
        }
    }
});
1
Copied!

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

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

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

Untitled
// 查询目标用户 ID(单次查询至多包含 200 名用户)
// 当 userIDs 为 空,表示需要获取完整订阅表信息
// 当 userIDs 不为空,表示需要查询目标用户是否在订阅列表中
// 若存在,则结果回调会包含该用户状态信息
// 若不存在,则结果回调不包含相关信息
ZIMSubscribedUserStatusQueryConfig config = new ZIMSubscribedUserStatusQueryConfig();
config.userIDs.add("userIdA");
config.userIDs.add("userIdB");

zim.querySubscribedUserStatusList(config, new ZIMSubscribedUserStatusListQueriedCallback() {
    @Override
    public void onSubscribedUserStatusListQueried(ArrayList<ZIMUserStatusSubscription> userStatusSubscriptionList, ZIMError errorInfo) {
        for (ZIMUserStatusSubscription subscription : userStatusSubscriptionList) {
            subscription.subscribeExpiredTime; //订阅表中用户的订阅过期时间戳
            subscription.userStatus; //订阅表中用户的状态信息
        }
    }
});
1
Copied!

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

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

ZIMConnectionState 中, CONNECTED 表示用户在线, DISCONNECTED 表示用户离线;而剩余的 CONNECTINGRECONNECTING 这两种连接状态,您可以自行根据业务逻辑判断为用户是否在线。

Untitled
zim.setEventHandler(new ZIMEventHandler(){
    public void onConnectionStateChanged(ZIM zim, ZIMConnectionState state,
                                        ZIMConnectionEvent event, JSONObject extendedData) {
        switch (state) {
            case CONNECTED:
                // 已连接,您可以映射当前用户在线状态为在线
                break;
            case CONNECTING:
                // 连接中,您可以根据您的业务逻辑,映射当前用户在线状态为在线或者离线
                break;
            case RECONNECTING:
                // 重连中,您可以根据您的业务逻辑,映射当前用户在线状态为在线或离线
                break;
            case DISCONNECTED:
                // 已断开,您可以映射当前用户状态为离线
                break;
            default:
                break;
        }
    }
});
1
Copied!

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

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

说明

当 onUserStatusUpdated 回调返回当前用户的 userStatus 信息时,其中的 onlineStatus 将为 unknownlastUpdateTime 为 0,并不能真实反馈在线状态。

Untitled
zim.setEventHandler(new ZIMEventHandler(){
    public void onUserStatusUpdated(ZIM zim, ArrayList<ZIMUserStatus> userStatusList) {
        String myUserID = "当前用户的ID"; // 替换为实际当前用户的 ID
        for (ZIMUserStatus userStatus : userStatusList) {
            if (userStatus.userID.equals(myUserID)) {
                // 如果为当前用户,onlineStatus 将为 UNKNOWN,并不能真实反馈当前用户的在线状态
                ZIMUserOnlineStatus onlineStatus = userStatus.onlineStatus;
                
                // 当前用户的在线平台列表
                ArrayList<ZIMPlatformType> onlinePlatforms = userStatus.onlinePlatforms;
                
                // 如果为当前用户,lastUpdateTime 将为 0
                long lastUpdateTime = userStatus.lastUpdateTime;
            }
        }
    }
});
1
Copied!

Previous

好友管理

Next

房间管理