用户关系

云信目前提供好友关系、黑名单与免打扰三种内置用户关系。三种关系互相独立,互不影响。即任意两个用户之间可以同时存在这三种关系。

好友关系

获取好友关系

获取所有好友账号

该方法是同步方法,返回我的好友帐号集合。

/**
 * 获取所有的好友帐号
 *
 * @return 好友帐号集合
 */
List<String> getFriendAccounts();
List<String> friends = NIMClient.getService(FriendService.class).getFriendAccounts();

获取所有好友信息

/**
 * 获取所有的好友关系
 *
 * @return 好友集合
 */
java.util.List<Friend> getFriends();

根据账号获取

/**
 * 根据用户账号获取好友关系
 *
 * @param account 用户账号
 * @return 该账号对应的好友关系
 */
Friend getFriendByAccount(String account);
Friend friend = NIMClient.getService(FriendService.class).getFriendByAccount("account");

根据备注名获取

从本地数据库获取具有指定备注名的好友账号列表

/**
 * 根据备注反查账号
 *
 * @param alias 备注
 * @return 账号列表
 */
InvocationFuture<List<String>> searchAccountByAlias(String alias);
NIMClient.getService(FriendService.class).searchAccountByAlias("alias").setCallback(new RequestCallbackWrapper<List<String>>() {
    @Override
    public void onResult(int code, List<String> result, Throwable exception) {
        if (code == ResponseCode.RES_SUCCESS) {
            // 成功
        } else {
            // 失败,错误码见code
        }

        if (exception != null) {
            // error
        }
    }
});

根据关键字获取

/**
 * 搜索与关键字匹配的所有好友
 *
 * @param keyword 关键字
 * @return 好友集合
 */
InvocationFuture<java.util.List<Friend>> searchFriendsByKeyword(java.lang.String keyword);

处理好友关系

申请添加好友

目前添加好友有两种验证类型(见 VerifyType):直接添加为好友和发起好友验证请求。后者需要对方同意才能建立好友关系。

添加好友时需要构造 AddFriendData,需要填入包括对方帐号,好友验证类型及附言(可选)。

VerifyType 属性说明:

VerifyType 属性 说明
DIRECT_ADD 直接加对方为好友
VERIFY_REQUEST 发起好友验证请求

AddFriendData 接口说明:

返回值 AddFriendData 接口 说明
String getAccount() 获取帐号
String getMsg() 获取好友请求附言
VerifyType getVerifyType() 获取好友请求方式
/**
 * 好友请求
 *
 * @param data 好友请求信息(包括对方帐号、好友请求验证类型、附言)
 * @return InvocationFuture 可以设置回调函数。消息发送完成后才会调用,如果出错,会有具体的错误代码。
 */
InvocationFuture<Void> addFriend(AddFriendData data);
参数 说明
data 好友请求信息(包括对方帐号、好友请求验证类型、附言)
final VerifyType verifyType = VerifyType.VERIFY_REQUEST; // 发起好友验证请求
String msg = "好友请求附言";
NIMClient.getService(FriendService.class).addFriend(new AddFriendData(account, verifyType, msg))
    .setCallback(new RequestCallback<Void>() { ... });

回应好友申请

收到好友申请后,可以通过或者拒绝该请求。

/**
 * 同意/拒绝好友请求
 *
 * @param account 对方帐号
 * @param agree   true表示同意,false表示拒绝
 * @return InvocationFuture 可以设置回调函数。消息发送完成后才会调用,如果出错,会有具体的错误代码。
 */
InvocationFuture<Void> ackAddFriendRequest(String account, boolean agree);
参数 说明
account 对方帐号
agree true 表示同意,false 表示拒绝
// 以通过对方好友请求为例
NIMClient.getService(FriendService.class).ackAddFriendRequest(account, true).setCallback(...);

监听好友相关操作

好友关系相关操作执行后,对方会收到一条系统通知 SystemMessage。具体可参见系统通知

AddFriendNotify.Event 属性说明:

AddFriendNotify.Event 属性 说明
RECV_ADD_FRIEND_DIRECT 对方直接加你为好友
RECV_ADD_FRIEND_VERIFY_REQUEST 对方发起好友验证请求
RECV_AGREE_ADD_FRIEND 对方同意加你为好友
RECV_REJECT_ADD_FRIEND 对方拒绝加你为好友
NIMClient.getService(SystemMessageObserver.class).observeReceiveSystemMsg(systemMessageObserver, register);

