群组功能
群组功能概述
网易云通信 SDK 提供了普通群 (TeamTypeEnum#Normal
),以及高级群 (TeamTypeEnum#Advanced
)两种形式的群聊功能。高级群拥有更多的权限操作,两种群聊形式在共有操作上保持了接口一致。在群组中,当前会话的 ID 就是群组的 ID。
- 普通群
开发手册中所提及的普通群都等同于 Demo 中的讨论组。普通群没有权限操作,适用于快速创建多人会话的场景。每个普通群只有一个管理员。管理员可以对普通群进行增减员操作,普通成员只能对普通群进行增员操作。在添加新成员的时候,并不需要经过对方同意。
- 高级群
高级群在权限上有更多的限制,权限分为群主、管理员、以及群成员。2.4.0之前版本在添加成员的时候需要对方接受邀请;2.4.0版本之后,可以设定被邀请模式(是否需要对方同意)。高级群可以覆盖所有普通群的能力,建议开发者创建时选用高级群。
群组消息
群聊消息
群聊消息收发和管理和单人聊天完全相同,仅在 SessionTypeEnum
上做了区分,详见消息收发节。
设置群聊消息提醒类型
可以对某个群设置消息提醒类型,群消息提醒分为全部提醒、仅管理员消息提醒、全部不提醒等三种,默认为全部提醒,普通群不支持设置仅管理员消息提醒。设置之后如果新消息不满足消息提醒的条件,用户仍然会收到这个消息,如果开发者使用的是网易云通信内建的消息提醒,用户收到新消息后不会再用通知栏提醒,如果用户使用的 iOS 客户端,则他将收不到该群聊消息的 APNS 推送。如果开发者自行实现状态栏提醒,可通过 Team
的 getMessageNotifyType
接口获取提醒配置,并决定是不是要显示通知。群聊消息提醒设置可以漫游。
- API 原型
/**
* 设置指定群消息通知类型
*
* @param teamId 群组ID
* @param notifyType 通知类型枚举
* @return InvocationFuture 可以设置回调函数,监听操作结果
*/
InvocationFuture<Void> muteTeam(String teamId, TeamMessageNotifyTypeEnum notifyType);
- 参数说明
参数 | 说明 |
---|---|
teamId | 群组ID |
TeamMessageNotifyTypeEnum | 消息提醒类型枚举,分别为全部提醒、仅管理员消息提醒、全部不提醒 |
- 示例
// 以设置 “仅管理员消息提醒” 为例
TeamMessageNotifyTypeEnum type = TeamMessageNotifyTypeEnum.Manager;
NIMClient.getService(TeamService.class).muteTeam(teamId, type).setCallback(new RequestCallback<Void>() {
@Override
public void onSuccess(Void param) {
// 设置成功
}
@Override
public void onFailed(int code) {
// 设置失败
}
@Override
public void onException(Throwable exception) {
// 错误
}
});
指定群成员强制推送
群消息支持设置强制推送。强制推送优先级最高,
1、打开强推开关,即使关闭消息提醒,依然能收到通知栏提醒,但是声音和震动跟随本机设置。
2、打开强推开关,即使设置了 桌面端在线时不推送,依然能收到通知栏提醒。
3、无论是否打开强推开关,设置了强推通知文本内容并且位于强推列表中的成员(若强推列表为 null,则表示本群所有成员),收到的消息提醒均显示强推通知文本。
4、强推列表可以配置需要强制推送的群成员,若为 null ,则表示该群所有群成员均收到强制推送消息。
5、打开强推开关,也打开免打扰设置。有通知栏提醒,但是没有声音和震动。
- 参数说明
MemberPushOption 接口说明
返回值 | MemberPushOption接口 | 说明 |
---|---|---|
List |
getForcePushList() | 返回强制推送的账号列表 |
String | getForcePushContent() | 返回强制推送的文案 |
boolean | isForcePush() | 返回是否强制推送 |
void | setForcePush(boolean forcePush) | 设置是否强推。 针对 forcePushList 里的帐号, false 为不强推,true 为强推,默认为 true。 对于 forcePushList 中的用户,推送文案为 forcePushContent; 对于不在 forcePushList 中的用户,推送文案为 pushContent; 针对在 forcePushList 中的账号: isForcePush 为true 时,推送文案中不会包含发送者 nick,直接为 forcePushContent; isForcePush 为 false 时,推送文案中目前包含了发送者 nick(暂定),即为 fromNick:forcePushContent |
void | setForcePushList(List |
设置强推列表, 填 null 表示强推给该会话所有成员, 不为 null 时最大上限账号为100个 |
void | setForcePushContent(String forcePushContent) | 强推文案(可扩展为区别与普通推送的推送文案),目前限制为500字以内 |
- 示例
// 该帐号为示例,请先注册
String account = "testAccount";
// 群聊才有强推消息
SessionTypeEnum sessionType = SessionTypeEnum.Team;
String text = "指定推送消息";
// 创建一个文本消息
IMMessage textMessage = MessageBuilder.createTextMessage(account, sessionType, text);
// 配置指定成员推送
MemberPushOption memberPushOption = new MemberPushOption();
// 开启强制推送
memberPushOption.setForcePush(true);
// 设置强推文案
memberPushOption.setForcePushContent(textMessage.getContent());
List<String> pushList = new ArrayList<>();
pushList.add("account1");
pushList.add("account2");
// 设置指定推送列表
memberPushOption.setForcePushList(pushList);
textMessage.setMemberPushOption(memberPushOption);
// 发送给对方
NIMClient.getService(MsgService.class).sendMessage(textMessage, false);
群已读回执
发送群已读回执消息
IMMessage 新增接口
返回值 | IMMessage部分接口 | 说明 |
---|---|---|
boolean | needMsgAck() | 是否需要消息已读(主要针对群消息) |
void | setMsgAck() | 设置该消息为需要消息已读的 |
boolean | hasSendAck() | 是否已经发送过群消息已读回执 |
- 示例
// 创建待发送消息
IMMessage message = MessageBuilder.createTextMessage(sessionId, SessionTypeEnum.Team, "content");
// 标记该消息需要已读回执反馈
message.setMsgAck();
// 发送消息
NIMClient.getService(MsgService.class).sendMessage(message, false);
标记群组消息已读
- 原型
/**
* (群消息接收方)标记群组消息已读
*
* @param message 群组消息
* @return InvocationFuture 可设置回调函数,监听发送结果。
*/
InvocationFuture<Void> sendTeamMessageReceipt(IMMessage message);
一般在消息可见时发出已读回执。
- 示例
NIMSDK.getTeamService().sendTeamMessageReceipt(message)
批量刷新群组消息已读、未读的数量
- 原型
/**
* (群消息发送方)批量刷新群组消息已读、未读的数量信息,没有异步回调
* 如果已读、未读数有变更,会通过 {@link com.netease.nimlib.sdk.msg.MsgServiceObserve#observeTeamMessageReceipt(Observer, boolean)}来批量通知,没有变更则不会通知
*
* @param messages 请求刷新的群组消息集合
*/
void refreshTeamMessageReceipt(List<IMMessage> messages);
一般在加载消息进行批量刷新。反复刷新,SDK实际上不会发出网络请求。只有已读、未读数量有变更,才会通过观察者接口进行通知。该API为异步无回调接口。
- 示例
// messages为接收到的批量消息
NIMSDK.getTeamService().refreshTeamMessageReceipt(messages);
查询单条群组消息已读、未读账号列表
- 原型
/**
* (群消息发送方)查询单条群组消息已读、未读账号列表
*
* @param message 待查询的消息
* @return 该消息的已读、未读账号列表
*/
InvocationFuture<TeamMsgAckInfo> fetchTeamMessageReceiptDetail(IMMessage message);
- 示例
// message为待查询的消息
NIMSDK.getTeamService().fetchTeamMessageReceiptDetail(message).setCallback(new RequestCallback<TeamMsgAckInfo>() {
@Override
public void onSuccess(TeamMsgAckInfo param) {
// 获取成功
}
@Override
public void onFailed(int code) {
// 获取失败
}
@Override
public void onException(Throwable exception) {
// 异常
}
});
群消息已读未读数变更监听
- 原型
/**
* 注册/注销群消息已读回执观察者(群成员发出需要已读回执的消息时,当有群成员已读后,该观察者会回调)
*
* @param observer 观察者,参数为已读回执信息集合
* @param register true为注册,false为注销
*/
public void observeTeamMessageReceipt(Observer<List<TeamMessageReceipt>> observer, boolean register);
- 参数说明
TeamMessageReceipt 接口说明
返回值 | TeamMessageReceipt 接口 | 说明 |
---|---|---|
String | getMsgId() | 获取消息 id |
int | getAckCount() | 获取已读人数 |
int | getUnAckCount() | 获取未读人数 |
- 示例
// 注册监听器
NIMClient.getService(MsgServiceObserve.class).observeTeamMessageReceipt(teamMessageReceiptObserver, register);
// 监听器的实现
private Observer<List<TeamMessageReceipt>> teamMessageReceiptObserver = new Observer<List<TeamMessageReceipt>>() {
@Override
public void onEvent(List<TeamMessageReceipt> teamMessageReceipts) {
...
}
};
群组管理
获取群组
SDK 提供了两个获取自己加入的所有群的列表的接口,一个是获取所有群(包括高级群和普通群)的接口,另一个是根据类型获取列表的接口。开发者可根据实际产品需求选择使用。
1. 获取我加入的所有群组
- API 原型
异步版本:
/**
* 获取自己加入的群的列表
*
* @return InvocationFuture 可以设置回调函数,如果成功,参数为自己加入的群的列表
*/
InvocationFuture<List<Team>> queryTeamList();
同步版本
/**
* 获取自己加入的群的列表(同步版本)
*
* @return 自己加入的群的列表
*/
public List<Team> queryTeamListBlock();
- 参数说明
Team函数说明:
返回值 | Team函数 | 说明 |
---|---|---|
String | getAnnouncement() | 获取群组公告 |
long | getCreateTime() | 获取群组的创建时间 |
String | getCreator() | 获取创建群组的用户帐号 |
String | getExtension() | 获取群组扩展配置。 |
String | getExtServer() | 获取服务器设置的扩展配置。 |
String | getIcon() | 获取群头像 |
String | getId() | 获取群组ID |
String | getIntroduce() | 获取群组简介 |
int | getMemberCount() | 获取群组的总成员数 |
int | getMemberLimit() | 获取群组的成员人数上限 |
String | getName() | 获取群组名称 |
TeamBeInvite ModeEnum |
getTeamBeInviteMode() | 获取群被邀请模式:被邀请人的同意方式 |
TeamExtension UpdateModeEnum |
getTeamExtension UpdateMode() |
获取群资料扩展字段修改模式:谁可以修改群自定义属性(扩展字段) |
TeamInviteModeEnum | getTeamInviteMode() | 获取群邀请模式:谁可以邀请他人入群 |
TeamUpdateModeEnum | getTeamUpdateMode() | 获取群资料修改模式:谁可以修改群资料 |
TeamTypeEnum | getType() | 获取群组类型 |
VerifyTypeEnum | getVerifyType() | 获取申请加入群组时的验证类型 |
boolean | isAllMute() | 是否群全员禁言 |
TeamAllMuteModeEnum | getMuteMode() | 获取全员禁言模式 |
boolean | isMyTeam() | 获取自己是否在这个群里 |
boolean | mute() | 获取这个群收到新消息时要不要提醒的设置,废弃,使用getMessageNotifyType()替代 |
TeamMessageNotifyTypeEnum | getMessageNotifyType() | 获取当前账号在此群收到消息之后提醒的类型 |
void | setExtension(extension) | 设置群组扩展配置。 |
- 示例
异步请求示例:
NIMClient.getService(TeamService.class).queryTeamList().setCallback(new RequestCallback<List<Team>>() {
@Override
public void onSuccess(List<Team> teams) {
// 获取成功,teams为加入的所有群组
}
@Override
public void onFailed(int i) {
// 获取失败,具体错误码见i参数
}
@Override
public void onException(Throwable throwable) {
// 获取异常
}
});
同步请求示例:
// teams为加入的所有群组
List<Team> teams = NIMClient.getService(TeamService.class).queryTeamListBlock();
注意:这里获取的是所有我加入的群列表(退群、被移除群后,将不在返回列表中),如果需要自己退群或者被移出群的群资料,请使用下面的 queryTeam 接口。
2. 根据类型获取我加入的群组
- API 原型
异步版本:
/**
* 获取自己加入的指定类型群(讨论组/高级群)列表
*
* @param type 群类型
* @return 可以设置回调函数,如果成功,参数为加入的指定类型群列表
*/
InvocationFuture<List<Team>> queryTeamListByType(TeamTypeEnum type);
同步版本:
/**
* 获取自己加入的指定类型群(讨论组/高级群)列表(同步版本)
*
* @param type 群类型
* @return 加入的指定类型群列表
*/
public List<Team> queryTeamListByTypeBlock(TeamTypeEnum type);
- 参数说明
TeamTypeEnum属性 | 说明 |
---|---|
Advanced | 高级群,有完善的权限管理功能 |
Normal | 讨论组,仅具有基本的权限管理功能,所有人都能加入, 仅拥有者可以踢人 |
- 示例
异步版本示例:
// 以讨论组为例
NIMClient.getService(TeamService.class).queryTeamListByType(TeamTypeEnum.Normal).setCallback(new RequestCallback<List<Team>>() {
@Override
public void onSuccess(List<Team> teams) {
// 成功
}
@Override
public void onFailed(int i) {
// 失败
}
@Override
public void onException(Throwable throwable) {
// 错误
}
});
同步版本示例:
// 以高级群为例
List<Team> teams = NIMClient.getService(TeamService.class).queryTeamListByTypeBlock(TeamTypeEnum.Advanced)
创建群组
网易云通信群组分为两类:普通群和高级群,两种群组的消息功能都是相同的,区别在于管理功能。普通群所有人都可以拉人入群,除群主外,其他人都不能踢人;固定群则拥有完善的成员权限体系及管理功能。创建群的接口相同,传入不同的类型参数即可。
API 原型
/** * 创建一个群组 * * @return InvocationFuture 可以设置回调函数,如果成功,参数为创建的群组资料 */ InvocationFuture<CreateTeamResult> createTeam(Map<TeamFieldEnum, Serializable> fields, TeamTypeEnum type, String postscript, List<String> members);
参数说明
参数 | 说明 |
---|---|
fields | 群组预设资料, key为数据字段,value对应的值, 该值类型必须和field中定义的fieldType一致。 |
type | 要创建的群组类型 |
postscript | 邀请入群的附言。如果是创建临时群,该参数无效 |
members | 邀请加入的成员帐号列表 |
CreateTeamResult
说明
参数 | 说明 |
---|---|
team | 创建成功后返回的team 对象 |
failedInviteAccounts | 被邀请成员中群组数量已达上限的成员列表 |
- 示例
// 群组类型
TeamTypeEnum type = TeamTypeEnum.Advanced;
// 创建时可以预设群组的一些相关属性,如果是普通群,仅群名有效。
// fields 中,key 为数据字段,value 对对应的值,该值类型必须和 field 中定义的 fieldType 一致
HashMap<TeamFieldEnum, Serializable> fields = new HashMap<TeamFieldEnum, Serializable>();
fields.put(TeamFieldEnum.Name, teamName);
fields.put(TeamFieldEnum.Introduce, teamIntroduce);
fields.put(TeamFieldEnum.VerifyType, verifyType);
NIMClient.getService(TeamService.class).createTeam(fields, type, "", accounts)
.setCallback(new RequestCallback<Team> { ... });
申请加入群组
- API 原型
/**
* 用户申请加入群。
*
* @param tid 申请加入的群ID
* @param postscript 申请附言
* @return InvocationFuture 可以设置回调函数,如果成功,参数为群资料
*/
InvocationFuture<Team> applyJoinTeam(String tid, String postscript);
- 参数说明
参数 | 说明 |
---|---|
tid | 申请加入的群ID |
postscript | 申请附言 |
- 示例
NIMClient.getService(TeamService.class).applyJoinTeam(team.getId(), null).setCallback(new RequestCallback<Team>() {
@Override
public void onSuccess(Team team) {
// 申请成功, 等待验证入群
}
@Override
public void onFailed(int code) {
// 申请失败
}
@Override
public void onException(Throwable exception) {
// error
}
});
- 特殊错误码说明
错误码 | 说明 |
---|---|
808 | 申请已发出 |
809 | 已经在群里 |
验证入群申请
用户发出申请后,所有管理员都会收到一条系统通知,类型为 SystemMessageType#TeamApply
,具体参数解释请参考系统通知章节。管理员可选择同意或拒绝。
1. 同意入群申请
仅管理员和拥有者有此权限。如果同意入群申请,群内所有成员(包括申请者)都会收到一条消息类型为 notification
的通知消息,附件类型为 MemberChangeAttachment
。具体参数说明见消息收发章节。
- API 原型
/**
* 通过用户的入群申请
* 仅管理员和拥有者有此权限
*
* @return InvocationFuture 可以设置回调函数
*/
InvocationFuture<Void> passApply(String teamId, String account);
- 参数说明
参数 | 说明 |
---|---|
teamId | 群ID |
account | 申请入群的用户ID |
- 示例
// teamId为申请加入的群组id, account为申请入群的用户id
NIMClient.getService(TeamService.class).passApply(teamId, account).setCallback(...);
2. 拒绝入群申请
仅管理员和拥有者有此权限。如果拒绝入群申请,申请者会收到一条系统通知,类型为 SystemMessageType#RejectTeamApply
。具体参数说明见系统通知章节。
- API 原型
/**
* 拒绝用户的入群申请
* 仅管理员和拥有者有此权限
*
* @return InvocationFuture 可以设置回调函数
*/
InvocationFuture<Void> rejectApply(String teamId, String account, String reason);
- 参数说明
参数 | 说明 |
---|---|
teamId | 群ID |
account | 申请入群的用户ID |
reason | 拒绝理由,选填 |
- 示例
// teamId为申请加入的群组id, account为申请入群的用户id
NIMClient.getService(TeamService.class).rejectApply(teamId, account, "您已被拒绝").setCallback(...);
说明:任意一管理员操作后,其他管理员再操作都会失败。
邀请加入群组
普通群所有人都可以拉人入群,SDK 2.4.0之前版本高级群仅管理员和拥有者可以邀请人入群, SDK 2.4.0及以后版本高级群在创建时可以设置群邀请模式,支持仅管理员或者所有人均可拉人入群。如果在被邀请成员中存在成员的群组数量已达上限,则会返回这部分失败成员的账号。
- API 原型
/**
* 添加成员
*
* @return InvocationFuture 可以设置回调函数,监听操作结果
*/
InvocationFuture<List<String>> addMembers(String teamId, List<String> accounts);
/**
* 添加成员并设置自定义字段
*
* @return InvocationFuture 可以设置回调函数,监听操作结果
*/
InvocationFuture<List<String>> addMembersEx(String teamId, List<String> accounts, String msg, String customInfo);
- 参数说明
参数 | 说明 |
---|---|
teamId | 群组ID |
accounts | 待加入的群成员帐号列表 |
msg | 邀请附言 ,不需要的话设置为空 |
customInfo | 自定义扩展字段,不需要的话设置为空 |
- 示例
NIMClient.getService(TeamService.class).addMembers(teamId, accounts)
.setCallback(new RequestCallback<Void>() {
@Override
public void onSuccess(Void param) {
// 返回onSuccess,表示拉人不需要对方同意,且对方已经入群成功了
}
@Override
public void onFailed(int code) {
// 返回onFailed,并且返回码为810,表示发出邀请成功了,但是还需要对方同意
}
@Override
public void onException(Throwable exception) {
...
}
});
- 特殊错误码说明
错误码 | 说明 |
---|---|
810 | 高级群邀请人的情况下,发出邀请成功了,但是还需要对方同意 |
说明:被邀请的人会收到一条系统通知 (SystemMessage),类型为 SystemMessageType#TeamInvite
。用户接受该邀请后,才真正入群。可以通过 SystemMessage#getAttachObject 获取服务器设置的扩展字段,类型为TeamInviteNotify。
用户入群(普通群被拉人,高级群接受邀请)后,在收到之后的第一条消息时,群内所有成员(包括入群者)会收到一条入群消息,附件类型为 MemberChangeAttachment。若通知类型为NotificationType#InviteMember
,可以通过 MemberChangeAttachment#getExtension 获取服务器设置的扩展字段。
验证入群邀请
收到入群邀请后,用户可在系统通知中看到该邀请,并选择接受或拒绝。接受邀请后,用户真正入群。如果拒绝邀请,邀请该用户的管理员会收到一条系统通知,类型为 SystemMessageType#DeclineTeamInvite
。
1. 接受入群邀请
- API 原型
/**
* 接受别人的入群邀请
*
* @return InvocationFuture 可以设置回调函数
*/
InvocationFuture<Void> acceptInvite(String teamId, String inviter);
- 参数说明
参数 | 说明 |
---|---|
teamId | 群ID |
inviter | 邀请我的用户帐号 |
- 示例
NIMClient.getService(TeamService.class).acceptInvite(teamId, inviter).setCallback(...);
2. 拒绝入群邀请
- API 原型
/**
* 拒绝别人的入群邀请通知
*
* @return InvocationFuture 可以设置回调函数
*/
InvocationFuture<Void> declineInvite(String teamId, String inviter, String reason);
- 参数说明
参数 | 说明 |
---|---|
teamId | 群ID |
inviter | 邀请我的用户帐号 |
reason | 拒绝理由,选填 |
- 示例
NIMClient.getService(TeamService.class).declineInvite(teamId, inviter, "").setCallback(callback);
踢人出群
普通群仅拥有者可以踢人,高级群拥有者和管理员可以踢人,且管理员不能踢拥有者和其他管理员。踢人后,群内所有成员(包括被踢者)会收到一条消息类型为 notification 的 IMMessage,类型为 NotificationType#KickMember
, 附件类型为 MemberChangeAttachment
。可以通过 MemberChangeAttachment#getExtension 获取服务器设置的扩展字段。
- API 原型
/**
* 移除成员,只有创建者有此权限
*
* @return InvocationFuture 可以设置回调函数,监听操作结果
*/
InvocationFuture<Void> removeMember(String teamId, String member);
- 参数说明
参数 | 说明 |
---|---|
teamId | 群ID |
member | 被踢出的成员帐号 |
- 示例
// teamId表示群ID,account表示被踢出的成员帐号
NIMClient.getService(TeamService.class).removeMember(teamId, account).setCallback(new RequestCallback<Void>() {
@Override
public void onSuccess(Void param) {
// 成功
}
@Override
public void onFailed(int code) {
// 失败
}
@Override
public void onException(Throwable exception) {
// 错误
}
});
主动退群
普通群群主可以退群,若退群,该群没有群主。高级群除群主外,其他用户均可以主动退群。退群后,群内所有成员(包括退出者)会收到一条消息类型为 notification 的 IMMessage,附件类型为 MemberChangeAttachment
。
- API 原型
/**
* 退出群
*
* @param teamId 群ID
* @return InvocationFuture 可以设置回调函数,监听操作结果
*/
InvocationFuture<Void> quitTeam(String teamId);
- 示例
NIMClient.getService(TeamService.class).quitTeam(teamId).setCallback(new RequestCallback<Void>() {
@Override
public void onSuccess(Void param) {
// 退群成功
}
@Override
public void onFailed(int code) {
// 退群失败
}
@Override
public void onException(Throwable exception) {
// 错误
}
});
转让群组
高级群拥有者可以将群的拥有者权限转给群内的其他成员,转移后,被转让者变为新的拥有者,原拥有者变为普通成员。原拥有者还可以选择在转让的同时,直接退出该群。
- API 原型
/**
* 拥有者将群的拥有者权限转给另外一个人,转移后,另外一个人成为拥有者。
* 原拥有者变成普通成员。若参数quit为true,原拥有者直接退出该群。
*
* @return InvocationFuture 可以设置回调函数,如果成功,视参数quit值:
* quit为false:参数仅包含原拥有着和当前拥有者的(即操作者和account),权限已被更新。
* quit为true: 参数为空。
*/
InvocationFuture<List<TeamMember>> transferTeam(String tid, String account, boolean quit);
- 参数说明
参数 | 说明 |
---|---|
tid | 群ID |
account | 新任拥有者的用户帐号 |
quit | 转移时是否要同时退出该群 |
返回值 | 说明 |
---|---|
InvocationFuture | 可以设置回调函数,如果成功,视参数quit值: quit为false:参数仅包含原拥有着和当前拥有者的(即操作者和account),权限已被更新。 quit为true: 参数为空 |
返回值 | TeamMember属性 | 说明 |
---|---|---|
String | getAccount() | 群成员帐号 |
Map | getExtension() | 获取扩展字段 |
long | getJoinTime() | 获取群成员入群时间 |
String | getTeamNick() | 获取该用户在这个群内的群昵称 |
String | getTid() | 获取所在群ID |
TeamMemberType | getType() | 群成员类型 |
boolean | isInTeam() | 是否该用户是否在这个群中 |
boolean | isMute() | 是否被禁言 |
- 示例
// false表示群主转让后不退群
NIMClient.getService(TeamService.class).transferTeam(teamId, account, false)
.setCallback(new RequestCallback<List<TeamMember>>() {
@Override
public void onSuccess(List<TeamMember> members) {
// 群转移成功
}
@Override
public void onFailed(int code) {
// 群转移失败
}
@Override
public void onException(Throwable exception) {
// 错误
}
});
解散群组
仅群主有这个权限。
- API 原型
/**
* 解散群,只有群主有此权限
*
* @param teamId 群ID
* @return InvocationFuture 可以设置回调函数,监听操作结果
*/
InvocationFuture<Void> dismissTeam(String teamId);
- 示例
NIMClient.getService(TeamService.class).dismissTeam(teamId).setCallback(new RequestCallback<Void>() {
@Override
public void onSuccess(Void param) {
// 解散群成功
}
@Override
public void onFailed(int code) {
// 解散群失败
}
@Override
public void onException(Throwable exception) {
// 错误
}
});
获取群组成员
由于群组成员数据比较大,且除了进入群组成员列表界面外,其他地方均不需要群组成员列表的数据,因此 SDK 不会在登录时同步群组成员数据,而是按照按需获取的原则,当上层主动调用获取指定群的群组成员列表时,才判断是否需要同步。
群成员资料 SDK 本地存储说明: 当自己退群、或者被移出群时,本地数据库会继续保留这个群成员资料,只是设置了无效标记,此时依然可以通过 queryTeamMember 查出来该群成员资料,只是 isInTeam 将返回 false 。
1. 获取群组所有成员
- API 原型
/**
* 获取指定群的成员信息列表. <br>
* 该操作有可能只是从本地数据库读取缓存数据,也有可能会从服务器同步新的数据, 因此耗时可能会比较长。
*
* @param teamId 群ID
* @return InvocationFuture 可以设置回调函数,如果成功,参数为群的成员信息列表
*/
InvocationFuture<List<TeamMember>> queryMemberList(String teamId);
- 示例
NIMClient.getService(TeamService.class).queryMemberList(teamId).setCallback(new RequestCallbackWrapper<List<TeamMember>>() {
@Override
public void onResult(int code, final List<TeamMember> members, Throwable exception) {
...
}
});
2. 根据群 ID 和成员帐号获取群成员
如果本地群成员资料已过期, SDK 会去服务器获取最新的。
- API 原型
异步版本:
/**
* 查询群成员资料。如果本地群成员资料已过期会去服务器获取最新的。
*
* @param teamId 群ID
* @param account 群成员帐号
* @return InvocationFuture 可以设置回调函数,如果成功,参数为该群成员信息
*/
InvocationFuture<TeamMember> queryTeamMember(String teamId, String account);
同步版本(仅查询本地群资料):
/**
* 查询群成员资料。(同步版本)仅查询本地群资料
*
* @param teamId 群ID
* @param account 群成员帐号
* @return 群成员信息
*/
TeamMember queryTeamMemberBlock(String teamId, String account);
- 示例
异步版本示例:
NIMClient.getService(TeamService.class).queryTeamMember(teamId, account).setCallback(new RequestCallbackWrapper<TeamMember>() {
@Override
public void onResult(int code, TeamMember member, Throwable exception) {
...
}
});
同步版本示例:
TeamMember member = NIMClient.getService(TeamService.class).queryTeamMemberBlock(teamId, account);
提升管理员
高级群中,群主可以增加管理员。操作完成后,群内所有成员都会收到一条消息类型为 notification 的 IMMessage,附件类型为 MemberChangeAttachment
。
- API 原型
/**
* 拥有者添加管理员
* 仅拥有者有此权限
*
* @param teamId 群ID
* @param accounts 待提升为管理员的用户帐号列表
* @return InvocationFuture 可以设置回调函数,如果成功,参数为新增的群管理员列表
*/
InvocationFuture<List<TeamMember>> addManagers(String teamId, List<String> accounts);
- 参数说明
参数 | 说明 |
---|---|
teamId | 群ID |
accounts | 待提升为管理员的用户帐号列表 |
返回值 | 说明 |
---|---|
InvocationFuture | 可以设置回调函数,如果成功,参数为被撤销的群成员列表 (权限已被降为Normal)。 |
- 示例
// teamId 操作的群id, accountList为待提升为管理员的用户帐号列表
NIMClient.getService(TeamService.class).addManagers(teamId, accountList).setCallback(new RequestCallback<List<TeamMember>>() {
@Override
public void onSuccess(List<TeamMember> managers) {
// 添加群管理员成功
}
@Override
public void onFailed(int code) {
// 添加群管理员失败
}
@Override
public void onException(Throwable exception) {
// 错误
});
移除管理员
高级群中,群主可以移除管理员。操作完成后,群内所有成员都会收到一条消息类型为 notification 的 IMMessage,附件类型为 MemberChangeAttachment
。
- API 原型
/**
* 拥有者撤销管理员权限
* 仅拥有者有此权限
*
* @param teamId 群ID
* @param managers 待撤销的管理员的帐号列表
* @return InvocationFuture 可以设置回调函数,如果成功,参数为被撤销的群成员列表(权限已被降为Normal)。
*/
InvocationFuture<List<TeamMember>> removeManagers(String teamId, List<String> managers);
- 参数说明
参数 | 说明 |
---|---|
teamId | 群ID |
managers | 待撤销的管理员的帐号列表 |
返回值 | 说明 |
---|---|
InvocationFuture | 可以设置回调函数,如果成功,参数为被撤销的群成员列表 (权限已被降为Normal)。 |
- 示例
// teamid为群id, accountList为待撤销的管理员的账号列表
NIMClient.getService(TeamService.class).removeManagers(teamId, accountList).setCallback(new RequestCallback<List<TeamMember>>() {
@Override
public void onSuccess(List<TeamMember> members) {
// 移除群管理员成功
}
@Override
public void onFailed(int code) {
// 移除群管理员失败
}
@Override
public void onException(Throwable exception) {
// 错误
}
});
群成员禁言
支持管理员和群主对普通成员的禁言、解除禁言操作。
- API 原型
/**
* 禁言、解除禁言
*
* @return InvocationFuture 可以设置回调函数,监听操作结果
*/
InvocationFuture<Void> muteTeamMember(String teamId, String account, boolean mute);
- 参数说明
参数 | 说明 |
---|---|
teamId | 群组ID |
account | 被禁言、被解除禁言的账号 |
mute | true表示禁言,false表示解除禁言 |
- 示例
// 以禁言为例
NIMClient.getService(TeamService.class).muteTeamMember(teamId, account, true).setCallback(new RequestCallback<Void>() {
@Override
public void onSuccess(Void param) {
// 成功
}
@Override
public void onFailed(int code) {
// 失败
}
@Override
public void onException(Throwable exception) {
// 错误
}
});
群整体禁言
将整个群禁言,该操作仅群主或者管理员有权限。禁言操作成功之后,会回调群更新接口,影响方法 Team#getMuteMode 和 Team#isAllMute
- API 原型
/**
* 对整个群禁言、解除禁言,对普通成员生效,只有群组、管理员有权限
*
* @param teamId 群组 ID
* @param mute true表示禁言,false表示解除禁言
* @return InvocationFuture 可以设置回调函数,监听操作结果
*/
InvocationFuture<Void> muteAllTeamMember(String teamId, boolean mute);
- 示例
// members表示被禁言的成员列表
NIMClient.getService(TeamService.class).muteAllTeamMember(teamId, true));
查询被禁言群成员
该操作只返回被禁言的用户
- API 原型
/**
* 查询被禁言群成员列表
* 该操作,只返回调用TeamService#muteTeamMember(String, String, boolean) 禁言的用户。
*
* @param teamId 群ID
* @return 群成员信息列表
*/
List<TeamMember> queryMutedTeamMembers(String teamId);
- 示例
// members表示被禁言的成员列表
List<TeamMember> members = NIMClient.getService(TeamService.class).queryMutedTeamMembers(teamId);
群组资料管理
查询群组资料
1. 从本地数据库中查询群资料
如果本地没有群组资料,则去服务器查询。如果自己不在这个群中,该接口返回的可能是过期资料,如需最新的,请调用 searchTeam
接口去服务器查询。 此外 queryTeam 接口也有同步版本: queryTeamBlock 。
- API 原型
异步版本:
/**
* 查询群资料,如果本地没有群组资料,则去服务器查询。
* 如果自己不在这个群中,该接口返回的可能是过期资料,如需最新的,请调用{@link #searchTeam(String)}接口
*
* @param teamId 群ID
* @return InvocationFuture 可以设置回调函数,如果成功,参数为群资料
*/
InvocationFuture<Team> queryTeam(String teamId);
同步版本:
/**
* 查询群资料(仅查询本地,不会去服务器请求)
* 如果自己不在这个群中,该接口返回的可能是过期资料,如需最新的,请调用{@link #searchTeam(String)}接口
*
* @param teamId 群ID
* @return 群资料
*/
Team queryTeamBlock(String teamId);
注意: 同步版本的查询群资料,仅查询本地,不会去服务器请求
- 示例
异步接口示例:
NIMClient.getService(TeamService.class).queryTeam(teamId).setCallback(new RequestCallbackWrapper<Team>() {
@Override
public void onResult(int code, Team t, Throwable exception) {
if (code == ResponseCode.RES_SUCCESS) {
// 成功
} else {
// 失败,错误码见code
}
if (exception != null) {
// error
}
}
});
同步接口示例:
// teamId 为想要查询的群组 ID
Team team = NIMClient.getService(TeamService.class).queryTeamBlock(teamId);
2. 从服务器上查询群资料
用户可以直接从服务器上查询群资料
- API 原型
/**
* 从服务器上查询群资料信息
*
* @param teamId 群ID
* @return
*/
InvocationFuture<Team> searchTeam(String teamId);
- 示例
// teamId为想要查询的群组ID
NIMClient.getService(TeamService.class).searchTeam(teamId).setCallback(new RequestCallback<Team>() {
@Override
public void onSuccess(Team team) {
// 查询成功,获得群组资料
}
@Override
public void onFailed(int code) {
// 失败
}
@Override
public void onException(Throwable exception) {
// 错误
}
});
- 特殊错误码说明
错误码 | 说明 |
---|---|
803 | 查询的群id不存在 |
群资料 SDK 本地存储说明:
1. 解散群、退群或者被移出群时,本地数据库会继续保留这个群资料,只是设置了无效标记,此时依然可以通过 queryTeam 查出来该群资料,只是 isMyTeam 返回 false 。 如果用户手动清空全部本地数据,下次登录同步时,服务器不会将无效的群资料同步过来,将无法取得已退出群的群资料。
2. 群解散后,通过 searchTeam
接口从服务器查询将返回 null 。
编辑群组资料
1. 单个群属性更新
每次仅修改群的一个属性,可修改的属性查看 TeamFieldEnum
,注意: 其中的 Ext_Server
群服务器扩展字段,仅限服务端修改。
更新的value值,对应的数据类型,同样查看 TeamFieldEnum
。例如:群名 Name(ITeamService.TinfoTag.NAME, String.class),表示 value 值的数据类型为 String。验证类型 VerifyType(ITeamService.TinfoTag.JOIN_MODE, VerifyTypeEnum.class),表示 value 值的数据类型为VerifyTypeEnum。
TeamFieldEnum属性 | 说明 | 数据类型 |
---|---|---|
AllMute | 群禁言(群全员禁言),该字段只读,使用“群资料更新”接口更新该字段无效。 | TeamAllMuteModeEnum |
Announcement | 群公告 | String |
BeInviteMode | 群被邀请模式:被邀请人的同意方式 | TeamBeInviteModeEnum |
Ext_Server | 群扩展字段(仅服务端能够修改) | String |
Extension | 群扩展字段(客户端自定义信息) | String |
ICON | 群头像 | String |
Introduce | 群简介 | String |
InviteMode | 群邀请模式:谁可以邀请他人入群 | TeamInviteModeEnum |
Name | 群名 | String |
TeamExtensionUpdateMode | 群资料扩展字段修改模式: 谁可以修改群自定义属性(扩展字段) |
TeamExtensionUpdateModeEnum |
TeamUpdateMode | 群资料修改模式:谁可以修改群资料 | TeamUpdateModeEnum |
undefined | 未定义的域 | |
VerifyType | 申请加入群组的验证模式 | VerifyTypeEnum |
MaxMemberCount | 指定创建群组的最大群成员数量 | int |
修改后,群内所有成员会收到一条消息类型为 notification 的 IMMessage,带有一个消息附件,类型为 UpdateTeamAttachment
。如果注册了群组资料变化观察者,观察者也会收到通知,见监听群组资料变化。
- API 原型
/**
* 更新群组资料
*
* @return InvocationFuture 可以设置回调函数,监听操作结果
*/
InvocationFuture<Void> updateTeam(String teamId, TeamFieldEnum field, Serializable value);
- 参数说明
参数 | 说明 |
---|---|
teamId | 群ID |
field | 待更新的域 |
value | 待更新的域的新值 该值类型必须和field中定义的fieldType一致 |
- 示例
以群公告为例
String announcement = "这是更新的群公告";
NIMClient.getService(TeamService.class).updateTeam(teamId, TeamFieldEnum.Announcement, announcement).setCallback(new RequestCallback<Void>() {
@Override
public void onSuccess(Void param) {
// 成功
}
@Override
public void onFailed(int code) {
// 失败
}
@Override
public void onException(Throwable exception) {
// 错误
}
});
注意: 更新群头像请注意: 需要先调用
NosService#upload
方法,将头像图片成功上传到 nos。再将 nos 的 url 地址更新到群资料。
2. 批量更新群组资料
- API 原型
/**
* 批量更新群组资料,可一次性更新多个字段的值。
*
* @return InvocationFuture 可以设置回调函数,监听操作结果
*/
InvocationFuture<Void> updateTeamFields(String teamId, Map<TeamFieldEnum, Serializable> fields);
- 参数说明
参数 | 说明 |
---|---|
teamId | 群ID |
fields | 待更新的所有字段的新的资料,其中值类型必须和field中定义的fieldType一致 |
- 示例
// 以名字,介绍,公告为例
Map<TeamFieldEnum, Serializable> fieldsMap = new HashMap<>();
fieldsMap.put(TeamFieldEnum.Name, "新的名称");
fieldsMap.put(TeamFieldEnum.Introduce, "新的介绍");
fieldsMap.put(TeamFieldEnum.Announcement, "新的公告");
NIMClient.getService(TeamService.class).updateTeamFields(teamId,
fieldsMap).setCallback(new RequestCallback<Void>() {
@Override
public void onSuccess(Void aVoid) {
// 成功
}
@Override
public void onFailed(int i) {
// 失败
}
@Override
public void onException(Throwable throwable) {
// 错误
}
});
监听群组资料变化
由于获取群组资料需要跨进程异步调用,开发者最好能在第三方 APP 中做好群组资料缓存,查询群组资料时都从本地缓存中访问。在群组资料有变化时,SDK 会告诉注册的观察者,此时,第三方 APP 可更新缓存,并刷新界面。
1. 监听群资料变化
- API 原型
/**
* 群资料变动观察者通知。新建群和群更新的通知都通过该接口传递
* @param observer 观察者, 参数为有更新的群资料列表
* @param register true为注册,false为注销
*/
public void observeTeamUpdate(Observer<List<Team>> observer, boolean register);
- 参数说明
返回值 | Team接口 | 说明 |
---|---|---|
String | getAnnouncement() | 获取群组公告 |
long | getCreateTime() | 获取群组的创建时间 |
String | getCreator() | 获取创建群组的用户帐号 |
String | getExtension() | 获取群组扩展配置 |
String | getExtServer() | 获取服务器设置的扩展配置 |
String | getIcon() | 获取群头像 |
String | getId() | 获取群组ID |
String | getIntroduce() | 获取群组简介 |
int | getMemberCount() | 获取群组的总成员数 |
int | getMemberLimit() | 获取群组的成员人数上限 |
String | getName() | 获取群组名称 |
TeamBeInviteModeEnum | getTeamBeInviteMode() | 获取群被邀请模式:被邀请人的同意方式 |
TeamExtensionUpdateModeEnum | getTeamExtensionUpdateMode() | 获取群资料扩展字段修改模式:谁可以修改群自定义属性(扩展字段) |
TeamInviteModeEnum | getTeamInviteMode() | 获取群邀请模式:谁可以邀请他人入群 |
TeamUpdateModeEnum | getTeamUpdateMode() | 获取群资料修改模式:谁可以修改群资料 |
TeamTypeEnum | getType() | 获取群组类型 |
VerifyTypeEnum | getVerifyType() | 获取申请加入群组时的验证类型 |
boolean | isAllMute() | 是否群全员禁言 |
boolean | isMyTeam() | 获取自己是否在这个群里 |
boolean | mute() | 获取这个群收到新消息时要不要提醒的设置,废弃,使用getMessageNotifyType()替代 |
TeamMessageNotifyTypeEnum | getMessageNotifyType() | 获取当前账号在此群收到消息之后提醒的类型 |
void | setExtension(String extension) | 设置群组扩展配置 |
- 示例
// 创建群组资料变动观察者
Observer<List<Team>> teamUpdateObserver = new Observer<List<Team>>() {
@Override
public void onEvent(List<Team> teams) {
}
};
// 注册/注销观察者
NIMClient.getService(TeamServiceObserver.class).observeTeamUpdate(teamUpdateObserver, register);
2. 监听移除群的变化
移除成功后,Team#isMyTeam 返回 false。
- API 原型
/**
* 移除群的观察者通知。自己退群,群被解散,自己被踢出群时,会收到该通知
* @param observer 观察者, 参数为被移除的群资料,此时群的isMyTeam接口返回false
* @param register true为注册,false为注销
*/
public void observeTeamRemove(Observer<Team> observer, boolean register);
- 示例
// 创建群组被移除的观察者。在退群,被踢,群被解散时会收到该通知。
Observer<Team> teamRemoveObserver = new Observer<Team>() {
@Override
public void onEvent(Team team) {
// 由于界面上可能仍需要显示群组名等信息,因此参数中会返回 Team 对象。
// 该对象的 isMyTeam 接口返回为 false。
}
};
// 注册/注销观察者
NIMClient.getService(TeamServiceObserver.class).observeTeamRemove(teamRemoveObserver, register);
修改群成员群昵称
普通群不支持修改成员的群昵称。
对于高级群,群主和管理员修改群内其他成员的群昵称,仅群主和管理员拥有权限。
群主可以修改所有人的群昵称。管理员只能修改普通群成员的群昵称。
- API 原型
/**
* 群组管理员修改群内其他成员的群昵称。
* 仅群管理员和拥有者有此权限
*
* @param teamId 所在群组ID
* @param account 要修改的群成员帐号
* @param nick 新的群昵称
* @return InvocationFuture 可以设置回调函数,监听操作结果
*/
InvocationFuture<Void> updateMemberNick(String teamId, String account, String nick);
- 示例
// teamId表示所在群组ID,account表示要修改的群成员帐号,nickname表示新的群昵称
NIMClient.getService(TeamService.class).updateMemberNick(teamId, account, nickname).setCallback(new RequestCallback<Void>() {
@Override
public void onSuccess(Void param) {
// 成功
}
@Override
public void onFailed(int code) {
// 失败
}
@Override
public void onException(Throwable exception) {
// 错误
}
});
修改自己的群昵称
普通群不支持修改自己的群昵称。
- API 原型
/**
* 修改自己的群昵称
*
* @param teamId 所在群组ID
* @param nick 新的群昵称
* @return InvocationFuture 可以设置回调函数,监听操作结果
*/
InvocationFuture<Void> updateMyTeamNick(String teamId, String nick);
- 示例
// test为修改后自己的群昵称
NIMClient.getService(TeamService.class).updateMyTeamNick(teamId, "test")
修改自己的群成员扩展字段
修改后,群成员会收到群成员资料变更通知
- API 原型
/**
* 修改自己的群成员扩展字段(自定义属性)
*
* @param teamId 所在群组ID
* @param extension 新的扩展字段(自定义属性)
* @return InvocationFuture 可以设置回调函数,监听操作结果
*/
InvocationFuture<Void> updateMyMemberExtension(String teamId, Map<String, Object> extension);
- 示例
Map<String, Object> extension = new HashMap<>();
extension.put("ext","newExt");
NIMClient.getService(TeamService.class).updateMyMemberExtension(teamId, ext)
监听群成员资料变化
由于获取群成员资料需要跨进程异步调用,开发者最好能在第三方 APP 中做好群成员资料缓存,查询群成员资料时都从本地缓存中访问。在群成员资料有变化时,SDK 会告诉注册的观察者,此时,第三方 APP 可更新缓存,并刷新界面。
1. 监听群成员资料变化
- API 原型
/**
* 群成员资料变化观察者通知。
* 上层APP如果管理了群成员资料的缓存,可通过此接口更新缓存。
* @param observer 观察者, 参数为有更新的群成员资料列表
* @param register true为注册,false为注销
*/
public void observeMemberUpdate(Observer<List<TeamMember>> observer, boolean register);
- 示例
// 群成员资料变化观察者通知。群组添加新成员,成员资料变化会收到该通知。
// 返回的参数为有更新的群成员资料列表。
Observer<List<TeamMember>> memberUpdateObserver = new Observer<List<TeamMember>>() {
@Override
public void onEvent(List<TeamMember> members) {
}
};
// 注册/注销观察者
NIMClient.getService(TeamServiceObserver.class).observeMemberUpdate(memberUpdateObserver, register);
2. 监听移除群成员的变化
- API 原型
/**
* 移除群成员的观察者通知。
* @param observer 观察者, 参数为被移除的群成员
* @param register true为注册,false为注销
*/
public void observeMemberRemove(Observer<TeamMember> observer, boolean register);
- 示例
// 移除群成员的观察者通知。
private Observer<TeamMember> memberRemoveObserver = new Observer<TeamMember>() {
@Override
public void onEvent(TeamMember member) {
}
};
// 注册/注销观察者
NIMClient.getService(TeamServiceObserver.class).observeMemberRemove(memberRemoveObserver, register);