用户信息托管

本文档旨在帮助开发者了解如何在融云即时通讯 iOS 客户端 SDK 中实现用户信息订阅、查询和监听，同时对用户信息与权限进行修改、查询。 通过本文档，您将了解如何获取和跟踪用户信息，以及如何在用户信息变更、订阅状态变更时接收到通知。

提示

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

开通服务

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

提示

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

管理用户信息

融云 IMLib SDK 提供了对用户信息的查询、订阅以及修改您自己的用户信息的相关接口。

设置用户信息

您可以使用 updateMyUserProfile:success:error: 接口来修改您的用户信息，您需要设置的相关用户信息可以通过创建 RCUserProfile 对象来配置相关属性。

提示

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

接口原型

Objective C

- (void)updateMyUserProfile:(RCUserProfile *)profile
               successBlock:(void (^)(void))successBlock
                 errorBlock:(nullable void (^)(RCErrorCode errorCode,  NSArray<NSString *> * _Nullable errorKeys))errorBlock;

参数说明

RCUserProfile 属性介绍：

属性名	类型	描述
name	NSString	昵称，长度不超过 32 个字符。
portraitUri	NSString	头像地址，长度不超过 128 个字符。
uniqueId	NSString	用户应用号，支持大小写字母、数字，长度不超过 32 个字符。请注意 客户端 SDK 不支持设置此字段。
email	NSString	Email，长度不超过 128 个字符。
gender	RCUserGender	性别
location	NSString	所在地，长度不超过 32 个字符。
role	NSUInteger	角色，支持 0~100 以内数字。
level	NSUInteger	级别，支持 0~100 以内数字。
userExtProfile	NSDictionary<NSString *, NSString *>	自定义扩展信息，您最多可以设置 20 个用户信息（以 Key、Value 方式设置，扩展用户信息的 Key 需在开发者后台提前进行设置） Key：支持大小写字母、数字，长度不超过 32 个字符，且需要保障是 AppKey 下唯一。当设置的 Key 不存在时，设置不成功会返回错识提示。 Value：字符串，不超过 256 个字符。 。

示例代码

Objective C

RCUserProfile *userProfile = [[RCUserProfile alloc] init];
userProfile.name = @"name";

[[RCCoreClient sharedCoreClient] updateMyUserProfile:userProfile success:^{
    // 更新成功
} error:^(RCErrorCode errorCode, NSArray<NSString *> * _Nullable errorKeys) {
    // 更新失败
    // errorCode == RC_SERVICE_INFORMATION_AUDIT_FAILED 时，errorKeys 会返回审核未通过的属性名（如 name）
}];

获取当前用户信息

您可以使用 getMyUserProfile:error: 方法获取您自己的用户信息。

示例代码

Objective C

[[RCCoreClient sharedCoreClient] getMyUserProfile:^(RCUserProfile *userProfile) {
    // 获取成功
} error:^(RCErrorCode errorCode) {
    // 获取失败
}];

批量获取他人用户信息

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

提示

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

示例代码

Objective C

NSArray *userIds = @[@"userId1", @"userId2"];
[[RCCoreClient sharedCoreClient] getUserProfiles:userIds success:^(NSArray<RCUserProfile *> *userProfiles) {
    // 获取成功
} error:^(RCErrorCode errorCode) {
    // 获取失败
}];

管理用户权限

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

RCUserProfileVisibility 枚举介绍

枚举值	用户权限
RCUserProfileVisibilityNotSet	未设置：以 AppKey 设置的权限为准，默认是此状态。
RCUserProfileVisibilityInvisible	都不可见：任何人都不能搜索到您除了名称、头像以外的用户信息。
RCUserProfileVisibilityEveryone	所有人：AppKey 下的任何用户都可以查看到您的用户信息。

用户权限说明

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

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

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

设置用户权限

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

示例代码

Objective C

[[RCCoreClient sharedCoreClient] updateMyUserProfileVisibility:RCUserProfileVisibilityEveryone success:^{
    // 修改成功
} error:^(RCErrorCode errorCode) {
    // 修改失败
}];

