好友管理

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

提示

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

开通服务

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

好友事件监听

好友事件定义在 RCFriendEventDelegate 中，包含好友添加删除、好友申请状态、好友全部清理、好友信息变更多端回调。

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

提示

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

代码示例

// 添加好友事件监听
[[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
                                  status:(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 {
    
}

好友在线状态与资料变更

好友之间的在线状态和用户资料变更，无需调用 subscribeEvent 接口主动订阅。
若需要接收变更事件通知，您可以调用 addSubscribeEventDelegate 设置变更事件监听器。
监听器需要在 SDK 初始化之后，建立连接之前设置。

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

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

提示

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

// 添加监听代理
[[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 接口根据用户 ID 将指定用户添加为好友。 添加时可选择是否输入好友申请的附加信息，同步给目标用户。

提示

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

代码示例

// 添加的好友用户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) {
    // 添加好友请求失败
}];

加好友权限说明

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

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

场景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 个好友。

代码示例

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

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

好友信息设置

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

提示

• 扩展信息的 key 需要通过融云控制台 好友自定义属性 设置后才能使用，否则返回设置失败，最多可设置 10 个扩展信息 key。
• 好友信息修改成功后，本用户登录的其他终端会收到好友信息变更多端回调 onFriendInfoChangedSync。

代码示例

// 好友用户 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) {
    // 设置失败
}];

检查好友关系

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

提示

一次最多检查 20 个用户。

代码示例

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

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

设置加好友权限

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

加好友权限 RCFriendAddPermission 枚举介绍

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

代码示例

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

获取加好友权限

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

代码示例

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

好友申请

同意加为好友

在收到添加好友请求后，可调用 acceptFriendApplication 接受好友请求。

同意成功后，双方会收到 onFriendAdd 回调，说明好友添加成功。

代码示例

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

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

拒绝加为好友

在收到添加好友请求后，用户可以拒绝成为好友，调用 refuseFriendApplication 拒绝好友请求。

拒绝成功后，双方会收到 onFriendApplicationStatusChanged 回调（申请状态 status 参数为 RCFriendApplicationStatusRefused ）。

代码示例

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

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

分页获取好友请求列表

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

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

option 参数介绍

类型: RCPagingQueryOption

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

代码示例

// 查询选项
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) {
    // 获取失败
}];

获取好友列表

获取好友列表

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

代码示例

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

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

根据用户 ID 获取好友信息

您可以使用 getFriendsInfo 根据用户 ID 获取好友信息。
单次调用最多支持查询 100 个用户。

代码示例

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

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

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

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

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

代码示例

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

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