好友管理

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

提示

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

开通服务

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

好友事件监听

好友事件定义在 FriendEventListener 中，包含好友添加删除、好友申请状态、好友全部清理、好友信息变更多端回调，好友的在线状态与用户资料：点击。
您可以调用 setFriendEventListener 设置好友事件监听器，如果不想再接收好友事件，接口传 null 即可。

提示

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

代码示例

FriendEventListener friendEventListener = new FriendEventListener() {
    @Override
    public void onFriendAdd(DirectionType directionType, String userId, String name, String portraitUri, long operationTime) {
        // 好友添加回调
    }

    @Override
    public void onFriendDelete(DirectionType directionType, List<String> userIds, long operationTime) {
        // 好友删除回调
    }

    @Override
    public void onFriendApplicationStatusChanged(String userId, FriendApplicationType applicationType, FriendApplicationStatus status, DirectionType directionType, long operationTime, String extra) {
        // 好友申请状态回调事件
    }

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

    @Override
    public void onFriendInfoChangedSync(String userId, String remark, Map<String, String> extProfile, long operationTime) {
        // 好友信息变更多端回调事件
    }
};
RongCoreClient.getInstance().setFriendEventListener(friendEventListener);

好友在线状态与资料变更

好友之间的在线状态和用户资料变更，无需调用 subscribeEvent 接口主动订阅。

为了接收好友在线状态和资料事件的变更通知,您需要设置订阅监听器。监听器需要在连接之前调用。

订阅事件的变更，需要根据 SubscribeType 订阅类型来处理对应的业务， FRIEND_ONLINE_STATUS(3) 时代表好友在线状态；FRIEND_USER_PROFILE(4) 代表好友资料。

提示

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

RongCoreClient.getInstance().addSubscribeEventListener(new OnSubscribeEventListener() {
    /**
     * @param subscribeEvents 订阅事件的列表，包含所有发生变化的事件。
     * 被订阅者发生状态变更时，SubscribeEvent.operationType 无值。
     * 订阅过期没有通知， 开发者需自行关注过期时间。
     * 注意：需要判断 SubscribeInfoEvent 的 SubscribeType， 等于 FRIEND_ONLINE_STATUS 代表好友在线状态，FRIEND_USER_PROFILE 代表好友资料
     */
    @Override
    public void onEventChange(List<SubscribeInfoEvent> subscribeEvents) {

    }

    /**
     * 标记订阅数据同步完成。 该方法在订阅数据成功同步到设备或系统后调用，用于执行后续处理。
     * 注意：需要判断 SubscribeType， 等于 FRIEND_ONLINE_STATUS 代表好友在线状态，FRIEND_USER_PROFILE 代表好友资料
     *
     * @param type 同步完成的类型。需要通过根据类型来判断具体是哪种业务同步完成。
     * @since 5.10.0
     */
    @Override
    public void onSubscriptionSyncCompleted(SubscribeEvent.SubscribeType type) {

    }

});

好友操作

添加好友

您可使用融云提供的用户搜索功能或自行实现用户搜索功能，搜索后调用 addFriend 接口根据用户 ID 将指定用户添加为好友。 添加时可选择是否输入好友申请的附加信息，同步给目标用户。

提示

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

代码示例

// 添加的好友用户Id
String userId = "user1";
// 添加双向好友
DirectionType directionType = DirectionType.Both;
// 发送好友请求时的附加信息，长度不超过 128 个字符
String extra = "请求添加好友";
RongCoreClient.getInstance().addFriend(userId, directionType, extra, new IRongCoreCallback.ResultCallback<IRongCoreEnum.CoreErrorCode>() {
    @Override
    public void onSuccess(IRongCoreEnum.CoreErrorCode processCode) {
        // 添加好友请求成功
    }

    @Override
    public void onError(IRongCoreEnum.CoreErrorCode e) {
        // 添加好友请求失败
    }
});

加好友权限说明

AppKey 默认用户信息权限为 需要用户同意添加好友。 下面列举了 AppKey 级权限与 用户 级权限综合说明：

AppKey 权限	用户权限	结果
Free、NeedVerify、NoOneAllowed	未设置	以 AppKey 权限设置为准
Free、NeedVerify、NoOneAllowed	设置为（Free、NeedVerify、NoOneAllowed）	以用户权限设置为准

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

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

1. 用户 A 和 B 调用 setFriendListener 设置好友事件监听。
2. 用户 B 通过 setFriendAddPermission 设置加好友权限为 : 任何人直接添加好友（Free），见 FriendAddPermission。
3. 用户 A 调用 addFriend 申请添加 B 为好友，回调 onSuccess 并且 IRongCoreEnum.CoreErrorCode 返回 SUCCESS(0)，表示直接加为好友，同时用户 A 和 B 都会收到好友添加回调 onFriendAdd。

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