获取用户权限

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

示例代码

Objective C

[[RCCoreClient sharedCoreClient] getMyUserProfileVisibility:^(RCUserProfileVisibility visibility) {
    // 获取成功
} error:^(RCErrorCode errorCode) {
    // 获取失败
}];

搜索用户

按用户应用号精确搜索

您可以使用 searchUserProfileByUniqueId:success:error 方法通过用户应用号搜索用户：

示例代码

Objective C

// 使用应用号查询用户信息
[[RCCoreClient sharedCoreClient] searchUserProfileByUniqueId:@"uniqueId" success:^(RCUserProfile * _Nonnull userProfile) {
    // 查询成功
} error:^(RCErrorCode errorCode) {
    // 查询失败
}];

用户信息&权限变更订阅

监听订阅事件

为了及时接收订阅事件的变更通知，你需要在应用调用 IMLib SDK 的初始化之后，且在调用 IMLib SDK 的连接之前，设置订阅在线状态监听器的代理委托，并实现 RCSubscribeEventDelegate 协议的相关代理方法。

Objective C

// 添加监听代理
[[RCCoreClient sharedCoreClient] addSubscribeEventDelegate:self];

// 移除监听代理
[[RCCoreClient sharedCoreClient] removeSubscribeEventDelegate:self];

提示

• 从 5.10.0 版本开始，RCSubscribeType 包含了在线状态订阅 RCSubscribeTypeOnlineStatus(1)、用户信息托管 RCSubscribeTypeUserProfile(2) 这2种类型。
• 从 5.12.0 版本开始，RCSubscribeType 新增了好友在线状态订阅 RCSubscribeTypeFriendOnlineStatus(3)、好友用户信息托管 RCSubscribeTypeFriendUserProfile(4) 这2种类型。

实现代理：

1. 您在连接 IM 成功后，IMLib SDK 内部会自动同步订阅数据的变动。当订阅数据成功同步到本地设备或系统后，会触发下面的方法，您可以在此方法中执行后续业务逻辑。

   Objective C

   /// 已废弃，请使用 onSubscriptionSyncCompleted: 代替
   - (void)onSubscriptionSyncCompleted;
   
   /// 订阅数据同步完成
   /// 使用 type 区分不同的订阅类型，等于 RCSubscribeTypeOnlineStatus 时代表在线状态订阅事件。
   /// - Since: 5.10.0
   - (void)onSubscriptionSyncCompleted:(RCSubscribeType)type;

2. 当订阅事件发生变化时，您可以通过实现此方法来处理事件的变化，例如去更新用户界面或处理新的数据。通常，该方法在后台线程中被调用，因此您需要切换到主线程去更新 UI。subscribeEvents 是订阅事件的列表，包含所有发生变化的事件。 请注意，订阅过期没有通知，所以您需自行关注过期时间。

   Objective C

   /// 注意：从 5.10.0 版本开始，需要判断 RCSubscribeInfoEvent 的 subscribeType，等于 RCSubscribeTypeOnlineStatus 时代表在线状态订阅事件。
   - (void)onEventChange:(NSArray<RCSubscribeInfoEvent *> *)subscribeEvents;

3. 当用户在其他设备上的订阅信息发生变更时，您可以在当前设备的此方法中更新当前设备上的状态信息，以保证订阅信息的一致性。 subscribeEvents 包含发生变化的订阅事件的列表。

   Objective C

   /// 从 5.10.0 版本开始，需要判断 RCSubscribeEvent 的 subscribeType，等于 RCSubscribeTypeOnlineStatus 时代表在线状态订阅事件。
   - (void)onSubscriptionChangedOnOtherDevices:(NSArray<RCSubscribeEvent *> *)subscribeEvents;

订阅用户信息&权限变更

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

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

Objective C

