跳到主要内容

用户信息托管

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

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

提示

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

开通服务​

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

管理用户信息​

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

设置用户信息​

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

提示

默认情况下，您设置的资料信息不会进行审核。如需要开通审核功能，请前往融云控制台 IM 服务 > 功能配置 > 安全&审核 > IM 信息托管审核，开启并设置需要审核的内容。

接口​

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

参数说明​

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

属性名类型描述
namestring昵称，长度不超过 32 个字符。
portraitUristring头像地址，长度不超过 128 个字符。
uniqueIdstring用户应用号，支持大小写字母、数字，长度不超过 32 个字符。请注意 SDK 不支持设置此字段。
emailstringEmail，长度不超过 128 个字符。
birthdaystring生日，长度不超过 32 个字符。
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 {
    // 分页查询用户信息订阅状态失败
  }
});
最后于 更新