用户关系托管

网易云通信提供了好友关系的托管,好友资料(用户资料)由第三方 APP 自行管理或者选择网易云通信用户资料托管,见用户资料托管

好友关系

添加好友

1. 发出添加好友请求

目前添加好友有两种验证类型(见 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>() { ... });

2. 监听添加好友请求

添加好友请求发出后,对方会收到一条 SystemMessage,可以通过 SystemMessageObserver 的observeReceiveSystemMsg 函数来监听系统通知,通过 getAttachObject 函数可以获取添加好友的通知 AddFriendNotify,通知的事件类型见 AddFriendNotify.Event

AddFriendNotify.Event 属性说明:

AddFriendNotify.Event 属性 说明
RECV_ADD_FRIEND_DIRECT 对方直接加你为好友
RECV_ADD_FRIEND_VERIFY_REQUEST 对方发起好友验证请求
RECV_AGREE_ADD_FRIEND 对方同意加你为好友
RECV_REJECT_ADD_FRIEND 对方拒绝加你为好友
/**
 * 注册/注销系统消息接收事件观察者
 * @param observer 观察者, 参数为接收到的系统消息
 * @param register true为注册,false为注销
 */
public void observeReceiveSystemMsg(Observer<SystemMessage> observer, boolean register);

SystemMessage 参数说明,请参考系统通知章节。

NIMClient.getService(SystemMessageObserver.class).observeReceiveSystemMsg(systemMessageObserver, register);

Observer<SystemMessage> systemMessageObserver = new Observer<SystemMessage>() {
    @Override
    public void onEvent(SystemMessage systemMessage) {
        if (message.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()获取好友验证请求的附言
        }
    }
}
    }
};

通过/拒绝对方好友请求

收到好友的验证请求的系统通知后,可以通过或者拒绝,对方会收到一条系统通知,通知的事件类型为 AddFriendNotify.Event.RECV_AGREE_ADD_FRIEND 或者 AddFriendNotify.Event.RECV_REJECT_ADD_FRIEND

/**
 * 同意/拒绝好友请求
 *
 * @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(...);

删除好友

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

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

监听好友关系的变化

第三方 APP 应在 APP 启动后监听好友关系的变化,当主动添加好友成功、被添加为好友、主动删除好友成功、被对方解好友关系、好友关系更新、登录同步好友关系数据时都会收到通知。

/**
 * 监听好友关系变化通知
 *
 * @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(); // 删除好友或者被解除好友
        ...
    }
};

获取好友列表

该方法是同步方法,返回我的好友帐号集合,可以根据帐号来获取对应的用户资料来构建自己的通讯录,见用户资料托管的构建通讯录

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

根据用户账号获取好友关系

该方法是同步方法。

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

判断用户是否为我的好友

/**
 * 是否为我的好友
 *
 * @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,keyString,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用户依然可以看到。

加入黑名单

/**
 * 添加用户到黑名单
 *
 * @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(); // 被移出黑名单的账号集合
        ...
    }
};

获取黑名单列表

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

判断用户是否被拉进黑名单

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

消息提醒

网易云通信支持对用户设置或关闭消息提醒(静音),关闭后,收到该用户发来的消息时,不再进行通知栏消息提醒。个人用户的消息提醒设置支持漫游。

设置/关闭消息提醒

/**
 * 设置消息提醒/静音
 *
 * @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 account 用户帐号
 * @return true表示需要消息提醒;false表示静音
 */
boolean isNeedMessageNotify(String account);
boolean notice = NIMClient.getService(FriendService.class).isNeedMessageNotify(account);

获取所有静音帐号(不进行消息提醒的用户)

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

监听消息提醒变更通知

同一个账号在其他端登录时发生了消息提醒变更,会有下面回调通知:

/**
 * 监听静音列表变更通知
 *
 * @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);