RCSubscribeEventRequest *request = [[RCSubscribeEventRequest alloc] init];
// 订阅的用户列表
request.userIds = @[@"userId1", @"userId2"];
// 本次订阅的类型
request.subscribeType = RCSubscribeTypeUserProfile;
// 订阅时长，单位秒
request.expiry = 180000;

2. 您通过调用 subscribeEvent:completion: 方法传入第一步设置好的 RCSubscribeEventRequest 对象执行订阅操作。

Objective C

[[RCCoreClient sharedCoreClient] subscribeEvent:request completion:^(RCErrorCode status, NSArray<NSString *> * _Nullable failedUserIds) {
    if (RC_SUCCESS == status) {
        // 订阅成功
    }
}];

取消订阅用户信息&权限变更

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

Objective C

RCSubscribeEventRequest *request = [[RCSubscribeEventRequest alloc] init];
request.subscribeType = RCSubscribeTypeUserProfile;
request.userIds = @[@"userId1", @"userId2"];

2. 您通过调用 unSubscribeEvent:completion: 方法传入第一步设置好的 RCSubscribeEventRequest 对象取消对传入的所有用户的用户信息与权限变更的订阅。

Objective C

[[RCCoreClient sharedCoreClient] unSubscribeEvent:request completion:^(RCErrorCode status, NSArray<NSString *> * _Nullable failedUserIds) {
    if (RC_SUCCESS == status) {
        // 取消订阅成功
    }
}];

查询订阅用户信息&权限变更状态

1. 当您需要查询指定用户的用户信息与权限变更状态信息时，您需要创建订阅请求对象 RCSubscribeEventRequest，设置订阅类型为订阅用户信息与权限变更状态 RCSubscribeTypeUserProfile，并设置好需要查询订阅用户信息与权限变更状态的所有用户的 userId 列表，需要注意您一次查询订阅的用户的上限为 200 个。

Objective C

RCSubscribeEventRequest *request = [[RCSubscribeEventRequest alloc] init];
request.subscribeType = RCSubscribeTypeUserProfile;
request.userIds = @[@"userId1", @"userId2"];

2. 您通过调用 querySubscribeEvent:completion: 方法传入第一步设置好的 RCSubscribeEventRequest 对象查询传入的所有用户的用户信息与权限变更状态信息。

Objective C

[[RCCoreClient sharedCoreClient] querySubscribeEvent:request completion:^(RCErrorCode status, NSArray<RCSubscribeInfoEvent *> * _Nullable subscribeEvents) {
    if (RC_SUCCESS == status) {
        // 查询成功
    }
}];

分页查询订阅用户信息&权限变更状态

1. 当您需要分页查询所有已订阅用户的用户信息与权限变更信息时，您需要创建订阅请求对象 RCSubscribeEventRequest，设置订阅类型为订阅用户信息与权限变更状态 RCSubscribeTypeUserProfile。

Objective C

RCSubscribeEventRequest *request = [[RCSubscribeEventRequest alloc] init];
request.subscribeType = RCSubscribeTypeUserProfile;

2. 您通过调用 querySubscribeEvent:pageSize:startIndex:completion:方法传入第一步设置好的 RCSubscribeEventRequest 对象，同时设置好每次查询的分页的起始的值以及每页需要查询的用户的数量。

• pageSize: 每页获取的用户的数量，取值范围为[1~200]。
• startIndex: 起始索引。第一页传 0， 下一页取已经获取到的所有数据的数组数量（比如 pageSize = 20，当获取第二页时，您已经获取到了第一页的 20 条数据，所以 startIndex 设置为 20；当获取第三页时，您已经获取到了前两页的 40 条数据，所以 startIndex 设置为 40。

Objective C

[[RCCoreClient sharedCoreClient] querySubscribeEvent:request
                                            pageSize:20
                                          startIndex:0
                                          completion:^(RCErrorCode status, NSArray<RCSubscribeInfoEvent *> * _Nullable subscribeEvents) {
    if (RC_SUCCESS == status && subscribeEvents.count > 0) {
        // 查询成功
    }
}];