Class UserInfoManager

constructor

• new UserInfoManager(): UserInfoManager

  Returns UserInfoManager

Readonlycapabilities

addEventHandler

• addEventHandler(id: EventHandlerId, handlers: UserInfoEventHandlerMap): void

  注册用户资料事件处理器，用于接收当前用户资料更新和订阅用户资料变更通知。

  Parameters

  • id: string

    事件处理器 ID，同一个 ID 再次注册会覆盖旧处理器。
  • handlers: UserInfoEventHandlerMap

    用户资料事件处理器集合。

  可监听事件

  onOwnInfoUpdated, onUserInfoUpdated

  UserInfoEventName

  Returns void

  无返回值。

  Example: 调用示例（注册事件处理器）

  client.userInfoManager.addEventHandler('profile-listener', {
    onOwnInfoUpdated: profile => {
      console.log(profile.nickname);
    },
    onUserInfoUpdated: users => {
      console.log(users.map(user => user.userId));
    },
  });
  Copy

removeEventHandler

• removeEventHandler(id: string): void

  移除指定 ID 的用户资料事件处理器，停止接收对应事件回调。

  Parameters

  • id: string

    注册时传入的事件处理器 ID。

  Returns void

  无返回值。

  Example: 调用示例（移除事件处理器）

  client.userInfoManager.removeEventHandler('profile-listener');
  Copy

getUserInfoByUserId

• getUserInfoByUserId(
      params: FetchUserInfoByUserIdParams,
  ): Promise<readonly UserInfo[]>

  按用户 ID 查询用户资料属性；未指定属性时查询 SDK 默认资料字段。

  Parameters

  • params: FetchUserInfoByUserIdParams

    包含 userIds 与可选成功/失败回调的参数对象。

  Returns Promise<readonly UserInfo[]>

  返回标准化后的用户资料数组，仅包含服务端命中的用户。

  Example: 调用示例（按用户 ID 查询）

  const users = await client.userInfoManager.getUserInfoByUserId({
    userIds: ['alice', 'bob'],
  });
  console.log(users[0]?.avatarUrl);
  Copy

  可能出现的错误码

  Code	含义	HTTP	处理建议	可重试
  110	参数无效	-	传入非空用户 ID 数组，并确保每个用户 ID 都是非空字符串	否
  900	批量查询用户数超限	400	减少单次查询的用户数量后重试	否
  204	用户不存在	404	确认用户 ID 正确	否
  4	超过服务限制	429	降低请求频率后重试	是

getUserInfoByAttribute

• getUserInfoByAttribute(
      params: FetchUserInfoByAttributeParams,
  ): Promise<readonly UserInfo[]>

  按用户 ID 和指定属性集查询用户资料，适合只读取昵称、头像等部分字段。

  Parameters

  • params: FetchUserInfoByAttributeParams

    包含 userIds、attributes 与可选回调的参数对象。

  Returns Promise<readonly UserInfo[]>

  返回标准化后的用户资料数组。

  Example: 调用示例（按属性集查询）

  const users = await client.userInfoManager.getUserInfoByAttribute({
    userIds: ['alice'],
    attributes: ['nickname', 'avatarUrl'],
  });
  console.log(users[0]?.nickname);
  Copy

  可能出现的错误码

  Code	含义	HTTP	处理建议	可重试
  110	参数无效	-	传入非空用户 ID 数组和非空资料属性数组，并确保属性名属于支持范围	否
  900	批量查询用户数超限	400	减少单次查询的用户数量后重试	否
  204	用户不存在	404	确认用户 ID 正确	否
  4	超过服务限制	429	降低请求频率后重试	是

subscribeUsersInfo

• subscribeUsersInfo(params: SubscribeUsersInfoParams): Promise<void>

  订阅指定陌生人用户的资料变化；订阅成功后可通过用户资料事件处理器接收变更通知。

  Parameters

  • params: SubscribeUsersInfoParams

    包含 userIds 与可选回调的参数对象。

  Returns Promise<void>

  成功时无返回值。

  Example: 调用示例（订阅资料变化）

  await client.userInfoManager.subscribeUsersInfo({
    userIds: ['alice', 'bob'],
  });
  Copy

  可能出现的错误码

  Code	含义	HTTP	处理建议	可重试
  202	用户鉴权失败	401	刷新 token 后重试	是
  210	服务未开通或无权限	403	检查服务开通状态与账号权限后重试	否
  1600	订阅人数超限	400	减少单次订阅的目标用户数量后重试	否
  1601	目标用户被订阅人数超限	400	更换订阅目标或稍后重试	否
  4	超过服务限制	429	降低请求频率后重试	是
  303	服务请求通用错误：服务端内部错误	500	稍后重试或联系服务端排查	是

