用户状态管理

说明

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

功能简介

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

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

自定义状态。根据您业务需要，自行定义的状态，例如请勿打扰、忙碌等。

本文介绍如何订阅、查询用户的在线状态、自定义状态，以及如何设置自己的自定义状态。

设置自己的自定义状态

您可以在登录时通过设置 ZIMLoginConfig 中的 customStatus 参数来设置自己的自定义状态，或是在登录后调用接口 updateUserCustomStatus 设置 customStatus 字段来设置。

customStatus 最大为 64 字节 updateUserCustomStatus 接口限频为 1次/秒

Untitled

// 创建订阅配置
const config = {
    subscriptionDuration: 60, // 订阅时长为60分钟
};

// 订阅用户ID列表
const userIDs = ['userIdA', 'userIdB'];

try {
    // 调用subscribeUsersStatus方法
    const result = await zim.subscribeUsersStatus(userIDs, config);

    // 检查订阅失败的用户
    if (result.errorUserList.length > 0) {
        result.errorUserList.forEach((errorUserInfo) => {
            console.log('订阅失败的用户ID：', errorUserInfo.userID);
            console.log('订阅失败的错误代码：', errorUserInfo.reason);
        });
    } else {
        console.log('所有用户订阅成功！');
    }
} catch (error) {
    // 捕获异常并处理错误代码
    console.error('订阅时发生错误：', error);
}

Copied!

订阅用户状态

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

说明

单个用户最多可以订阅 3000 人，当订阅用户超过 3000 人时，将会覆盖订阅时间最早的用户。
订阅其他用户的在线状态后，即便用户在 subscriptionDuration 时限内登出并重新登录 ZIM SDK，订阅仍然有效，无需再次调用订阅方法。

Untitled

// 创建订阅配置
const config = {
    subscriptionDuration: 60, // 订阅时长为60分钟
};

// 订阅用户ID列表
const userIDs = ['userIdA', 'userIdB'];

try {
    // 调用subscribeUsersStatus方法
    const result = await zim.subscribeUsersStatus(userIDs, config);

    // 检查订阅失败的用户
    if (result.errorUserList.length > 0) {
        result.errorUserList.forEach((errorUserInfo) => {
            console.log('订阅失败的用户ID：', errorUserInfo.userID);
            console.log('订阅失败的错误代码：', errorUserInfo.reason);
        });
    } else {
        console.log('所有用户订阅成功！');
    }
} catch (error) {
    // 捕获异常并处理错误代码
    console.error('订阅时发生错误：', error);
}

Copied!

结果回调

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

说明

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

取消订阅用户在线状态

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

查询用户在线状态

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

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

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

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

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

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

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

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

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

说明

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