Observer<SystemMessage> systemMessageObserver = new Observer<SystemMessage>() {
    @Override
    public void onEvent(SystemMessage systemMessage) {
        if (systemMessage.getType() == SystemMessageType.AddFriend) {
            AddFriendNotify attachData = (AddFriendNotify) message.getAttachObject();
            if (attachData != null) {
            // 针对不同的事件做处理
                if (attachData.getEvent() == AddFriendNotify.Event.RECV_ADD_FRIEND_DIRECT) {
                // 对方直接添加你为好友
                } else if (attachData.getEvent() == AddFriendNotify.Event.RECV_AGREE_ADD_FRIEND) {
                // 对方通过了你的好友验证请求
                } else if (attachData.getEvent() == AddFriendNotify.Event.RECV_REJECT_ADD_FRIEND) {
                // 对方拒绝了你的好友验证请求
                } else if (attachData.getEvent() == AddFriendNotify.Event.RECV_ADD_FRIEND_VERIFY_REQUEST) {
                // 对方请求添加好友,一般场景会让用户选择同意或拒绝对方的好友请求。
                // 通过message.getContent()获取好友验证请求的附言
                }
            }
        }
    }
};

监听好友关系变更

好友关系出现变更后,会触发回调:

/**
 * 监听好友关系变化通知
 *
 * @param observer 观察者,参数为收到的好友关系变化通知。
 * @param register true为注册监听,false为取消监听
 */
void observeFriendChangedNotify(Observer<FriendChangedNotify> observer, boolean register);

FriendChangedNotify 接口说明:

返回值 FriendChangedNotify 接口 说明
List getAddedOrUpdatedFriends() 返回增加或者发生变更的好友关系
List getDeletedFriends() 返回被删除的的好友关系

Friend 接口说明:

返回值 Friend 接口 说明
String getAccount() 获取好友帐号
String getAlias() 获取好友备注名
Map getExtension() 获取扩展字段
String getServerExtension() 获取服务器扩展字段,仅服务器接口可修改
NIMClient.getService(FriendServiceObserve.class).observeFriendChangedNotify(friendChangedNotifyObserver, true);
private Observer<FriendChangedNotify> friendChangedNotifyObserver = new Observer<FriendChangedNotify>() {
    @Override
    public void onEvent(FriendChangedNotify friendChangedNotify) {
        List<Friend> addedOrUpdatedFriends = friendChangedNotify.getAddedOrUpdatedFriends(); // 新增的好友
        List<String> deletedFriendAccounts = friendChangedNotify.getDeletedFriends(); // 删除好友或者被解除好友
        ...
    }
};

删除好友

删除好友后,将自动解除双方的好友关系,双方的好友列表中均不存在对方。删除好友后,默认情况下双方依然可以聊天。

/**
 * 删除好友
 *
 * @param account 要解除好友关系的帐号
 * @param deleteAlias 是否同时清除备注名
 * @return InvocationFuture 可以设置回调函数。消息发送完成后才会调用,如果出错,会有具体的错误代码。
 */
InvocationFuture<java.lang.Void> deleteFriend(java.lang.String account,boolean deleteAlias);
NIMClient.getService(FriendService.class).deleteFriend(account,true)
    .setCallback(new RequestCallback<Void>() { ... });

检测是否为好友

/**
 * 是否为我的好友
 *
 * @param account 对方帐号
 * @return 该帐号是否为我的好友
 */
boolean isMyFriend(String account);
boolean isMyFriend = NIMClient.getService(FriendService.class).isMyFriend(account);

修改好友备注

目前支持更新好友的备注名和好友关系扩展字段,见 FriendFieldEnum

FriendFieldEnum 属性说明:

FriendFieldEnum 属性 说明
ALIAS 备注名
EXTENSION 扩展字段
undefined 未定义的域
/**
 * 更新好友关系
 *
 * @param friendAccount 待更新的好友账号
 * @param fields        待更新的所有字段集合,目前支持更新备注名和扩展字段
 *                      注意:备注名最长128个字符,扩展字段需要传入Map,key为String,Value为Object,SDK负责转成Json String,最大长度256字符。
 * @return InvocationFuture 可以设置回调函数。消息发送完成后才会调用,如果出错,会有具体的错误代码。
 */
InvocationFuture<Void> updateFriendFields(String friendAccount, Map<FriendFieldEnum, Object> fields);
参数 说明
friendAccount 待更新的好友账号
fields 待更新的所有字段集合,目前支持更新备注名和扩展字段。
注意:备注名最长 128 个字符,扩展字段需要传入 Map,key 为 String,Value 为 Object,SDK 负责转成Json String,最大长度 256 字符。
// 更新备注名
Map<FriendFieldEnum, Object> map = new HashMap<>();
map.put(FriendFieldEnum.ALIAS, content);
NIMClient.getService(FriendService.class).updateFriendFields(data, map).setCallback(callback);

// 更新扩展字段
Map<FriendFieldEnum, Object> map = new HashMap<>();
Map<String, Object> exts = new HashMap<>();
exts.put("ext", "ext");
map.put(FriendFieldEnum.EXTENSION, exts);
NIMClient.getService(FriendService.class).updateFriendFields(data, map).setCallback(callback);

黑名单

将用户加入黑名单后,将不在收到对方发来的任何消息或者请求。例如:A用户将B用户加入黑名单,B用户发送的消息,A用户将收不到。A用户发送的消息,B用户依然可以看到。

