Web

Prev Next

请输入关键字

Recent Pages

文档

Download PDF

最后更新时间：2022-09-09 18:49:15

下载PDF

功能描述

从 2.21.0 版本开始，Web IMSDK 提供了用户状态管理的功能，每个用户拥有两种不同类型的状态：

普通状态。SDK 内置状态，客户无法直接修改。
自定义状态。客户自定义的状态，可以自行修改。利用自定义状态，您可以对该帐号设置诸如”听歌中“、”通话中“等一些自定义信息。

说明：

用户状态针对的是当前用户，跟设备无关。如果有多台设备同时登录同一个账号，不支持按设备查询或者按设备设置状态。

用户的普通状态类型有以下三种：

在线（TIM.TYPES.USER_STATUS_ONLINE）：当前用户已登录上线，可以正常收发消息。
离线（TIM.TYPES.USER_STATUS_OFFLINE）：web 登录/登出时不会触发离线状态，在集成 Native IMSDK 的 App 中会触发离线状态。
未登录（TIM.TYPES.USER_STATUS_UNLOGINED）：用户注册账号后从未登录过，或者用户主动调用 logout 退出登录。

注意：

下文所述的部分功能仅旗舰版套餐支持，使用前请确认。

下文所述的部分功能需要在即时通信 IM 控制台打开对应的用户状态开关，使用前请确认。

设置自己的自定义状态

您可以调用接口 setSelfStatus 设置 customStatus 字段来设置自己的自定义状态。设置成功后，您可以通过 TIM.EVENT.USER_STATUS_UPDATED 事件收到自己状态变更的通知。详情请参见下文的状态变更通知。

自定义状态清除机制：

您可以在调用 setSelfStatus 接口时，通过将 customStatus 字段设置为空来主动清除。
账号登出一段时间（Web）后，IM 后台会自动清除自定义状态，此时也会触发状态变更通知。

说明：

调用 setSelfStatus 不需要升级到旗舰版，也无需开启控制台开关。

本接口不做限频控制。

接口

tim.setSelfStatus(options);

参数

参数 options 为 Object 类型，包含的属性值如下：

Name	Type	Description
customStatus	String	用户自定义状态

返回值

Promise 对象。

示例

// 设置 customStatus 为空字符串 ''，则清除自己的自定义状态
let promise = tim.setSelfStatus({customStatus: 'xxx'});
promise.then(function(imResponse) {
  console.log(imResponse.data);
  const { userID, statusType, customStatus } = imResponse.data;
  // userID - 用户 ID
  // statusType - 用户状态，枚举值及说明如下：
  // TIM.TYPES.USER_STATUS_UNKNOWN - 未知
  // TIM.TYPES.USER_STATUS_ONLINE - 在线
  // TIM.TYPES.USER_STATUS_OFFLINE - 离线
  // TIM.TYPES.USER_STATUS_UNLOGINED - 未登录
  // customStatus - 用户自定义状态
}).catch(function(imError) {
  console.warn('setSelfStatus error:', imError); // 设置用户自己的自定义状态失败的相关信息
});

查询用户状态

您可以调用 getUserStatus 接口查询自己和其他用户的状态，接口会返回被查询者的普通状态和自定义状态。

接口

tim.getUserStatus(options);

参数

参数 options 为 Object 类型，包含的属性值如下：

Name	Type	Description
userIDList	Array	待查询的用户 userID 列表，查询自己时，只需要传入自己的 userID 即可。

返回值

Promise 对象。

查询自己的状态

设置 userIDList 仅包含自己的 userID，可查询自己的状态。

说明：

查询自己的状态不需要升级到旗舰版，也无需开启控制台开关。

查询自己的状态不做接口限频控制。

示例

// 查询自己的用户状态
// userIDList 仅包含自己的 userID 时表示查询自己的状态
let promise = tim.getUserStatus({userIDList: [`${myUserID}`]});
promise.then(function(imResponse) {
   const { successUserList } = imResponse.data;
   successUserList.forEach((item) => {
     const { userID, statusType, customStatus } = item;
     // userID - 用户 ID
     // statusType - 用户状态，枚举值及说明如下：
     // TIM.TYPES.USER_STATUS_UNKNOWN - 未知
     // TIM.TYPES.USER_STATUS_ONLINE - 在线
     // TIM.TYPES.USER_STATUS_OFFLINE - 离线
     // TIM.TYPES.USER_STATUS_UNLOGINED - 未登录
     // customStatus - 用户自定义状态
   });
}).catch(function(imError) {
  console.warn('getUserStatus error:', imError); // 获取用户状态失败的相关信息
});

查询其他人的状态

设置 userIDList 为其他人的 userID 列表，可查询其他人的状态。

查询其他用户状态需要升级到旗舰版套餐，详情请参见基础服务详情。

查询其他用户状态需要提前在即时通信 IM 控制台开启 ”用户状态查询及状态变更通知“。如果开关关闭，调用 getUserStatus 会报错。

说明：

接口限频默认为 5 秒 20 次请求，单次查询最大用户数不超过 500 人。

示例

