好友管理

本文档旨在指导开发者如何使用融云即时通讯 iOS IMLib SDK 实现添加好友、删除好友、查看好友列表、管理好友等功能。

提示

好友管理功能在 5.12.0 版本开始支持。

开通服务

使用好友管理功能前，您须在控制台开通信息托管服务。

好友事件监听

为了及时接收好友添加删除、好友申请状态、好友全部清理、好友信息变更多端回调变更通知，你需要在应用调用 IMLib SDK 的初始化之后，且在调用 IMLib SDK 的连接之前，设置订阅好友事件监听器的代理委托，并实现 RCFriendEventDelegate 协议的相关代理方法。

您可以调用 addFriendEventDelegate 设置好友事件监听器。如果不想再接收好友事件，可调用 removeFriendEventDelegate 接口移除设置的监听。

提示

信息托管服务中，好友操作产生的 SDK 通知回调也是一种状态通知行为，所以不管应用中是否实现好友事件的监听，服务端都会对客户端 SDK 进行状态同步，确保本地好友关系的状态是最新的，这些通知会计入消息的分发、下行数据统计中。

示例代码

Objective C

// 添加好友事件监听
[[RCCoreClient sharedCoreClient] addFriendEventDelegate:self];

// 移除好友事件监听
[[RCCoreClient sharedCoreClient] removeFriendEventDelegate:self];

// -------- 回调事件 ----------

// 好友添加回调
- (void)onFriendAdd:(NSString *)userId 
               name:(NSString *)name
        portraitUri:(NSString *)portraitUri
      directionType:(RCDirectionType)directionType
      operationTime:(long long)operationTime {
    
}

// 好友删除回调
- (void)onFriendDelete:(NSArray<NSString *> *)userIds 
         directionType:(RCDirectionType)directionType
         operationTime:(long long)operationTime {
    
}

// 好友申请状态回调事件
- (void)onFriendApplicationStatusChanged:(NSString *)userId 
                         applicationType:(RCFriendApplicationType)applicationType
                       applicationStatus:(RCFriendApplicationStatus)status
                           directionType:(RCDirectionType)directionType
                           operationTime:(long long)operationTime
                                   extra:(NSString *)extra {
    
}

// 好友全部清理回调事件。注意：此操作只能由服务端发起
- (void)onFriendCleared:(long long)operationTime {
    
}

// 好友信息变更多端回调事件
- (void)onFriendInfoChangedSync:(NSString *)userId 
                         remark:(NSString *)remark
                     extProfile:(NSDictionary<NSString *,NSString *> *)extProfile
                  operationTime:(long long)operationTime {
    
}

好友在线状态与资料变更

IMLib SDK 会自动处理好友之间的在线状态和用户资料变更。
如果您需要接收变更事件通知，您可以在 SDK 初始化之后，建立连接之前调用 addSubscribeEventDelegate 设置变更事件监听器。

订阅事件的变更，需要根据 RCSubscribeType 订阅类型来处理对应的业务：

• RCSubscribeTypeFriendOnlineStatus 代表好友在线状态。
• RCSubscribeTypeFriendUserProfile 代表好友用户资料。

提示

您需要通过开发者后台开启“客户端好友资料变更通知”和“客户端好友在线状态变更通知”功能后，才能使用此功能，实时接收好友之间的在线状态和用户资料变更通知，通知行为也会计入单聊消息的分发、下行数据统计。

示例代码

Objective C

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

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

// ---------- 事件回调 ----------

// 事件变更回调
- (void)onEventChange:(NSArray<RCSubscribeInfoEvent *> *)subscribeEvents {
    // 需要判断 RCSubscribeInfoEvent 的 subscribeType，
    // 等于 RCSubscribeTypeFriendOnlineStatus 时代表用户信息订阅事件。
    // 等于 RCSubscribeTypeFriendUserProfile 时代表好友用户资料变更事件。
}

// 订阅数据同步完成
- (void)onSubscriptionSyncCompleted:(RCSubscribeType)type {
    // 使用 type 区分不同的订阅类型:
    // RCSubscribeTypeFriendOnlineStatus 代表好友在线状态。
    // RCSubscribeTypeFriendUserProfile 代表好友用户资料。
}

