logo
控制台
即时通讯
小程序: JS
产品简介
概述
计费说明
基本概念介绍
客户端 SDK
下载
发布日志
升级指南
错误码
快速开始
跑通示例源码
实现基本消息收发
功能指引
用户
房间
群组
消息
会话
内容审核
呼叫邀请
离线推送
迁移方案
API 参考文档
客户端 APIlink
服务端 APIlink
常见问题link
当前页

用户状态管理

说明

如需使用本功能，请开通旗舰版套餐，并联系 ZEGO 技术支持打开用户状态订阅开关。

功能简介

用户状态包含用户在线状态和自定义状态：
  • 用户在线状态（ ZIMUserOnlineStatus )：可分为在线、离线，和登出三种状态，由 ZIM 定义，开发者无法修改。
    • 在线：主动调用 login 接口登录并保持网络连接的条件下，用户的状态变更为在线状态。
    • 登出：主动调用 logout 接口后，用户的状态变更为登出状态。
    • 离线：调用 login 接口登录后，用户杀死 app、锁屏或退后台等行为导致网络断开，用户的状态变更为离线状态。
  • 自定义状态：您可以按需自行定义的状态，例如，请勿打扰、忙碌等。
1_用户状态_中文.png

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

设置自定义状态

您可以使用以下任意方式设置自定义状态：
    • 说明
    • customStatus 长度上限为 64 字节，有效期为 1 天。
    • 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);
}
    1
    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);
}
    1
    Copied!

    结果回调

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

    说明

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

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

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

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

    取消订阅用户在线状态

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

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

try {
    // 调用unsubscribeUsersStatus方法
    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);
}
    1
    Copied!

    查询用户在线状态

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

    Untitled
    // 需要查询状态的用户 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);
}
    1
    Copied!

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

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

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

    Untitled
    // 查询配置对象
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);
}
    1
    Copied!

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

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

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

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

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

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

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

    说明

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

    Untitled
    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);
        }
    });
});
    1
    Copied!

    Previous

    好友管理

    Next

    房间管理

    当前页

    返回到顶部