获取黑名单列表

/**
 * 返回黑名单中的用户列表
 *
 * @return 所有黑名单帐号集合
 */
List<String> getBlackList();
List<String> accounts = NIMClient.getService(FriendService.class).getBlackList();

添加用户到黑名单

/**
 * 添加用户到黑名单
 *
 * @param account 用户帐号
 * @return InvocationFuture 可以设置回调函数。消息发送完成后才会调用,如果出错,会有具体的错误代码。
 */
InvocationFuture<Void> addToBlackList(String account);
NIMClient.getService(FriendService.class).addToBlackList(account)
    .setCallback(new RequestCallback<Void>() { ... });

将用户从黑名单移除

/**
 * 把用户从黑名单中移除
 *
 * @param account 用户帐号
 * @return InvocationFuture 可以设置回调函数。消息发送完成后才会调用,如果出错,会有具体的错误代码。
 */
InvocationFuture<Void> removeFromBlackList(String account);
NIMClient.getService(FriendService.class).removeFromBlackList(user.getAccount())
    .setCallback(new RequestCallback<Void>() { ... });

监听黑名单变更

/**
 * 监听黑名单变更通知
 *
 * @param observer 观察者,参数为收到的黑名单变化通知。
 * @param register true为注册监听,false为取消监听
 */
void observeBlackListChangedNotify(Observer<BlackListChangedNotify> observer, boolean register);

BlackListChangedNotify 接口说明:

返回值 BlackListChangedNotify 接口 说明
List getAddedAccounts() 返回被加入到黑名单的用户账号
List getRemovedAccounts() 返回移出黑名单的用户账号
NIMClient.getService(FriendServiceObserve.class)
    .observeBlackListChangedNotify(blackListChangedNotifyObserver, true);

private Observer<BlackListChangedNotify> blackListChangedNotifyObserver
    = new Observer<BlackListChangedNotify>() {
    @Override
    public void onEvent(BlackListChangedNotify blackListChangedNotify) {
        List<String> addedAccounts = blackListChangedNotify.getAddedAccounts();  // 被拉黑的账号集合
        List<String> removedAccounts = blackListChangedNotify.getRemovedAccounts(); // 被移出黑名单的账号集合
        ...
    }
};

判断是否已拉黑

/**
 * 判断用户是否已被拉黑
 *
 * @param account 用戶帐号
 * @return 该用户是否在黑名单列表中
 */
boolean isInBlackList(String account);
boolean black = NIMClient.getService(FriendService.class).isInBlackList(account);

免打扰

云信支持对用户设置免打扰,收到该用户发来的消息时,云信范围内不再进行通知栏、振动与响铃在内的提醒。个人用户的消息提醒设置支持多端同步。

获取免打扰列表

/**
 * 获取所有不需要进行消息提醒的账号列表(免打扰帐号列表)
 *
 * @return 不需要进行消息提醒的帐号集合
 */
List<String> getMuteList();
List<String> accounts = NIMClient.getService(FriendService.class).getMuteList();

设置免打扰

/**
 * 设置免打扰
 *
 * @return InvocationFuture 可以设置回调函数。消息发送完成后才会调用,如果出错,会有具体的错误代码。
 */
InvocationFuture<Void> setMessageNotify(String account, boolean notify);
参数 说明
account 要设置消息提醒的帐号
notify 是否提醒该用户发来的消息,false 为不提醒
NIMClient.getService(FriendService.class).setMessageNotify(account, checkState)
    .setCallback(new RequestCallback<Void>() {
        @Override
        public void onSuccess(Void param) {
            if (checkState) {
                Toast.makeText(UserProfileActivity.this, "开启消息提醒", Toast.LENGTH_SHORT).show();
            } else {
                Toast.makeText(UserProfileActivity.this, "关闭消息提醒", Toast.LENGTH_SHORT).show();
            }
});

监听免打扰列表变更

/**
 * 监听免打扰列表变更通知
 *
 * @param observer 观察者,参数为免打扰列表变更通知。
 * @param register true为注册监听,false为取消监听
 */
void observeMuteListChangedNotify(Observer<MuteListChangedNotify> observer, boolean register);

MuteListChangedNotify 接口说明:

返回值 MuteListChangedNotify 接口 说明
String getAccount() 免打扰发生变化的用户
boolean isMute() 该用户是否被免打扰
NIMClient.getService(FriendServiceObserve.class).observeMuteListChangedNotify(
    new Observer<MuteListChangedNotify>() {
        @Override
        public void onEvent(MuteListChangedNotify notify) {
            // notify.isMute() 是否被免打扰
        }
    }, register);

判断是否免打扰

/**
 * 判断用户是否需要消息提醒/免打扰
 *
 * @param account 用户帐号
 * @return true表示需要提醒;false表示免打扰
 */
boolean isNeedMessageNotify(String account);
boolean notice = NIMClient.getService(FriendService.class).isNeedMessageNotify(account);