用户关系托管
网易云通信提供了好友关系的托管,好友资料(用户资料)由第三方 APP 自行管理或者选择网易云通信用户资料托管,见用户资料托管。
好友关系
添加好友
1. 发出添加好友请求
- API 介绍
目前添加好友有两种验证类型(见 VerifyType
):直接添加为好友和发起好友验证请求。添加好友时需要构造 AddFriendData
,需要填入包括对方帐号,好友验证类型及附言(可选)。
VerifyType 属性说明:
VerifyType 属性 | 说明 |
---|---|
DIRECT_ADD | 直接加对方为好友 |
VERIFY_REQUEST | 发起好友验证请求 |
AddFriendData 接口说明:
返回值 | AddFriendData 接口 | 说明 |
---|---|---|
String | getAccount() | 获取帐号 |
String | getMsg() | 获取好友请求附言 |
VerifyType | getVerifyType() | 获取好友请求方式 |
- API 原型
/**
* 好友请求
*
* @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. 监听添加好友请求
- API 介绍
添加好友请求发出后,对方会收到一条 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 | 对方拒绝加你为好友 |
- API 原型
/**
* 注册/注销系统消息接收事件观察者
* @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()获取好友验证请求的附言
}
}
}
}
};
通过/拒绝对方好友请求
- API 介绍
收到好友的验证请求的系统通知后,可以通过或者拒绝,对方会收到一条系统通知,通知的事件类型为 AddFriendNotify.Event.RECV_AGREE_ADD_FRIEND 或者 AddFriendNotify.Event.RECV_REJECT_ADD_FRIEND
- API 原型
/**
* 同意/拒绝好友请求
*
* @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(...);
删除好友
- API 介绍
删除好友后,将自动解除双方的好友关系,双方的好友列表中均不存在对方。删除好友后,双方依然可以聊天。
- API 原型
/**
* 删除好友
*
* @param account 要解除好友关系的帐号
* @return InvocationFuture 可以设置回调函数。消息发送完成后才会调用,如果出错,会有具体的错误代码。
*/
InvocationFuture<Void> deleteFriend(String account);
- 示例
NIMClient.getService(FriendService.class).deleteFriend(account)
.setCallback(new RequestCallback<Void>() { ... });
监听好友关系的变化
- API 介绍
第三方 APP 应在 APP 启动后监听好友关系的变化,当主动添加好友成功、被添加为好友、主动删除好友成功、被对方解好友关系、好友关系更新、登录同步好友关系数据时都会收到通知。
- API 原型
/**
* 监听好友关系变化通知
*
* @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(); // 删除好友或者被解除好友
...
}
};
获取好友列表
- API 介绍
该方法是同步方法,返回我的好友帐号集合,可以根据帐号来获取对应的用户资料来构建自己的通讯录,见用户资料托管的构建通讯录。
- API 原型
/**
* 获取我所有的好友帐号
*
* @return 好友帐号集合
*/
List<String> getFriendAccounts();
- 示例
List<String> friends = NIMClient.getService(FriendService.class).getFriendAccounts();
根据用户账号获取好友关系
- API 介绍
该方法是同步方法。
- API 原型
/**
* 根据用户账号获取好友关系
*
* @param account 用户账号
* @return 该账号对应的好友关系
*/
Friend getFriendByAccount(String account);
- 示例
Friend friend = NIMClient.getService(FriendService.class).getFriendByAccount("account");
判断用户是否为我的好友
- API 原型
/**
* 是否为我的好友
*
* @param account 对方帐号
* @return 该帐号是否为我的好友
*/
boolean isMyFriend(String account);
- 示例
boolean isMyFriend = NIMClient.getService(FriendService.class).isMyFriend(account);
更新好友关系
- API 介绍
目前支持更新好友的备注名和好友关系扩展字段,见 FriendFieldEnum
。
FriendFieldEnum 属性说明:
FriendFieldEnum 属性 | 说明 |
---|---|
ALIAS | 备注名 |
EXTENSION | 扩展字段 |
undefined | 未定义的域 |
- API 原型
/**
* 更新好友关系
*
* @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用户依然可以看到。
加入黑名单
- API 原型
/**
* 添加用户到黑名单
*
* @param account 用户帐号
* @return InvocationFuture 可以设置回调函数。消息发送完成后才会调用,如果出错,会有具体的错误代码。
*/
InvocationFuture<Void> addToBlackList(String account);
- 示例
NIMClient.getService(FriendService.class).addToBlackList(account)
.setCallback(new RequestCallback<Void>() { ... });
移出黑名单
- API 原型
/**
* 把用户从黑名单中移除
*
* @param account 用户帐号
* @return InvocationFuture 可以设置回调函数。消息发送完成后才会调用,如果出错,会有具体的错误代码。
*/
InvocationFuture<Void> removeFromBlackList(String account);
- 示例
NIMClient.getService(FriendService.class).removeFromBlackList(user.getAccount())
.setCallback(new RequestCallback<Void>() { ... });
监听黑名单变化
- API 原型
/**
* 监听黑名单变更通知
*
* @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(); // 被移出黑名单的账号集合
...
}
};
获取黑名单列表
- API 原型
/**
* 返回黑名单中的用户列表
*
* @return 所有黑名单帐号集合
*/
List<String> getBlackList();
- 示例
List<String> accounts = NIMClient.getService(FriendService.class).getBlackList();
判断用户是否被拉进黑名单
- API 原型
/**
* 判断用户是否已被拉黑
*
* @param account 用戶帐号
* @return 该用户是否在黑名单列表中
*/
boolean isInBlackList(String account);
- 示例
boolean black = NIMClient.getService(FriendService.class).isInBlackList(account);
消息提醒
网易云通信支持对用户设置或关闭消息提醒(静音),关闭后,收到该用户发来的消息时,不再进行通知栏消息提醒。个人用户的消息提醒设置支持漫游。
设置/关闭消息提醒
- API 原型
/**
* 设置消息提醒/静音
*
* @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();
}
});
判断用户是否需要消息提醒
- API 原型
/**
* 判断用户是否需要消息提醒/静音
*
* @param account 用户帐号
* @return true表示需要消息提醒;false表示静音
*/
boolean isNeedMessageNotify(String account);
- 示例
boolean notice = NIMClient.getService(FriendService.class).isNeedMessageNotify(account);
获取所有静音帐号(不进行消息提醒的用户)
- API 原型
/**
* 获取所有不需要进行消息提醒的账号列表(静音帐号列表)
*
* @return 不需要进行消息提醒的帐号集合
*/
List<String> getMuteList();
- 示例
List<String> accounts = NIMClient.getService(FriendService.class).getMuteList();
监听消息提醒变更通知
- API 介绍
同一个账号在其他端登录时发生了消息提醒变更,会有下面回调通知:
- API 原型
/**
* 监听静音列表变更通知
*
* @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);