好友操作

添加好友

您可以通过调用 addFriend 接口根据用户 userId 将指定用户添加为好友，添加时可通过设置 extra 将好友申请的附加信息同步给被添加的用户。 用户 userId 的获取可以使用使用融云提供的用户搜索功能。

提示

一个用户最多可以添加 3000 个好友。

示例代码

Objective C

// 添加的好友用户Id
NSString *userId = @"userId1";
// 添加双向好友，目前仅支持双向好友，后续可能会支持其他类型
RCDirectionType directionType = RCDirectionTypeBoth;
// 发送好友请求时的附加信息，长度不超过 128 个字符
NSString *extra = @"请求添加好友";
[[RCCoreClient sharedCoreClient] addFriend:userId
                                directionType:directionType
                                        extra:extra
                                    success:^(RCErrorCode processCode) {
    // 添加好友请求成功
    if (processCode == RC_SUCCESS) {
        // 好友添加成功
    } else {
        // 等待好友同意
    }
} error:^(RCErrorCode errorCode) {
    // 添加好友请求失败
}];

设置加好友权限

您可以使用 setFriendAddPermission 设置当前用户的加好友权限，未设置时以 AppKey 默认的加好友权限为准。

加好友权限说明

• AppKey 默认用户信息权限为 需要用户同意添加好友。
• 用户的权限设置将覆盖 AppKey 的权限设置，若用户未设定自己的权限，此时将采用 AppKey 的权限设置。

加好友权限 RCFriendAddPermission 枚举介绍

枚举值	枚举说明
RCFriendAddPermissionFree	任何人直接添加好友
RCFriendAddPermissionNeedVerify	需要用户同意添加好友
RCFriendAddPermissionNoOneAllowed	不允许任何人添加好友

示例代码

objc

 // 好友添加权限，示例设置为 需要用户同意添加好友
RCFriendAddPermission permission = RCFriendAddPermissionNeedVerify;
    
// 设置好友添加权限
[[RCCoreClient sharedCoreClient] setFriendAddPermission:permission success:^{
    // 设置成功
} error:^(RCErrorCode errorCode) {
    // 设置失败
}];

获取加好友权限

您可以使用 getFriendAddPermission 获取当前用户的加好友权限。

示例代码

objc

// 获取好友添加权限
[[RCCoreClient sharedCoreClient] getFriendAddPermission:^(RCFriendAddPermission permission) {
    // 获取成功
} error:^(RCErrorCode errorCode) {
    // 获取失败
}];

不同的权限设置，会产生以下两种流程

场景1：添加好友不需要对方同意

1. 用户 A 和 B 调用 addFriendEventDelegate 设置好友事件监听。
2. 用户 B 通过 setFriendAddPermission 设置加好友权限为 : 任何人直接添加好友，详见 RCFriendAddPermission。
3. 用户 A 调用 addFriend 申请添加 B 为好友，成功回调中的 processCode 返回 RC_SUCCESS（ 0 ），表示直接加为好友，同时用户 A 和 B 都会收到好友添加回调 onFriendAdd。

场景2：添加好友需要通过对方同意

1. 用户 A 和 B 调用 addFriendEventDelegate 设置好友事件监听。
2. 用户 B 通过 setFriendAddPermission 设置加好友权限为 : 需要用户同意添加好友，详见 RCFriendAddPermission。
3. 用户 A 调用 addFriend 申请添加 B 为好友，成功回调中的 processCode 返回 RC_FRIEND_NEED_ACCEPT（ 25461 ），表示需要等待用户 B 的同意。同时用户 A 和 B 都会收到好友申请状态 onFriendApplicationStatusChanged 回调（申请状态 status 参数为 RCFriendApplicationStatusUnHandled ）。
4. 用户 B 收到 onFriendApplicationStatusChanged 回调，可以选择接受或者拒绝：
   • 用户 B 调用 acceptFriendApplication 接受好友请求，双方会收到 onFriendAdd 回调，说明好友添加成功。
   • 用户 B 调用 refuseFriendApplication 拒绝好友请求，双方都会收到 onFriendApplicationStatusChanged 回调（申请状态 status 参数为 RCFriendApplicationStatusRefused ）。

