tencent cloud

PrevNext

文档反馈

请输入关键字

Recent Pages

文档
即时通信 IM
    文档
    Download PDF

    JavaScript

    最后更新时间：2024-10-30 12:01:43
    下载PDF

      功能描述

      从 2.21.0 版本开始，Web Chat SDK 提供了用户状态管理的功能，每个用户拥有两种不同类型的状态：
      普通状态。SDK 内置状态，客户无法直接修改。
      自定义状态。客户自定义的状态，可以自行修改。利用自定义状态，您可以对该设置诸如“听歌中”、“通话中”等一些自定义信息。
      说明：
      用户状态针对的是当前用户，跟设备无关。如果有多台设备同时登录同一个账号，不支持按设备查询或者按设备设置状态。
      用户的普通状态类型有以下三种：
      在线（TIM.TYPES.USER_STATUS_ONLINE）：当前用户已登录上线，可以正常收发消息。
      离线（TIM.TYPES.USER_STATUS_OFFLINE）：web 登录/登出时不会触发离线状态， 在集成 Native IMSDK 的 App 中会触发离线状态。
      未登录（TIM.TYPES.USER_STATUS_UNLOGINED）：用户注册账号后从未登录过，或者用户主动调用 logout 退出登录。
      注意：
      下文所述的部分功能仅进阶版套餐支持，使用前请确认。
      下文所述的部分功能需要在 Chat Console 打开对应的用户状态开关，使用前请确认。
      
      
      

      设置自己的自定义状态

      您可以调用接口 setSelfStatus 设置 customStatus 字段来设置自己的自定义状态。设置成功后，您可以通过 TIM.EVENT.USER_STATUS_UPDATED 事件收到自己状态变更的通知。详情请参见下文的 状态变更通知。
      自定义状态清除机制：
      1. 您可以在调用 setSelfStatus 接口时，通过将 customStatus 字段设置为空来主动清除。
      2. 账号登出一段时间（Web）后，IM 后台会自动清除自定义状态，此时也会触发状态变更通知。
      说明：
      1. 调用 setSelfStatus 不需要升级到进阶版，也无需开启控制台开关。
      2. 本接口不做限频控制。
      接口
      chat.setSelfStatus(options);
      参数
      参数 options 为 Object 类型，包含的属性值如下：
      Name
      Type
      Description
      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); // 设置用户自己的自定义状态失败的相关信息
      });

      查询用户状态

      您可以调用 getUserStatus 接口查询自己和其他用户的状态，接口会返回被查询者的普通状态和自定义状态。
      接口
      chat.getUserStatus(options);
      参数
      参数 options 为 Object 类型，包含的属性值如下：
      Name
      Type
      Description
      userIDList
      Array
      待查询的用户 userID 列表，查询自己时，只需要传入自己的 userID 即可。
      返回值
      Promise

      查询自己的状态

      设置 userIDList 仅包含自己的 userID，可查询自己的状态。
      说明：
      1. 查询自己的状态不需要升级到旗舰版，也无需开启控制台开关。
      2. 查询自己的状态不做接口限频控制。
      示例
      // 查询自己的用户状态
      // 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 列表，可查询其他人的状态。
      查询其他用户状态需要升级到进阶版套餐，详情请参见 基础服务详情。
      查询其他用户状态需要提前在 Chat Console 开启 “用户状态查询及状态变更通知”。如果开关关闭，调用 getUserStatus 会报错。
      
      
      
      说明：
      接口限频默认为 5 秒 20 次请求，单次查询最大用户数不超过 500 人。
      示例
      // 查询其他用户的状态
      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); // 获取用户状态失败的相关信息
      });

      订阅用户状态

      您可以调用接口 subscribeUserStatus 订阅指定用户的状态。 订阅成功后，当您所订阅的用户状态变更时（包括普通状态和自定义状态），您可以通过 TIM.EVENT.USER_STATUS_UPDATED 事件收到用户状态变更通知。
      接口特性：
      1. 该接口不支持订阅自己的状态。如果您想感知自己的状态变更，可直接监听 TIM.EVENT.USER_STATUS_UPDATED 事件。详情请参见下文的 状态变更通知。
      2. 该接口支持订阅好友的状态，但是订阅好友也会占用 IM 后台订阅名额。
      如果您关心所有好友的状态，不需要调用本接口，直接在 Chat Console 开启好友状态自动通知开关，开启后，您可以通过 TIM.EVENT.USER_STATUS_UPDATED 事件收到好友状态变更通知。
      如果您仅关心部分好友的状态，只能调用 subscribeUserStatus 主动订阅。订阅成功后，您可以通过 TIM.EVENT.USER_STATUS_UPDATED 事件收到好友状态变更通知。
      订阅用户状态需要升级到进阶版套餐，详情请参见 基础服务详情。
      订阅用户状态需要提前在 Chat Console 开启 “用户状态查询及状态变更通知”。如果开关关闭，调用 subscribeUserStatus 会报错。
      说明：
      接口限频默认为 5 秒 20 次请求，单次订阅最大用户数不超过 100 人。
      接口
      chat.subscribeUserStatus(options);
      参数
      参数 options 为 Object 类型，包含的属性值如下：
      Name
      Type
      Description
      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); // 订阅用户状态失败的相关信息
      });

      取消订阅用户状态

      如果您不想接收用户的状态变更通知，您可以调用接口 unsubscribeUserStatus 取消订阅用户的状态或清空订阅列表。 如果您不想主动清空订阅列表，当账号退出登录后，IM 后台默认延迟一段时间后自动清空订阅列表。
      取消订阅用户状态需要升级到进阶版套餐，详情请参见 基础服务详情。
      取消订阅用户状态需要提前在 Chat Console 开启 “用户状态查询及状态变更通知”。如果开关关闭，调用 unsubscribeUserStatus 会报错。
      说明：
      接口限频默认为 5 秒 20 次请求，单次取消订阅最大用户数不超过 100 人。
      接口
      chat.unsubscribeUserStatus(options);
      参数
      参数 options 为 undefined 时，表示取消当前所有订阅，options 为 Object 时，包含的属性值如下：
      Name
      Type
      Description
      userIDList
      Array
      用户 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); // 取消订阅失败的相关信息
      });

      状态变更通知

      根据您希望感知用户状态的用户类型，可以将状态变更分为 3 种类型：
      1. 感知自己的状态变更。
      2. 感知好友的状态变更。
      3. 感知用户（非好友）的状态变更。
      上述 3 种方式的状态变更通知，SDK 都会派发 TIM.EVENT.USER_STATUS_UPDATED 事件。
      虽然状态通知都通过 TIM.EVENT.USER_STATUS_UPDATED 抛出，但不同类型的用户触发该通知的方式不同。

      自己的状态变更通知

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

      好友的状态变更通知

      1. 如果您在 Chat Console 开启了好友状态自动通知，那么当好友的状态发生变更时，SDK 会派发 TIM.EVENT.USER_STATUS_UPDATED 事件，您可以在其中获取到好友的最新状态。
      2. 如果您没有开启好友状态自动通知，并且仍然想感知好友的状态变更，您需要调用 subscribeUserStatus 主动订阅好友的状态。当好友的状态发生变更时，SDK 会派发 TIM.EVENT.USER_STATUS_UPDATED 回调。
      注意：
      subscribeUserStatus 仅进阶版客户支持，并且需要开启控制台开关。详情请参见上文的 订阅用户状态。
      3. 如果您既没有开启好友状态自动通知，也没有调用 subscribeUserStatus 主动订阅好友状态，那么当好友状态发生变更时，您将无法感知到。

      普通用户（非好友）的状态变更

      如果您希望感知普通用户（非好友）的状态变更，只能调用 subscribeUserStatus 主动订阅。当该用户状态发生变更时，会触发 TIM.EVENT.USER_STATUS_UPDATED 回调，您可以在其中获取到其最新状态。
      注意：
      subscribeUserStatus 仅进阶版客户支持，并且需要开启控制台开关。详情请参见上文的 订阅用户状态。
      示例
      /**
       * 收到通知的情况：
       * 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);
      说明：
      除了上述通过 TIM.EVENT.USER_STATUS_UPDATED 得知用户状态以外，您还可以主动查询用户状态，详情请参见上文 查询用户状态。

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

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

      接口限制

      套餐限制

      setSelfStatus 接口不限制进阶版。
      getUserStatus 查询自己的状态，不限制进阶版。
      getUserStatus 除了查询自己的状态外，均需要升级到进阶版。
      subscribeUserStatus / unsubscribeUserStatus 接口的所有能力，均需要升级到进阶版。

      接口限频

      setSelfStatus 接口不限频。
      getUserStatus 查询自己的状态，不限频。
      getUserStatus 除了查询自己的状态外，默认限制 5 秒 20 次请求，单次查询最大用户数不超过 500。
      subscribeUserStatus 接口，默认限制 5 秒 20 次请求，单次订阅最大用户数不超过 100。
      unsubscribeUserStatus 接口，默认限制 5 秒 20 次请求，单次取消订阅最大用户数不超过 100。

      常见问题

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

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

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

      联系我们
      技术支持

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

      提交工单
      7x24 电话支持
      Copyright © 2013-2024 Tencent Cloud. All Rights Reserved.
      隐私条款服务条款缓存条款