在线状态订阅

---

功能简介

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

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

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

订阅用户在线状态

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

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

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

try {
    // 调用订阅方法
    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);
}

结果回调

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

// 监听用户状态更新事件
zim.on('userStatusUpdated', function (zim, { userStatusList }) {
    userStatusList.forEach((userStatus) => {
        const { userID, onlineStatus, onlinePlatforms, lastUpdateTime } = userStatus;

        console.log('userStatusUpdated:', userID, onlineStatus, onlinePlatforms, lastUpdateTime);

        // 在这里处理用户状态更新后的逻辑，例如更新 UI 或其他操作
    });
});

取消订阅用户在线状态

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

// 需要取消订阅的用户 ID 列表
const userIDs = ['userIdA', 'userIdB'];

try {
    // 调用取消订阅方法
    const result = await zim.unsubscribeUsersStatus(userIDs);

    // 检查取消订阅失败的用户
    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);
}

查询用户在线状态

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

// 需要查询状态的用户 ID 列表
const userIDs = ['userIdA', 'userIdB'];

try {
    // 调用查询用户状态方法
    const result = await zim.queryUsersStatus(userIDs);

    // 遍历查询成功的用户状态
    result.userStatusList.forEach((userStatus) => {
        console.log('User ID:', userStatus.userID); // 目标用户 ID
        console.log('Online Status:', userStatus.onlineStatus); // 用户在线状态
        console.log('Online Platforms:', userStatus.onlinePlatforms); // 用户在线平台列表
        console.log('Last Update Time:', userStatus.lastUpdateTime); // 上次在线状态变更时间
    });

    // 检查查询失败的用户
    result.errorUserList.forEach((errorUserInfo) => {
        console.log('查询失败的用户 ID:', errorUserInfo.userID);
        console.log('查询失败的错误码:', errorUserInfo.reason);
    });
} catch (error) {
    // 捕获异常并处理错误
    console.error('查询用户状态时发生错误:', error);
}

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

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

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

// 查询配置对象
const config = {
    userIDs: ['userIdA', 'userIdB'], // 如果为空则查询全部订阅用户
};

try {
    // 调用查询订阅用户状态列表方法
    const result = await zim.querySubscribedUserStatusList(config);

    // 遍历订阅用户状态信息
    result.userStatusSubscriptionList.forEach((subscription) => {
        console.log('订阅过期时间:', subscription.subscribeExpiredTime); // 订阅过期时间戳
        console.log('用户状态信息:', subscription.userStatus); // 用户状态信息
    });
} catch (error) {
    // 捕获异常并处理错误
    console.error('查询订阅用户状态列表时发生错误:', error);
}

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

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

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

zim.on('connectionStateChanged', function (zim, { state, event }) {
    switch (state) {
        case 2: // Connected
            console.log('已连接');
            break;
        case 1: // Connecting:
            console.log('连接中');
            break;
        case 3: // Reconnecting:
            console.log('重连中');
            break;
        case 0: // Disconnected:
            console.log('已断开');
            break;
        default:
            console.log('未知状态');
            break;
    }

    console.log('连接事件:', event, state);
});

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

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

zim.on('userStatusUpdated', function (zim, userStatusList) {
    const myUserID = '当前用户的ID'; // 替换为实际当前用户的 ID

    userStatusList.forEach((userStatus) => {
        if (userStatus.userID === myUserID) {
            // 如果为当前用户，onlineStatus 将为 unknown，并不能真实反馈当前用户的在线状态
            const onlineStatus = userStatus.onlineStatus;

            // 当前用户的在线平台列表
            const onlinePlatforms = userStatus.onlinePlatforms;

            // 如果为当前用户，lastUpdateTime 将为 0
            const lastUpdateTime = userStatus.lastUpdateTime;

            // 处理在线状态、在线平台等逻辑
            console.log('当前用户在线状态:', onlineStatus);
            console.log('当前用户在线平台:', onlinePlatforms);
            console.log('最后状态更新时间:', lastUpdateTime);
        }
    });
});