好友管理

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

提示

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

开通服务

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

好友事件监听

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

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

提示

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

代码示例

objc

// 添加好友事件监听
[[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 代表好友用户资料。

提示

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

objc

// 添加监听代理
[[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 个好友。

代码示例

objc

// 添加的好友用户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 个好友。

代码示例

objc

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

// 解除好友关系
[[RCCoreClient sharedCoreClient] deleteFriends:userIds directionType:directionType success:^{
    // 解除好友成功
} 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）
}];

检查好友关系

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

提示

一次最多检查 20 个用户。

代码示例

objc

// 好友用户 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	不允许任何人添加好友

代码示例

objc

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

获取加好友权限

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

代码示例

objc

// 获取好友添加权限
[[RCCoreClient sharedCoreClient] getFriendAddPermission:^(RCFriendAddPermission permission) {
    // 获取成功
} 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) {
    // 拒绝失败
}];

分页获取好友请求列表

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

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

option 参数介绍

类型: RCPagingQueryOption

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

代码示例

objc

// 查询选项
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 获取当前用户的好友列表。

代码示例

objc

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

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

根据用户 ID 获取好友信息

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

代码示例

objc

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

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

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

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

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

代码示例

Java

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

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