跳到主要内容

用户信息托管

本文档旨在指导开发者如何在融云即时通讯 HarmonyOS 客户端 SDK 中实现用户信息订阅、查询和监听，同时支持用户信息与权限的修改、查询。

通过本文档，HarmonyOS 开发者将了解如何获取和跟踪用户信息，以及如何在用户信息变更、订阅状态变更时接收通知。

提示

此功能在 25.12.0 版本开始支持。

开通服务​

信息托管服务已默认开通，您可以直接使用此功能。

提示

开启信息托管功能后，您可以通过 API 设置用户、群组资料信息。设置资料即视为同意将用户、群组资料信息托管在融云服务器存储和维护。信息托管服务产生的状态通知会计入消息分发和下行统计，功能开通后 15 分钟生效。

管理用户信息​

可以修改或查询自己的用户信息，批量查询指定多个用户的用户信息。

设置用户信息​

用户在应用中使用 updateMyUserProfile 可以修改自己的用户信息，您需要设置的相关用户信息可以通过创建 UserProfile 对象来配置相关属性。

提示

默认情况下，您设置的资料信息不会进行审核。如需要开通审核功能，请在需先按控制台内嵌指南嵌入到管理后台的 IM 服务功能配置页面（page_code: im_service_config）中，进入 安全&审核 > IM 信息托管审核，开启并设置需要审核的内容。

接口​

TypeScript
public updateMyUserProfile(profile: UserProfile): Promise<IAsyncResult<Array<string>>>;

参数说明​

下表描述 UserProfile 类的属性，也可参考 API 文档。

属性名类型描述
namestring昵称，长度不超过 32 个字符。
portraitUristring头像地址，长度不超过 128 个字符。
uniqueIdstring用户应用号，支持大小写字母、数字，长度不超过 32 个字符。请注意 SDK 不支持设置此字段。
emailstringEmail，长度不超过 128 个字符。
genderUserGender性别，未知 0、男 1、女 2。
locationstring所在地，长度不超过 32 个字符。
roleint角色，支持 0~100 以内数字。
levelint级别，支持 0~100 以内数字。
userExtProfileHashMap自定义扩展信息，最多可以设置 20 个用户信息（以 Key、Value 方式设置，扩展用户信息通过开发者后台进行设置）
  1. Key：支持大小写字母、数字，长度不超过 32 个字符，需要保障 AppKey 下唯一。Key 不存在时，设置不成功返回错误提示。
  2. Value：字符串，不超过 256 个字符。

示例代码​

TypeScript
// 更新自己的用户信息
let profile = new UserProfile();
profile.name = "name";
profile.gender = UserGender.UserGenderMale;
profile.role = 0;
profile.level = 0;
profile.userExtProfile = new HashMap<string, string>();
profile.userExtProfile.set("key", "value");
IMEngine.getInstance().updateMyUserProfile(profile).then((result: IAsyncResult<Array<string>>) => {
  if (result.code === EngineError.Success) {
    // 更新成功
  } else {
    // 更新失败
  }
});

获取当前用户信息​

您可以使用 getMyUserProfile 方法获取当前用户信息。

示例代码​

TypeScript
IMEngine.getInstance().getMyUserProfile().then((result: IAsyncResult<UserProfile>) => {
  if (result.code === EngineError.Success) {
    // 查询成功，返回自己的用户信息
  } else {
    // 查询失败
  }
});

批量获取用户信息​

您可以使用 getUserProfiles 方法，通过传入指定用户的 userId 来查询指定用户的用户信息。

提示

单次最多查询 20 个用户的用户信息。

示例代码​

TypeScript
// 设置查询用户 ID 列表
let userIds = new Array<string>();
userIds.push("userId1");
userIds.push("userId2");
IMEngine.getInstance().getUserProfiles(userIds).then((result: IAsyncResult<Array<UserProfile>>) => {
  if (result.code === EngineError.Success) {
    // 获取用户信息完成
  } else {
    // 获取用户信息失败
  }
});

管理用户权限​