unsubscribeUsersInfo

• unsubscribeUsersInfo(params: UnsubscribeUsersInfoParams): Promise<void>

  取消订阅指定陌生人用户的资料变化；取消后不再接收这些用户的资料变更通知。

  Parameters

  • params: UnsubscribeUsersInfoParams

    包含 userIds 与可选回调的参数对象。

  Returns Promise<void>

  成功时无返回值。

  Example: 调用示例（取消订阅资料变化）

  await client.userInfoManager.unsubscribeUsersInfo({
    userIds: ['alice'],
  });
  Copy

  可能出现的错误码

  Code	含义	HTTP	处理建议	可重试
  202	用户鉴权失败	401	刷新 token 后重试	是
  210	服务未开通或无权限	403	检查服务开通状态与账号权限后重试	否
  1600	订阅人数超限	400	减少单次订阅的目标用户数量后重试	否
  1601	目标用户被订阅人数超限	400	更换订阅目标或稍后重试	否
  4	超过服务限制	429	降低请求频率后重试	是
  303	服务请求通用错误：服务端内部错误	500	稍后重试或联系服务端排查	是

getSubscribedUsers

• getSubscribedUsers(): Promise<readonly UserInfo[]>

  查询当前用户已订阅资料变化的陌生人列表，并返回这些用户的标准化资料。

  Returns Promise<readonly UserInfo[]>

  返回标准化后的用户资料数组。

  Example: 调用示例（查询已订阅用户）

  const users = await client.userInfoManager.getSubscribedUsers();
  console.log(users.map(user => user.userId));
  Copy

  可能出现的错误码

  Code	含义	HTTP	处理建议	可重试
  202	用户鉴权失败	401	刷新 token 后重试	是
  210	服务未开通或无权限	403	检查服务开通状态与账号权限后重试	否
  1600	订阅人数超限	400	减少单次订阅的目标用户数量后重试	否
  1601	目标用户被订阅人数超限	400	更换订阅目标或稍后重试	否
  4	超过服务限制	429	降低请求频率后重试	是
  303	服务请求通用错误：服务端内部错误	500	稍后重试或联系服务端排查	是

updateOwnInfo

• updateOwnInfo(params: UpdateOwnInfoParams): Promise<UserInfo>

  更新当前登录用户的一个或多个资料属性，例如昵称、头像、邮箱、手机号、签名或扩展字段。

  Parameters

  • params: UpdateOwnInfoParams

    至少包含一个可更新字段的参数对象。

  Returns Promise<UserInfo>

  返回标准化后的当前用户资料。

  Example: 调用示例（整对象更新）

  const profile = await client.userInfoManager.updateOwnInfo({
    nickname: 'Alice',
    avatarUrl: 'https://example.com/avatar.png',
  });
  console.log(profile.userId, profile.nickname);
  Copy

  可能出现的错误码

  Code	含义	HTTP	处理建议	可重试
  110	参数无效	-	至少传入一个可更新字段，并确保字段值类型合法	否
  901	用户资料数据长度超限	403	缩短资料字段内容后重试	否
  204	用户不存在	404	确认用户已注册	否
  4	超过服务限制	429	降低请求频率后重试	是

updateOwnInfoByAttribute

• updateOwnInfoByAttribute(
      attribute: UserInfoAttribute,
      value: string | number | boolean,
  ): Promise<UserInfo>

  更新当前登录用户的单个资料属性，适合只修改昵称、头像等一个字段的场景。

  Parameters

  • attribute: UserInfoAttribute

    需要更新的资料属性。
  • value: string | number | boolean

    属性值；空字符串、false、0 都是合法值。

  Returns Promise<UserInfo>

  返回标准化后的当前用户资料。

  Example: 调用示例（单属性更新）

  const profile = await client.userInfoManager.updateOwnInfoByAttribute(
    'avatarUrl',
    'https://example.com/avatar.png'
  );
  console.log(profile.avatarUrl);
  Copy

  可能出现的错误码

  Code	含义	HTTP	处理建议	可重试
  110	参数无效	-	仅使用支持的资料属性，并确保属性值类型合法	否
  901	用户资料数据长度超限	403	缩短资料字段内容后重试	否
  204	用户不存在	404	确认用户已注册	否
  4	超过服务限制	429	降低请求频率后重试	是