解除好友

您可以使用 deleteFriends 批量解除好友关系。如果解除好友成功，双方都会触发好友删除回调 onFriendDelete。

接口每次调用最多支持解除 100 个好友。

示例代码

Objective C

// 好友用户 ID 列表
NSArray *userIds = @[@"userId1", @"userId2"];
// 好友类型，目前只支持 RCDirectionTypeBoth
RCDirectionType directionType = RCDirectionTypeBoth;

// 解除好友关系
[[RCCoreClient sharedCoreClient] deleteFriends:userIds directionType:directionType success:^{
    // 解除好友成功
} error:^(RCErrorCode errorCode) {
    // 解除好友失败
}];

检查好友关系

您可以使用 checkFriends 检查好友关系，目前仅支持双向好友检查。

提示

一次最多检查 20 个用户。

示例代码

Objective C

// 好友用户 ID 列表
NSArray *userIds = @[@"userId1", @"userId2"];
// 好友类型，目前只支持 RCDirectionTypeBoth
RCDirectionType directionType = RCDirectionTypeBoth;

// 检查好友关系
[[RCCoreClient sharedCoreClient] checkFriends:userIds
                                directionType:directionType
                                        success:^(NSArray<RCFriendRelationInfo *> *friendRelations) {
    // 检查成功
} error:^(RCErrorCode errorCode) {
    // 检查失败
}];

好友申请操作

分页获取好友请求列表

您可以使用 getFriendApplications 查看所有发送和接收的添加好友的请求记录信息。

• 此接口成功回调中的 result 会返回 -1，代表不支持返回满足查询条件的请求列表总数。
• 好友请求处理有效期为 7 天，融云服务端最多存储 7 天的请求数据，超过 7 天后需要重新发起添加好友的请求。

接口原型

Objective C

- (void)getFriendApplications:(RCPagingQueryOption *)option
                        types:(NSArray<NSNumber *> *)types
                       status:(NSArray<NSNumber *> *)status
                      success:(void (^)(RCPagingQueryResult<RCFriendApplicationInfo *> *result))successBlock
                        error:(void (^)(RCErrorCode errorCode))errorBlock;

参数说明

类型: RCPagingQueryOption

参数	类型	描述
pageToken	NSString	分页标识, 首次拉取时， 可以传 nil 或 @""，若回调成功后返回 result (类型RCPagingQueryResult) 的 pageToken 参数如果不为 @""，则可以传入该值再次拉取，直至 pageToken 返回为 @""，表示全部拉取完成。
count	NSInteger	每页条数，一页最大不超过 100 条
order	BOOL	按申请时间排序（默认 NO 倒序， YES 为正序）

示例代码

Objective C

// 查询选项
RCPagingQueryOption *option = [[RCPagingQueryOption alloc] init];
// 每页条数
option.count = 20;
// 默认NO 为按申请操作时间倒序， YES 为正序
option.order = NO;
// 申请类型, 示例为 发送的申请 + 接收的申请
NSArray<NSNumber *> *types = @[@(RCFriendApplicationTypeSent), @(RCFriendApplicationTypeReceived)];
// 状态类型
NSArray<NSNumber *> *status = @[@(RCFriendApplicationStatusUnHandled)];

// 获取好友申请
[[RCCoreClient sharedCoreClient] getFriendApplications:option
                                                    types:types
                                                status:status
                                                success:^(RCPagingQueryResult<RCFriendApplicationInfo *> *result) {
    // 获取成功
    if (result.pageToken.length > 0) {
        // 继续获取下一页数据
        [self getFriendApplications:result.pageToken];
    } else {
        // 获取完成，没有更多数据
        for (RCFriendApplicationInfo *info in result.data) {
            if (info.applicationType == RCFriendApplicationTypeSent) {
                // 发送的申请
            }
            if (info.applicationType == RCFriendApplicationTypeReceived) {
                // 接收的申请
            }
            if (info.applicationStatus == RCFriendApplicationStatusUnHandled) {
                // 未处理的申请
            }
        }
    }
} error:^(RCErrorCode errorCode) {
    // 获取失败
}];

同意加为好友