融云 IMLib SDK 提供了对用户级别用户权限进行设置和获取接口，通过接口设置 UserProfileVisibility 枚举来设置不同的用户权限。

UserProfileVisibility 枚举介绍​

枚举值用户权限
UserProfileVisibilityNotSet未设置：以 AppKey 权限设置为准，默认是此状态。
UserProfileVisibilityInvisible都不可见：任何人都不能搜索到我的用户信息，名称、头像除外。
UserProfileVisibilityEveryone所有人：应用中任何用户都可以查看到我的用户信息。
UserProfileVisibilityFriendVisible仅好友可见：仅我的好友列表中用户可以查看到我的用户信息。

用户权限说明​

AppKey 下默认用户信息访问权限为 都不可见，用户级别默认用户信息访问权限为 未设置。当您都未设置也就是二者访问权限都为默认值时， 您仅可查看他人的用户名和头像信息。

下面列举了 AppKey 级 权限与 用户级 权限综合说明：

AppKey 级权限用户级权限结果
都不可见、仅好友可见、所有人可见未设置以 AppKey 级权限设置为准
都不可见、仅好友可见、所有人可见设置为（都不可见、仅好友可见、所有人可见）以用户级权限设置为准

设置用户权限​

您可以使用 updateMyUserProfileVisibility 方法设置您自己的用户信息访问权限。

示例代码​

TypeScript
let visibility: UserProfileVisibility = UserProfileVisibility.UserProfileVisibilityEveryone;
IMEngine.getInstance().updateMyUserProfileVisibility(visibility).then((result: IAsyncResult<void>) => {
  if (result.code === EngineError.Success) {
    // 设置用户信息访问权限成功
  } else {
    // 设置用户信息访问权限失败
  }
});

获取用户权限​

您可以使用 getMyUserProfileVisibility 方法获取您自己的用户信息访问权限。

示例代码​

TypeScript
IMEngine.getInstance().getMyUserProfileVisibility().then((result: IAsyncResult<UserProfileVisibility>) => {
  if (result.code === EngineError.Success) {
    // 获取用户信息访问权限成功
  } else {
    // 获取用户信息访问权限失败
  }
});

搜索用户​

按用户应用号精确搜索​

您可以使用 searchUserProfileByUniqueId 方法通过用户应用号搜索用户。

示例代码​

TypeScript
let uniqueId = "uniqueId";
IMEngine.getInstance().searchUserProfileByUniqueId(uniqueId).then((result: IAsyncResult<UserProfile>) => {
  if (result.code === EngineError.Success) {
    // 搜索用户信息成功
  } else {
    // 搜索用户信息失败
  }
});

用户信息&权限变更订阅​

监听订阅事件​

为了及时接收订阅事件的变更通知，您需要在应用调用 IMLib SDK 的初始化之后，且在调用 IMLib SDK 的连接之前设置订阅监听器。

订阅事件的变更，需要根据 SubscribeType 订阅类型来处理对应的业务，等于 SubscribeTypeUserProfile 时代表用户信息托管。

提示

从 25.12.0 版本开始，SubscribeType 包含了在线状态订阅 SubscribeTypeOnlineStatus(1)、用户信息托管 SubscribeTypeUserProfile(2)、好友在线状态订阅 SubscribeTypeFriendOnlineStatus(3)、好友用户信息托管 SubscribeTypeFriendUserProfile(4) 这四种类型。

示例代码​

TypeScript
let listener: SubscribeEventListener = {
  onEventChange: (events: Array<SubscribeInfoEvent>) => {
    // 订阅事件变化
  },
  onSubscriptionSyncCompleted: (type: SubscribeType) => {
    // 订阅同步完成
  },
  onSubscriptionChangedOnOtherDevices: (events: Array<SubscribeEvent>) => {
    // 订阅在其他设备上发生变化
  }
}
IMEngine.getInstance().addSubscribeEventListener(listener);

订阅用户信息&权限变更​

