User Relationship
Update time: 2021/12/03 17:20:03
CommsEase provides three built-in user relations, such as friend list, blocklist, and Do Not Disturb list. The three relations are independent. The three relations can exist between two users.
Friend list
Getting the friend list
Getting accounts of all friends
The API is synchronous and returns the accounts of all friends.
- API prototype
/**
* Get accounts of all friends.
*
* @return - friend accounts.
*/
List<String> getFriendAccounts();
- Example
List<String> friends = NIMClient.getService(FriendService.class).getFriendAccounts();
Getting the profiles of all friends
- API prototype
/**
* Get the profiles of all friends.
*
* @return - Friends set.
*/
java.util.List<Friend> getFriends();
Getting the friend list by account
- API prototype
/**
* Get the friend list by user account.
*
* @param account - User account.
* @return - Corresponding friends of the account.
*/
Friend getFriendByAccount(String account);
- Example
Friend friend = NIMClient.getService(FriendService.class).getFriendByAccount("account");
Get accounts by alias
Get the list of friend accounts with specified alias from the local database.
- API prototype
/**
* Query accounts by alias.
*
* @param alias - Alias.
* @return - List of accounts.
*/
InvocationFuture<List<String>> searchAccountByAlias(String alias);
- Example
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) {
// Success.
} else {
// Failure. See the code for error code
}
if (exception != null) {
// Error
}
}
});
Getting friends by keyword
/**
* Search all friends by keyword.
*
* @param keyword - Keyword.
* @return - friend list.
*/
InvocationFuture<java.util.List<Friend>> searchFriendsByKeyword(java.lang.String keyword);
Managing the friend list
Requesting for friendship
Two verification types for adding friends (see VerifyType
): add as friend or send a friend request. By the latter, friendship can be created with the permission of the peer.
When adding friends, you must create AddFriendData
and join the account of the peer, friend verification type, and additional information (optional).
VerifyType attribute:
VerifyType attribute | Description |
---|---|
DIRECT_ADD | Add as friend. |
VERIFY_REQUEST | Send a friend request. |
AddFriendData interface:
Return | AddFriendData interface | Description |
---|---|---|
String | getAccount() | Get an account. |
String | getMsg() | Get additional information for friend requests. |
VerifyType | getVerifyType() | Get the type of friend requests. |
- API prototype
/**
* Friend requests.
*
* @param data - Friend request information (including account of the peer, verification type of friend request, P.S.)
* @return InvocationFuture - Configurable callback feature. It can be invoked only when the message is sent. If an error occurs, detailed error codes will be returned.
*/
InvocationFuture<Void> addFriend(AddFriendData data);
- Parameters
Parameter | Description |
---|---|
data | Friend request information (including account of the peer, verification type of friend request, and remark) |
- Example
final VerifyType verifyType = VerifyType.VERIFY_REQUEST; // Initiate the request for friend verification
String msg = "P.S. for friend request";
NIMClient.getService(FriendService.class).addFriend(new AddFriendData(account, verifyType, msg))
.setCallback(new RequestCallback<Void>() {... });
Response to friend requests
Accepts or rejects the received friend request.
- API prototype
/**
* Accept or reject a friend request.
*
* @param account - Account of the peer.
* @param agree - "true" indicates to accept request; "false" indicates to reject request.
* @return InvocationFuture - Configurable callback feature. It can be invoked only when the message is sent. If an error occurs, detailed error code will be returned.
*/
InvocationFuture<Void> ackAddFriendRequest(String account, boolean agree);
- Parameters
Parameter | Description |
---|---|
account | Account of the peer. |
agree | "true" indicates approve; "false" indicates reject. |
- Example
// Take "Accept friend request of the peer" for an example
NIMClient.getService(FriendService.class).ackAddFriendRequest(account, true).setCallback(...);
Listening for friendship related operations
After friends related operations are implemented, the peer will receive a system notification SystemMessage
. See System Notification.
- The field value of friends related system notification "SystemMessage - getType()" is "SystemMessageType.AddFriend".
- "getEvent()" of "AddFriendNotify" type object that is acquired through "SystemMessage - getAttachObject()" is used to get detailed operation event.
AddFriendNotify.Event attribute
AddFriendNotify.Event attribute | Description |
---|---|
RECV_ADD_FRIEND_DIRECT | The peer adds you as friend. |
RECV_ADD_FRIEND_VERIFY_REQUEST | Send friend request by the peer. |
RECV_AGREE_ADD_FRIEND | Approve friend request by the peer. |
RECV_REJECT_ADD_FRIEND | Reject friend request by the peer. |
- Example
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) {
// Handle different events.
if (attachData.getEvent() == AddFriendNotify.Event.RECV_ADD_FRIEND_DIRECT) {
// The peer adds you as friend.
} else if (attachData.getEvent() == AddFriendNotify.Event.RECV_AGREE_ADD_FRIEND) {
// The peer accepts your request for friend verification.
} else if (attachData.getEvent() == AddFriendNotify.Event.RECV_REJECT_ADD_FRIEND) {
// The peer rejects your request for friend verification.
} else if (attachData.getEvent() == AddFriendNotify.Event.RECV_ADD_FRIEND_VERIFY_REQUEST) {
// The peer requests for adding you as friends. In general scene, users may accept or reject friend request of the peer.
// Get additional information for friend verification request using message.getContent().
}
}
}
}
};
Listening for friendship changes
Friendship changes may trigger a callback:
- API prototype
/**
* Listen for notification for friends changes.
*
* @param observer - Observer. The parameter is received notification for friends change.
* @param register - "true" indicates to register Listen foring, "false" is to cancel Listen foring.
*/
void observeFriendChangedNotify(Observer<FriendChangedNotify> observer, boolean register);
- Parameters
FriendChangedNotify interface
Return | Method | Description |
---|---|---|
List | getAddedOrUpdatedFriends() | Return added or updated friends. |
List | getDeletedFriends() | Return deleted friends. |
Friend interface
Return | Method | Description |
---|---|---|
String | getAccount() | Get friend account. |
String | getAlias() | Get friend alias. |
Map | getExtension() | Get the extension field. |
String | getServerExtension() | Get the extension field of server. Only server interface can be changed. |
- Example
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(); // New added friends
List<String> deletedFriendAccounts = friendChangedNotify.getDeletedFriends(); // Deleted or removed friends
...
}
};
Delete a friend
The relationship will be relieved automatically after deleting friends. Both parties will be disappeared from the list of friends. By default, both parties can still chat with each other after deleting friends.
- API prototype
/**
* Delete friends.
*
* @param account - account whose friends are removed.
* @param deleteAlias - It determines to clear alias.
* @return InvocationFuture - Configurable callback feature. It can be invoked only when the message is sent. If an error occurs, detailed error code will be returned.
*/
InvocationFuture<java.lang.Void> deleteFriend(java.lang.String account,boolean deleteAlias);
- Example
NIMClient.getService(FriendService.class).deleteFriend(account,true)
.setCallback(new RequestCallback<Void>() {... });
Checking friendship
- API prototype
/**
* The API determines whether a user is in the friend list.
*
* @param account - Account of the peer.
* It determines that the account is in the friend list.
*/
boolean isMyFriend(String account);
- Example
boolean isMyFriend = NIMClient.getService(FriendService.class).isMyFriend(account);
Modifying friend remarks
Updates friend's alias and friend extension field. See FriendFieldEnum
.
FriendFieldEnum schema:
Field | Description |
---|---|
ALIAS | The alias of the user account. |
EXTENSION | Extension field. |
undefined | Undefined domain. |
- API prototype
/**
* Update friends.
*
* @param friendAccount - Friend account to be updated.
* @param fields - Set of all fields to be updated. It is available to update alias and extension field now.
* Notes: The maximum length of alias is 128 characters. Extension field must be input to Map; key is String; Value is Object; SDK is responsible for converting it into Json String; the maximum length is 256 characters.
* @return InvocationFuture - Configurable callback feature. It can be invoked only when the message is sent. If an error occurs, detailed error code will be returned.
*/
InvocationFuture<Void> updateFriendFields(String friendAccount, Map<FriendFieldEnum, Object> fields);
- Parameters
Parameter | Description |
---|---|
friendAccount | Friend account to be updated. |
fields | Set of all fields to be updated. You can update alias and extension field now. Notes: The maximum length of alias is 128 characters. Extension field must be input to Map; key is String; Value is Object; The SDK converts it into JSON String; the maximum length is 256 characters. |
- Example
// Update the alias.
Map<FriendFieldEnum, Object> map = new HashMap<>();
map.put(FriendFieldEnum.ALIAS, content);
NIMClient.getService(FriendService.class).updateFriendFields(data, map).setCallback(callback);
// Update the extension field.
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);
Blocklist
When a user is added to the blocklist, you will not receive any message or request from the user. For example, if user A adds user B to the blocklist, user A will not receive any message from user B. But user B can read any message sent from user A.
Getting the blocklist
- API prototype
/**
* Return the users in Blocklist.
*
* @return - all accounts in the blocklist.
*/
List<String> getBlocklist();
- Example
List<String> accounts = NIMClient.getService(FriendService.class).getBlocklist();
Adding a user to a blocklist
- API prototype
/**
* Add a user to a blocklist.
*
* @param account - User account.
* @return InvocationFuture - Configurable callback feature. It can be invoked only when the message is sent. If an error occurs, detailed error code will be returned.
*/
InvocationFuture<Void> addToBlocklist(String account);
- Example
NIMClient.getService(FriendService.class).addToBlocklist(account)
.setCallback(new RequestCallback<Void>() {... });
Remove a user from a blocklist
- API prototype
/**
* Remove a user from the blocklist.
*
* @param account - User account.
* @return InvocationFuture - Configurable callback feature. It can be invoked only when the message is sent. If an error occurs, detailed error code will be returned.
*/
InvocationFuture<Void> removeFromBlocklist(String account);
- Example
NIMClient.getService(FriendService.class).removeFromBlocklist(user.getAccount())
.setCallback(new RequestCallback<Void>() {... });
Listening for blocklist changes
- API prototype
/**
* Listen for notification for blocklist change.
*
* @param observer - Observer. The parameter is received notification for blocklist change.
* @param register - "true" indicates to register Listen foring, "false" is to cancel Listen foring.
*/
void observeBlocklistChangedNotify(Observer<BlocklistChangedNotify> observer, boolean register);
- Parameters
BlocklistChangedNotify interface:
Return | Method | Description |
---|---|---|
List | getAddedAccounts() | Return user accounts added to the blocklist. |
List | getRemovedAccounts() | Return user accounts removed from the blocklist. |
- Example
NIMClient.getService(FriendServiceObserve.class)
.observeBlocklistChangedNotify(BlocklistChangedNotifyObserver, true);
private Observer<BlocklistChangedNotify> BlocklistChangedNotifyObserver
= new Observer<BlocklistChangedNotify>() {
@Override
public void onEvent(BlocklistChangedNotify BlocklistChangedNotify) {
List<String> addedAccounts = BlocklistChangedNotify.getAddedAccounts(); // Set of accounts added to the blocklist
List<String> removedAccounts = BlocklistChangedNotify.getRemovedAccounts(); // Set of accounts removed from Blocklist
...
}
};
Determining whether a user is in the blocklist
- API prototype
/**
* The API determines whether a user is added to the blocklist.
*
* @param account - User account.
* @return - The API determines that a user is added to the blocklist.
*/
boolean isInBlocklist(String account);
- Example
boolean black = NIMClient.getService(FriendService.class).isInBlocklist(account);
Do Not Disturb setting
Sets mute for users. When the message from a user is received, you will not be reminded by notification bar, vibration and bell in the range of YunXin. Message reminding setting for individual user supports multi-client synchronization.
Get the Do Not Disturb list
- API prototype
/**
* Get the list of all accounts without message alert (list of accounts that apply Do Not Disturb).
*
* @return - Accounts without message alert.
*/
List<String> getMuteList();
- Example
List<String> accounts = NIMClient.getService(FriendService.class).getMuteList();
Do Not Disturb setting
- API prototype
/**
* Configure the Do Not Disturb setting.
*
* @return InvocationFuture - Configurable callback feature. It can be invoked only when the message is sent. If an error occurs, detailed error code will be returned.
*/
InvocationFuture<Void> setMessageNotify(String account, boolean notify);
- Parameters
Parameter | Description |
---|---|
account | Account to be set with notification. |
notify | Whether to notify the message from a user. false represents no notification. |
- Example
NIMClient.getService(FriendService.class).setMessageNotify(account, checkState)
.setCallback(new RequestCallback<Void>() {
@Override
public void onSuccess(Void param) {
if (checkState) {
Toast.makeText(UserProfileActivity.this, "Enable message alert", Toast.LENGTH_SHORT).show();
} else {
Toast.makeText(UserProfileActivity.this, "Disable message alert", Toast.LENGTH_SHORT).show();
}
});
Listening for change in the Do Not Disturb list
- API prototype
/**
* Listen for the notification for change in the Do Not Disturb list.
*
* @param observer - Observer. The parameter is received notification for change in mute list.
* @param register - "true" indicates to register Listen foring, "false" is to cancel Listen foring.
*/
void observeMuteListChangedNotify(Observer<MuteListChangedNotify> observer, boolean register);
- Parameters
MuteListChangedNotify interface
Return | Method | Description |
---|---|---|
String | getAccount() | User with change in mute setting. |
boolean | isMute() | Set that the user is muted. |
- Example
NIMClient.getService(FriendServiceObserve.class).observeMuteListChangedNotify(
new Observer<MuteListChangedNotify>() {
@Override
public void onEvent(MuteListChangedNotify notify) {
// notify.isMute() - It determines to be muted.
}
}, register);
Checking the Do Not Disturb status
- API prototype
/**
* The API determines that a user requires message alert/mute.
*
* @param account - User account.
* @return - true: to set tip, false: to set mute.
*/
boolean isNeedMessageNotify(String account);
- Example
boolean notice = NIMClient.getService(FriendService.class).isNeedMessageNotify(account);