// 查询其他用户的状态
let promise = tim.getUserStatus({userIDList: ['user0', 'user1']});
promise.then(function(imResponse) {
   const { successUserList, failureUserList } = imResponse.data;
   // 查询成功的用户列表
   successUserList.forEach((item) => {
     const { userID, statusType, customStatus } = item;
     // userID - 用户 ID
     // statusType - 用户状态，枚举值及说明如下：
     // TIM.TYPES.USER_STATUS_UNKNOWN - 未知
     // TIM.TYPES.USER_STATUS_ONLINE - 在线
     // TIM.TYPES.USER_STATUS_OFFLINE - 离线
     // TIM.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 事件收到用户状态变更通知。

接口特性：

该接口不支持订阅自己的状态。如果您想感知自己的状态变更，可直接监听 TIM.EVENT.USER_STATUS_UPDATED 事件。详情请参见下文的状态变更通知。
该接口支持订阅好友的状态，但是订阅好友也会占用 IM 后台订阅名额。
- 如果您关心所有好友的状态，不需要调用本接口，直接在即时通信 IM 控制台开启好友状态自动通知开关，开启后，您可以通过 TIM.EVENT.USER_STATUS_UPDATED 事件收到好友状态变更通知。
- 如果您仅关心部分好友的状态，只能调用 subscribeUserStatus 主动订阅。订阅成功后，您可以通过 TIM.EVENT.USER_STATUS_UPDATED 事件收到好友状态变更通知。

订阅用户状态需要升级到旗舰版套餐，详情请参见基础服务详情。

订阅用户状态需要提前在即时通信 IM 控制台开启 ”用户状态查询及状态变更通知“。如果开关关闭，调用 subscribeUserStatus 会报错。

说明：

接口限频默认为 5 秒 20 次请求，单次订阅最大用户数不超过 100 人。

接口

tim.subscribeUserStatus(options);

参数

参数 options 为 Object 类型，包含的属性值如下：

Name	Type	Description
userIDList	Array	用户 userID 列表，单次请求最多 100 个。

返回值

Promise 对象。

示例

let promise = tim.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 后台默认延迟一段时间后自动清空订阅列表。

取消订阅用户状态需要升级到旗舰版套餐，详情请参见基础服务详情。

取消订阅用户状态需要提前在即时通信 IM 控制台开启 ”用户状态查询及状态变更通知“。如果开关关闭，调用 unsubscribeUserStatus 会报错。

说明：

接口限频默认为 5 秒 20 次请求，单次取消订阅最大用户数不超过 100 人。

接口

tim.unsubscribeUserStatus(options);

参数

参数 options 为 undefined 时，表示取消当前所有订阅，options 为 Object 时，包含的属性值如下：

Name	Type	Description
userIDList	Array	用户 userID 列表，单次请求最多 100 个。当 userIDList 为空数组或者 undefined 时，取消当前所有的订阅。

返回值

Promise 对象。

示例

// 取消当前部分用户的订阅
let promise = tim.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 = tim.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 种类型：

感知自己的状态变更。
感知好友的状态变更。
感知用户（非好友）的状态变更。

上述 3 种方式的状态变更通知，SDK 都会派发 TIM.EVENT.USER_STATUS_UPDATED 事件。

虽然状态通知都通过 TIM.EVENT.USER_STATUS_UPDATED 抛出，但不同类型的用户触发该通知的方式不同。

自己的状态变更通知

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

好友的状态变更通知

如果您在即时通信 IM 控制台开启了好友状态自动通知，那么当好友的状态发生变更时，SDK 会派发 TIM.EVENT.USER_STATUS_UPDATED 事件，您可以在其中获取到好友的最新状态。
如果您没有开启好友状态自动通知，并且仍然想感知好友的状态变更，您需要调用 subscribeUserStatus 主动订阅好友的状态。当好友的状态发生变更时，SDK 会派发 TIM.EVENT.USER_STATUS_UPDATED 回调。

注意：

subscribeUserStatus 仅旗舰版客户支持，并且需要开启控制台开关。详情请参见上文的订阅用户状态。

如果您既没有开启好友状态自动通知，也没有调用 subscribeUserStatus 主动订阅好友状态，那么当好友状态发生变更时，您将无法感知到。

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

如果您希望感知普通用户（非好友）的状态变更，只能调用 subscribeUserStatus 主动订阅。当该用户状态发生变更时，会触发 TIM.EVENT.USER_STATUS_UPDATED 回调，您可以在其中获取到其最新状态。

注意：

subscribeUserStatus 仅旗舰版客户支持，并且需要开启控制台开关。详情请参见上文的订阅用户状态。

示例

/**
 * 收到通知的情况：
 * 1. 订阅过的用户发生了状态变更（包括在线状态和自定义状态），会触发该事件
 * 2. 在 IM 控制台打开了好友状态通知开关，即使未主动订阅，当好友状态发生变更时，也会触发该事件
 * 3. 同一个账号多设备登录，当其中一台设备修改了自定义状态，所有设备都会收到该事件
 */
let onUserStatusUpdated = function(event) {
   console.log(event.data);
   const userStatusList = event.data;
   userStatusList.forEach((item) => {
     const { userID, statusType, customStatus } = item;
     // userID - 用户 ID
     // statusType - 用户状态，枚举值及说明如下：
     // TIM.TYPES.USER_STATUS_UNKNOWN - 未知
     // TIM.TYPES.USER_STATUS_ONLINE - 在线
     // TIM.TYPES.USER_STATUS_OFFLINE - 离线
     // TIM.TYPES.USER_STATUS_UNLOGINED - 未登录
     // customStatus - 用户自定义状态
   })
};
tim.on(TIM.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 错误码表示在控制台上并没有开启对应的能力，请登录即时通信 IM 控制台打开对应的功能开关。

联系我们

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

技术支持

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

7x24 电话支持

tencent cloud

Recent Pages

Web

功能描述

设置自己的自定义状态

查询用户状态

查询自己的状态

查询其他人的状态

订阅用户状态

取消订阅用户状态

状态变更通知

自己的状态变更通知

好友的状态变更通知

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

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

接口限制

套餐限制

接口限频

常见问题

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

本页内容是否解决了您的问题？

本页内容是否解决了您的问题？