在收到添加好友请求后，您可以调用 acceptFriendApplication 接受好友请求。触发成功回调后，好友添加成功，同时双方会触发 onFriendAdd 回调。

示例代码

objc

 // 好友用户 ID
NSString *userId = @"userId1";

// 同意好友申请
[[RCCoreClient sharedCoreClient] acceptFriendApplication:userId success:^{
    // 同意成功
} error:^(RCErrorCode errorCode) {
    // 同意失败
}];

拒绝加为好友

在收到添加好友请求后，您可以调用 refuseFriendApplication 拒绝好友请求。 拒绝成功后，双方会触发 onFriendApplicationStatusChanged 回调（申请状态 status 参数为 RCFriendApplicationStatusRefused ）。

示例代码

objc

// 好友用户 ID
NSString *userId = @"userId1";

// 拒绝好友申请
[[RCCoreClient sharedCoreClient] refuseFriendApplication:userId success:^{
    // 拒绝成功
} error:^(RCErrorCode errorCode) {
    // 拒绝失败
}];

好友信息的设置与获取

获取好友列表

您可以使用 getFriends 获取当前用户的好友列表。

示例代码

objc

// 查询方向，目前仅支持双向好友
RCQueryFriendsDirectionType directionType = RCQueryFriendsDirectionTypeBoth;

// 获取好友列表
[[RCCoreClient sharedCoreClient] getFriends:directionType success:^(NSArray<RCFriendInfo *> *friendInfos) {
    // 获取成功
} error:^(RCErrorCode errorCode) {
    // 获取失败
}];

好友信息设置

您可以使用 setFriendInfo 设置好友的备注名和扩展信息。

提示

• 您需要通过融云控制台 好友自定义属性 配置后才能使用扩展信息的 key，否则直接设置会返回设置失败，最多可设置 10 个扩展信息 key。
• 好友信息修改成功后，本用户登录的其他终端会收到好友信息变更多端回调 onFriendInfoChangedSync。
• 默认情况下，设置的资料信息不支持审核。如需审核功能，请前往[控制台]，选择应用配置>安全&审核>IM & 音视频审核>IM 信息托管配置，开启并设置需要审核的内容。

示例代码

objc

// 好友用户 ID
NSString *userId = @"userId1";
// 备注，最多为 64 个字符，不传或为空时清除备注名。
NSString *remark = @"备注";
// 扩展信息，清除时可将 kéy 对应的 value 设置为空字符串 @""
NSDictionary *extProfile = @{@"key1": @"value1", @"key2": @"value2"};

// 设置好友信息
[[RCCoreClient sharedCoreClient] setFriendInfo:userId
                                            remark:remark
                                        extProfile:extProfile
                                        success:^{
    // 设置成功
} error:^(RCErrorCode errorCode, NSArray<NSString *> * _Nullable errorKeys) {
    // 设置失败
    // errorCode == RC_SERVICE_INFORMATION_AUDIT_FAILED 时，errorKeys 会返回审核未通过的属性名（如 remark）
}];

根据好友 userId 获取好友信息

您可以使用 getFriendsInfo 根据好友的 userId 获取好友信息。
接口每次调用最多支持查询 100 个用户。

示例代码

objc

// 好友用户 ID 列表
NSArray *userIds = @[@"userId1", @"userId2"];

// 获取好友信息
[[RCCoreClient sharedCoreClient] getFriendsInfo:userIds success:^(NSArray<RCFriendInfo *> *friendInfos) {
    // 获取成功
} error:^(RCErrorCode errorCode) {
    // 获取失败
}];

根据好友昵称搜索好友信息

您可以使用 searchFriendsInfo 根据好友昵称搜索好友信息。

搜索时默认先匹配好友备注名 remark，再匹配好友名称 name。只要其中一个字段匹配成功，即返回搜索结果。

示例代码

objc

// 用户昵称关键字，不能为空最长不超过 64 个字符
NSString *name = @"name";

// 搜索好友信息
[[RCCoreClient sharedCoreClient] searchFriendsInfo:name success:^(NSArray<RCFriendInfo *> *friendInfos) {
    // 搜索成功
} error:^(RCErrorCode errorCode) {
    // 搜索失败
}];