tencent cloud

文档反馈

JavaScript

最后更新时间:2024-11-15 10:51:59

    功能描述

    Web Chat SDK 提供了用户状态管理的功能,每个用户拥有两种不同类型的状态:
    普通状态。SDK 内置状态,客户无法直接修改。
    自定义状态。客户自定义的状态,可以自行修改。利用自定义状态,您可以对该设置诸如“听歌中”、“通话中”等一些自定义信息。
    说明:
    用户状态针对的是当前用户,跟设备无关。如果有多台设备同时登录同一个账号,不支持按设备查询或者按设备设置状态。
    用户的普通状态类型有以下三种:
    在线(TencentCloudChat.TYPES.USER_STATUS_ONLINE):当前用户已登录上线,可以正常收发消息。
    离线(TencentCloudChat.TYPES.USER_STATUS_OFFLINE):web 登录/登出时不会触发离线状态, 在集成 Native IMSDK 的 App 中会触发离线状态。
    未登录(TencentCloudChat.TYPES.USER_STATUS_UNLOGINED):用户注册账号后从未登录过,或者用户主动调用 logout 退出登录。
    
    
    

    设置自己的自定义状态

    您可以调用接口 setSelfStatus 设置 customStatus 字段来设置自己的自定义状态。设置成功后,您可以通过 TencentCloudChat.EVENT.USER_STATUS_UPDATED 事件收到自己状态变更的通知。详情请参见下文的 状态变更通知
    说明:
    1. 调用 setSelfStatus 不需要升级到进阶版,也无需开启控制台开关。
    2. 本接口不做限频控制。
    3. 您可以在调用 setSelfStatus 接口时,通过将 customStatus 字段设置为空来主动清除。
    4. 账号登出一段时间(Web)后,IM 后台会自动清除自定义状态,此时也会触发状态变更通知。
    接口
    chat.setSelfStatus(options);
    参数
    参数 optionsObject类型,包含的属性值如下:
    参数
    类型
    说明
    customStatus
    String
    用户自定义状态
    返回值
    Promise
    示例
    // 设置 customStatus 为空字符串 '',则清除自己的自定义状态
    let promise = chat.setSelfStatus({customStatus: 'xxx'});
    promise.then(function(imResponse) {
    console.log(imResponse.data);
    const { userID, statusType, customStatus } = imResponse.data;
    // userID - 用户 ID
    // statusType - 用户状态,枚举值及说明如下:
    // TencentCloudChat.TYPES.USER_STATUS_UNKNOWN - 未知
    // TencentCloudChat.TYPES.USER_STATUS_ONLINE - 在线
    // TencentCloudChat.TYPES.USER_STATUS_OFFLINE - 离线
    // TencentCloudChat.TYPES.USER_STATUS_UNLOGINED - 未登录
    // customStatus - 用户自定义状态
    }).catch(function(imError) {
    console.warn('setSelfStatus error:', imError); // 设置用户自己的自定义状态失败的相关信息
    });

    查询用户状态

    此接口会返回被查询者的普通状态和自定义状态。
    说明:
    1. 查询自己的状态不限制进阶版。
    2. 查询自己的状态时,接口调用不限频。
    3. 查询其他用户的状态需要升级到进阶版,接口调用默认限制 5 秒 20 次请求,单次查询最大用户数不超过 500 人。
    4. 查询其他用户状态需要提前在 Chat Console 开启 “用户状态查询及状态变更通知”。如果开关关闭,调用 getUserStatus 会报错。
    接口
    chat.getUserStatus(options);
    参数
    参数 optionsObject类型,包含的属性值如下:
    参数
    类型
    说明
    userIDList
    Array
    待查询的用户 userID 列表,查询自己时,只需要传入自己的 userID 即可。
    返回值
    Promise
    示例
    // 查询自己的用户状态
    // userIDList 仅包含自己的 userID 时表示查询自己的状态
    let promise = chat.getUserStatus({userIDList: [`${myUserID}`]});
    promise.then(function(imResponse) {
    const { successUserList } = imResponse.data;
    successUserList.forEach((item) => {
    const { userID, statusType, customStatus } = item;
    // userID - 用户 ID
    // statusType - 用户状态,枚举值及说明如下:
    // TencentCloudChat.TYPES.USER_STATUS_UNKNOWN - 未知
    // TencentCloudChat.TYPES.USER_STATUS_ONLINE - 在线
    // TencentCloudChat.TYPES.USER_STATUS_OFFLINE - 离线
    // TencentCloudChat.TYPES.USER_STATUS_UNLOGINED - 未登录
    // customStatus - 用户自定义状态
    });
    }).catch(function(imError) {
    console.warn('getUserStatus error:', imError); // 获取用户状态失败的相关信息
    });

    查询其他人的状态

    设置 userIDList 为其他人的 userID 列表,可查询其他人的状态。
    
    
    
    示例
    // 查询其他用户的状态
    let promise = chat.getUserStatus({userIDList: ['user0', 'user1']});
    promise.then(function(imResponse) {
    const { successUserList, failureUserList } = imResponse.data;
    // 查询成功的用户列表
    successUserList.forEach((item) => {
    const { userID, statusType, customStatus } = item;
    // userID - 用户 ID
    // statusType - 用户状态,枚举值及说明如下:
    // TencentCloudChat.TYPES.USER_STATUS_UNKNOWN - 未知
    // TencentCloudChat.TYPES.USER_STATUS_ONLINE - 在线
    // TencentCloudChat.TYPES.USER_STATUS_OFFLINE - 离线
    // TencentCloudChat.TYPES.USER_STATUS_UNLOGINED - 未登录
    // customStatus - 用户自定义状态
    });
    
    // 查询失败的用户列表
    failureUserList.forEach((item) => {
    const { userID, code, message } = item;
    // userID - 查询失败的用户 ID
    // code - 查询失败的错误码
    // message - 查询失败的错误信息
    });
    }).catch(function(imError) {
    console.warn('getUserStatus error:', imError); // 获取用户状态失败的相关信息
    });

    订阅用户状态

    订阅成功后,当您所订阅的用户状态变更时(包括普通状态和自定义状态),您可以通过 TencentCloudChat.EVENT.USER_STATUS_UPDATED 事件收到用户状态变更通知。
    说明:
    1. 订阅用户状态需要升级到进阶版套餐,详情请参见 基础服务详情
    2. 接口限频默认为 5 秒 20 次请求,单次订阅最大用户数不超过 100 人。
    3. 列表订阅数量有限制,一旦超出限制,最早订阅的用户将被自动淘汰。
    接口
    chat.subscribeUserStatus(options);
    参数
    参数 optionsObject类型,包含的属性值如下:
    参数
    类型
    说明
    userIDList
    Array
    用户 userID 列表,单次请求最多 100 个。
    返回值
    Promise
    示例
    let promise = chat.subscribeUserStatus({userIDList: ['user0', 'user1']});
    promise.then(function(imResponse) {
    const { failureUserList } = imResponse.data;
    // 订阅失败的用户列表
    failureUserList.forEach((item) => {
    const { userID, code, message } = item;
    // userID - 查询失败的用户 ID
    // code - 查询失败的错误码
    // message - 查询失败的错误信息
    });
    }).catch(function(imError) {
    console.warn('subscribeUserStatus error:', imError); // 订阅用户状态失败的相关信息
    });

    取消订阅用户状态

    取消订阅成功后,当用户的状态发生变化(包括正常状态和自定义状态)时,SDK将不会派发TencentCloudChat.EVENT.USER_STATUS_UPDATED事件。
    说明:
    接口限频默认为 5 秒 20 次请求,单次取消订阅最大用户数不超过 100 人。
    接口
    chat.unsubscribeUserStatus(options);
    参数
    参数
    类型
    说明
    userIDList
    Array | undefined
    用户 userID 列表,单次请求最多 100 个。当 userIDList 为空数组或者 undefined 时,取消当前所有的订阅。
    返回值
    Promise
    示例
    // 取消当前部分用户的订阅
    let promise = chat.unsubscribeUserStatus({userIDList: ['user0', 'user1']});
    promise.then(function(imResponse) {
    const { failureUserList } = imResponse.data;
    // 取消订阅失败的用户列表
    failureUserList.forEach((item) => {
    const { userID, code, message } = item;
    // userID - 查询失败的用户 ID
    // code - 查询失败的错误码
    // message - 查询失败的错误信息
    });
    }).catch(function(imError) {
    console.warn('unsubscribeUserStatus error:', imError); // 取消订阅失败的相关信息
    });
    // 取消当前所有的订阅
    let promise = chat.unsubscribeUserStatus();
    promise.then(function(imResponse) {
    const { failureUserList } = imResponse.data;
    // 取消订阅失败的用户列表
    failureUserList.forEach((item) => {
    const { userID, code, message } = item;
    // userID - 查询失败的用户 ID
    // code - 查询失败的错误码
    // message - 查询失败的错误信息
    });
    }).catch(function(imError) {
    console.warn('unsubscribeUserStatus error:', imError); // 取消订阅失败的相关信息
    });

    自己的状态变更通知

    如果您提前注册了 TencentCloudChat.EVENT.USER_STATUS_UPDATED 事件监听,当自己的状态发生变更时,SDK 会派发 TencentCloudChat.EVENT.USER_STATUS_UPDATED 事件,您可以在其中获取到自己的最新状态。

    好友的状态变更通知

    1. 如果您在 Chat Console 开启了好友状态自动通知,那么当好友的状态发生变更时,SDK 会派发 TencentCloudChat.EVENT.USER_STATUS_UPDATED 事件,您可以在其中获取到好友的最新状态。
    2. 如果您没有开启好友状态自动通知,并且仍然想感知好友的状态变更,您需要调用 subscribeUserStatus 主动订阅好友的状态。当好友的状态发生变更时,SDK 会派发 TencentCloudChat.EVENT.USER_STATUS_UPDATED 回调。
    3. 如果您既没有开启好友状态自动通知,也没有调用 subscribeUserStatus 主动订阅好友状态,那么当好友状态发生变更时,您将无法感知到。

    普通用户(非好友)的状态变更

    如果您希望感知普通用户(非好友)的状态变更,只能调用 subscribeUserStatus 主动订阅。当该用户状态发生变更时,会触发 TencentCloudChat.EVENT.USER_STATUS_UPDATED 回调,您可以在其中获取到其最新状态。
    示例
    /**
    * 收到通知的情况:
    * 1. 订阅过的用户发生了状态变更(包括在线状态和自定义状态),会触发该事件
    * 2. 在控制台打开了好友状态通知开关,即使未主动订阅,当好友状态发生变更时,也会触发该事件
    * 3. 同一个账号多设备登录,当其中一台设备修改了自定义状态,所有设备都会收到该事件
    */
    let onUserStatusUpdated = function(event) {
    console.log(event.data);
    const userStatusList = event.data;
    userStatusList.forEach((item) => {
    const { userID, statusType, customStatus } = item;
    // userID - 用户 ID
    // statusType - 用户状态,枚举值及说明如下:
    // TencentCloudChat.TYPES.USER_STATUS_UNKNOWN - 未知
    // TencentCloudChat.TYPES.USER_STATUS_ONLINE - 在线
    // TencentCloudChat.TYPES.USER_STATUS_OFFLINE - 离线
    // TencentCloudChat.TYPES.USER_STATUS_UNLOGINED - 未登录
    // customStatus - 用户自定义状态
    })
    };
    chat.on(TencentCloudChat.EVENT.USER_STATUS_UPDATED, onUserStatusUpdated);

    状态变更通知多端、多实例同步

    如果您开启了多端或同平台多实例登录(详情请参见 多端或同平台多实例登录) ,同一个账号可以在不同设备上登录。当其中一个设备上所登录的用户的自定义状态发生变更时,IM 后台会给其他登录的设备也下发状态变更通知。

    常见问题

    调用订阅/取消订阅接口时,接口提示 “72001” 的错误码

    72001 错误码表示在控制台上并没有开启对应的能力,请登录 Chat Console 打开对应的功能开关。
    联系我们

    联系我们,为您的业务提供专属服务。

    技术支持

    如果你想寻求进一步的帮助,通过工单与我们进行联络。我们提供7x24的工单服务。

    7x24 电话支持