1. 用户 A 和 B 调用 setFriendListener 设置好友事件监听。
2. 用户 B 通过 setFriendAddPermission 设置加好友权限为 : 需要用户同意添加好友（NeedVerify），见FriendAddPermission。
3. 用户 A 调用 addFriend 申请添加 B 为好友，回调 onSuccess 并且 IRongCoreEnum.CoreErrorCode 返回 RC_FRIEND_NEED_ACCEPT(25461)，表示需要等待用户 B 的同意，同时用户 A 和 B 都会收到好友申请状态回调 onFriendApplicationStatusChanged。
4. 用户 B 收到 onFriendApplicationStatusChanged 回调，参数 FriendApplicationStatus 为 UnHandled ，可以选择接受或者拒绝：
   • 用户 B 调用 acceptFriendApplication 接受好友请求，双方都会收到 onFriendAdd回调，说明好友添加成功。
   • 用户 B 调用 refuseFriendApplication 拒绝好友请求，双方都会收到 onFriendApplicationStatusChanged 回调，参数 FriendApplicationStatus 为 Refused。

解除好友

您可以使用 deleteFriends 批量解除好友关系。解除好友成功，双方都会收到好友删除回调 onFriendDelete。
该接口支持批量移除，您可以一次传入多个 userId 解除多个用户好友关系，最多不超过 100 个。

代码示例

// 好友用户Id列表
List<String> userIds = new ArrayList<>();
userIds.add("user1");
userIds.add("user2");
userIds.add("user3");
// 解除双向好友
DirectionType directionType = DirectionType.Both;
RongCoreClient.getInstance().deleteFriends(userIds, directionType, new IRongCoreCallback.OperationCallback() {
    @Override
    public void onSuccess() {
        // 解除好友成功
    }

    @Override
    public void onError(IRongCoreEnum.CoreErrorCode e) {
        // 解除好友失败
    }
});

好友信息设置

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

提示

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

代码示例

// 好友用户ID
String userId = "user1";
// 好友备注名，最多为 64 个字符。不传或为空时清除备注名
String remark = "user1的好友备注名";
// 扩展信息，默认最多可设置 10 个扩展信息。
Map<String, String> extProfile = new HashMap<>();
extProfile.put("ext_key_1", "ext_value_1");
extProfile.put("ext_key_2", "ext_value_2");
RongCoreClient.getInstance().setFriendInfo(userId, remark, extProfile, new IRongCoreCallback.OperationCallback() {
    @Override
    public void onSuccess() {
        // 设置好友信息成功
    }

    @Override
    public void onError(IRongCoreEnum.CoreErrorCode e) {
        // 设置好友信息失败
    }
});

检查好友关系

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

提示

一次最多检查 20 个用户。

代码示例

// 好友用户Id列表
List<String> userIds = new ArrayList<>();
userIds.add("user1");
userIds.add("user2");
userIds.add("user3");
// 检查双向好友
DirectionType directionType = DirectionType.Both;
RongCoreClient.getInstance().checkFriends(userIds, directionType, new IRongCoreCallback.ResultCallback<List<FriendRelationInfo>>() {
    @Override
    public void onSuccess(List<FriendRelationInfo> friendRelationInfos) {
        // 检查成功结果回调
    }

    @Override
    public void onError(IRongCoreEnum.CoreErrorCode e) {
        // 检查失败结果回调
    }
});

设置加好友权限

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

加好友权限 FriendAddPermission 枚举介绍：

枚举值	枚举说明
Free	任何人直接添加好友
NeedVerify	需要用户同意添加好友
NoOneAllowed	不允许任何人添加好友

代码示例

// 通过 permission 参数设置当前加好友权限为 NeedVerify
FriendAddPermission permission = FriendAddPermission.NeedVerify;
RongCoreClient.getInstance().setFriendAddPermission(permission, new IRongCoreCallback.OperationCallback() {
    @Override
    public void onSuccess() {
        // 设置加好友权限成功
    }

    @Override
    public void onError(IRongCoreEnum.CoreErrorCode e) {
        // 设置加好友权限失败
    }
});

获取加好友权限

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

代码示例

RongCoreClient.getInstance().getFriendAddPermission(new IRongCoreCallback.ResultCallback<FriendAddPermission>() {
    @Override
    public void onSuccess(FriendAddPermission permission) {
        // 获取加好友权限成功
    }

    @Override
    public void onError(IRongCoreEnum.CoreErrorCode e) {
        // 获取加好友权限失败
    }
});

好友申请

同意加为好友

在收到添加好友请求后，调用 acceptFriendApplication 接受好友请求，双方都会收到 onFriendAdd 回调，说明好友添加成功。

同时好友申请列表中的好友请求状态 FriendApplicationStatus 变为已同意(Accepted)。

代码示例