当您需要跟踪其他用户信息和权限的变更时，可以使用 subscribeEvent 方法订阅用户信息变更事件。

  1. 您需要创建订阅请求对象 SubscribeEventRequest，设置订阅类型为用户信息与权限变更状态 SubscribeTypeUserProfile，并设置好需要订阅的所有用户的 userId 列表和订阅时长。需要注意您一次订阅的用户的上限为 200 个，订阅的用户数最多为 1000 个，同时您最多可以被 5000 个用户订阅。

  2. 设置订阅时间：定义一个整数值，该值表示订阅的持续时间，订阅时长的范围为 60 秒到 2592000 秒。

示例代码​

TypeScript
// 设置订阅类型
let subscribeType: SubscribeType = SubscribeType.SubscribeTypeUserProfile;
// 设置订阅时间，取值范围为 [60, 2592000]（单位：秒）
let expiry: number = 180000;
// 订阅用户 userId（一次最多订阅 200 个）
let userIds = new Array<string>();
userIds.push("userId1");
userIds.push("userId2");
let request = new SubscribeEventRequest(subscribeType, expiry, userIds);
IMEngine.getInstance().subscribeEvent(request).then((result: IAsyncResult<Array<String>>) => {
  if (result.code === EngineError.Success) {
    // 订阅用户信息变更完成
  } else {
    // 订阅用户信息变更失败
  }
});

取消用户信息&权限订阅​

当您不再需要跟踪已被订阅用户的用户信息与权限变更时，您需要创建订阅请求对象 SubscribeEventRequest，设置订阅类型为订阅用户信息与权限变更状态 SubscribeTypeUserProfile，并设置好需要取消订阅用户信息与权限变更的所有用户的 userId 列表。需要注意您一次取消订阅的用户的上限为 200 个。

示例代码​

TypeScript
let subscribeType: SubscribeType = SubscribeType.SubscribeTypeUserProfile;
let expiry: number = 60;
let userIds = new Array<string>();
userIds.push("userId1");
userIds.push("userId2");
let request = new SubscribeEventRequest(subscribeType, expiry, userIds);
IMEngine.getInstance().unsubscribeEvent(request).then((result: IAsyncResult<Array<String>>) => {
  if (result.code === EngineError.Success) {
    // 取消用户信息订阅事件完成
  } else {
    // 取消用户信息订阅事件失败
  }
});

指定用户查询用户信息托管的订阅状态信息​

您可以使用 querySubscribeEvent 方法查询指定用户和订阅类型的状态信息。一次最多查询 200 个用户的订阅状态信息。

示例代码​

TypeScript
let subscribeType: SubscribeType = SubscribeType.SubscribeTypeUserProfile;
let expiry: number = 60;
let userIds = new Array<string>();
userIds.push("userId1");
userIds.push("userId2");
let request = new SubscribeEventRequest(subscribeType, expiry, userIds);
IMEngine.getInstance().querySubscribeEvent(request).then((result: IAsyncResult<Array<SubscribeInfoEvent>>) => {
  if (result.code === EngineError.Success) {
    // 查询用户信息订阅状态完成
  } else {
    // 查询用户信息订阅状态失败
  }
});

分页查询已订阅用户信息托管的用户的状态信息​

如果您需要分页获取已订阅的所有事件状态信息，可以使用 querySubscribeEventByPage 方法，并指定分页大小和起始索引。

  • pageSize：分页大小 [1~200]。
  • startIndex：第一页传 0，下一页取返回所有数据的数组数量（比如 pageSize = 20，第二页传 20，第三页传 40）。

示例代码​

TypeScript
let subscribeType: SubscribeType = SubscribeType.SubscribeTypeUserProfile;
let expiry: number = 60;
let userIds = new Array<string>();
userIds.push("userId1");
userIds.push("userId2");
let request = new SubscribeEventRequest(subscribeType, expiry, userIds);
let pageSize = 10;
let startIndex = 0;
IMEngine.getInstance().querySubscribeEventByPage(request, pageSize, startIndex).then((result: IAsyncResult<Array<SubscribeInfoEvent>>) => {
  if (result.code === EngineError.Success) {
    // 分页查询用户信息订阅状态完成
  } else {
    // 分页查询用户信息订阅状态失败
  }
});