// 好友用户ID
String userId = "user1";
RongCoreClient.getInstance().acceptFriendApplication(userId, new IRongCoreCallback.OperationCallback() {
    @Override
    public void onSuccess() {
        // 同意加好友成功
    }

    @Override
    public void onError(IRongCoreEnum.CoreErrorCode e) {
        // 同意加好友失败
    }
});

拒绝加为好友

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

拒绝成功后，双方都会收到 onFriendApplicationStatusChanged 回调，好友请求状态 FriendApplicationStatus 为已拒绝(Refused)。

代码示例

// 好友用户ID
String userId = "user1";
RongCoreClient.getInstance().refuseFriendApplication(userId, new IRongCoreCallback.OperationCallback() {
    @Override
    public void onSuccess() {
        // 拒绝加好友成功
    }

    @Override
    public void onError(IRongCoreEnum.CoreErrorCode e) {
        // 拒绝加好友失败
    }
});

分页获取好友请求列表

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

• 此接口不支持返回请求总数。
• 好友请求处理有效期为 7 天，融云服务端最多存储 7 天的请求数据，超过 7 天后需要重新发起请求。

提示

分页拉取说明：

1. 首次拉取时，PagingQueryOption 的 pageToken 无需设置（不设置、设置null、设置""，效果等同）。
2. 拉取第二页需要传入首次拉取返回结果 PagingQueryResult 类型中的 pageToken。
   • 如果不为 ""，则可以传入该值再次拉取，直至 pageToken 返回为 ""，表示全部拉取完成。
   • 如果为 ""，表示没有下一页或已拉取完成，无需再次拉取。如传递 ""，将视为拉取首页数据。

代码示例

{
    // ...
    // 分页拉取参数（设置null与设置""，效果等同）
    String pageToken = "";
    getFriendApplications(pageToken);
    // ...
}

public void getFriendApplications(String pageToken) {
    // 分页请求参数
    PagingQueryOption option = new PagingQueryOption();
    // 设置分页大小，取值范围为 [1~100]。
    option.setCount(20);
    // 分页拉取参数
    option.setPageToken(pageToken);
    // 按操作时间正序、倒序获取。true：正序；false：倒序。
    option.setOrder(false);
    // 查询发送 + 接收类型的好友请求
    FriendApplicationType[] types = new FriendApplicationType[]{FriendApplicationType.Sent, FriendApplicationType.Received};
    // 查询未处理 + 已处理 + 已拒绝类型的好友请求
    FriendApplicationStatus[] status = new FriendApplicationStatus[]{FriendApplicationStatus.UnHandled, FriendApplicationStatus.Accepted, FriendApplicationStatus.Refused};
    RongCoreClient.getInstance().getFriendApplications(option, types, status, new IRongCoreCallback.PageResultCallback<FriendApplicationInfo>() {
        @Override
        public void onSuccess(PagingQueryResult<FriendApplicationInfo> result) {
            if (!TextUtils.isEmpty(result.getPageToken())) {
                // 使用返回的 pageToken 拉取下一页
                getFriendApplications(result.getPageToken());
            } else {
                // 拉取结束
            }
        }

        @Override
        public void onError(IRongCoreEnum.CoreErrorCode e) {
            // 拉取失败
        }
    });
}

获取好友列表

获取好友列表

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

代码示例

// 查询双向好友列表
QueryFriendsDirectionType type = QueryFriendsDirectionType.Both;
RongCoreClient.getInstance().getFriends(type, new IRongCoreCallback.ResultCallback<List<FriendInfo>>() {
    @Override
    public void onSuccess(List<FriendInfo> friendInfos) {
        // 查询好友列表成功
    }

    @Override
    public void onError(IRongCoreEnum.CoreErrorCode e) {
        // 查询好友列表失败
    }
});

根据用户 ID 获取好友信息

您可以使用 getFriendsInfo 根据用户 ID 获取好友信息。
该接口支持批量获取，您可以一次传入多个 userId 获取多个好友信息，最多不超过 100 个。

代码示例

// 好友用户Id列表
List<String> userIds = new ArrayList<>();
userIds.add("user1");
userIds.add("user2");
userIds.add("user3");
RongCoreClient.getInstance().getFriendsInfo(userIds, new IRongCoreCallback.ResultCallback<List<FriendInfo>>() {
    @Override
    public void onSuccess(List<FriendInfo> friendInfos) {
        // 查询好友成功
    }

    @Override
    public void onError(IRongCoreEnum.CoreErrorCode e) {
        // 查询好友失败
    }
});

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

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

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

代码示例

// 用户昵称关键字，不能为空最长不超过 64 个字符
String name = "name";
RongCoreClient.getInstance().searchFriendsInfo(name, new IRongCoreCallback.ResultCallback<List<FriendInfo>>() {
    @Override
    public void onSuccess(List<FriendInfo> friendInfos) {
        // 查询好友列表成功
    }

    @Override
    public void onError(IRongCoreEnum.CoreErrorCode e) {
        // 查询好友列表失败
    }
});