群组功能

功能概述

容联云通讯SDK 提供了群组和讨论组两种形式的群聊功能。群组拥有更多的权限操作，两种群聊形式在共有操作上保持了接口一致。

讨论组类似当前IM聊天应用内的快速多人会话，没有群组的权限操作，适用于快速创建多人会话的场景。每个讨论组只有一个管理员。管理员可以对讨论组进行增减员操作，普通成员也能对群进行增员操作。在添加新成员的时候，并不需要经过对方同意。

群组的功能更加完整和丰富，在权限上也拥有更多的限制（权限分为群主、管理员、以及群成员）。可以设定被邀请模式（是否需要对方同意）群组可以拥有讨论组的全部功能，推荐使用群组进行开发。

注意事项：

1、创建的群组的时候注意传入的scope参数，基础版默认可传TEMP,专业版可传NORMAL，若需更大人数群组，请联系专有云商务或在控制台吗管理页面进行拓展。

2、群组中有三种成员角色，分别是群主、管理员（默认10个，群人数超过10人），普通成员。

3、群主可以修改，群组信息，群名片，邀请人加入，踢人，解散群组，设置管理员，转让群主，设置群内禁言等。

4、管理员可以修改群组公告，群名片，邀请人加入，设置群内禁言。

群组和讨论组的详细功能差异对比如下：

功能	讨论组	群组
群容量	IM 专业版 300人/群，最大可扩展至 500 人/群(增值功能)	IM 专业版 300人/群，最大可扩展至 2000 人/群(增值功能)
创建	创建时指定群组类型	创建时指定群组类型
群资料属性	讨论组名，讨论组类型，讨论组公告，讨论组扩展字段，讨论组资料修改，讨论组扩展字段修改	群名，群公告，群扩展字段，申请加入群组的验证模式，群邀请模式，群资料修改，群资料扩展字段修改模式
邀请入群	创建时邀请	群主和管理员可以邀请
被邀请人同意模式	不需要被邀请人同意	支持配置：需要被邀请人同意不需要被邀请人同意
申请入群	不支持	支持
群成员类型	群主、普通成员	群主、管理员、普通成员
管理员设置	不支持设置管理员	群主可以增减管理员
群组资料修改权限	群主可以修改	群主，管理员可以设置
修改群成员昵称	管理修改任何人群昵称，普通群成员只能修改自己的昵称	群主、管理员可以修改所有人的群昵称。普通成员只能修改普通群成员的群昵称。
修改自己的群昵称	支持	支持
消息类型支持	文本，图片，附件，语音等	文本，图片，附件，语音等
踢人	不支持	群主和管理员可以踢人，且管理员不能踢群主和其他管理员
主动退群	普通群所有人都可以退群；若群主退群，该群第一个加入的人是群主	除群主外，其他用户均可以主动退群。群主需先将群转让给其他群成员才可以进行退群操作
禁言	不支持	管理员对普通成员禁言、解除禁言
转让群	不支持	群主可以将群的拥有者权限转给群内的其他成员，转移后，被转让者变为新的群主，原群主变为普通成员。群主还可以选择在转让的同时，直接退出该群。
解散群	不支持	群主可以解散群

群组消息

群组聊天和单人聊天是相同的，请参考消息收发文档。

群组管理

参考类: ECGroup 查看API

群组管理类：ECGroupManager查看API

创建群组

创建群包含创建群组和创建讨论组两种形式。二者的接口接口相同，传入不同的类型参数即可（Isdiscuss）。

API介绍

void createGroup(ECGroup group,ECGroupManager.OnCreateGroupListener l)
创建群组
参数:
group - 创建群组所需要的参数信息
l - 创建群组请求回调

代码示例

我们假设Tony要创建一个名为"出彩中国人"，具体代码如下：

// 构建群组参数
ECGroup group = new ECGroup();
// 设置群组名称
group.setName("出彩中国人");
// 设置群组公告
group.setDeclare("欢迎体验云通讯群组功能");
// 设置群组类型，如：ECGroup.Scope.TEMP临时群组（100人）
group.setScope(ECGroup.Scope.TEMP);
// 设置群组验证权限，如：需要身份验证ECGroup.Permission.NEED_AUTH
group.setPermission(ECGroup.Permission.NEED_AUTH);
//是否是讨论组。false代表是群组、true代表是讨论组
group.setIsdiscuss(false);
// 获得SDK群组创建管理类
ECGroupManager groupManager = ECDevice.getECGroupManager();
// 调用创建群组接口，设置创建结果回调
groupManager.createGroup(group, new ECGroupManager.OnCreatGroupListener() {
    @Override
    public void onCreatGroupComplete(ECError error, ECGroup group) {
        if(error.errorCode == SdkErrorCode.REQUEST_SUCCESS) {
            // 群组/讨论组创建成功
            // 缓存创建的群组/讨论组到数据库，同时通知UI进行更新
            return ;
        }
        // 群组/讨论组创建失败
        Log.e("ECSDK_Demo" , "create group fail , errorCode=" + error.errorCode);
    }
    @Override
    public void onComplete(ECError error) {
        // 不需要处理忽略
    }});

主动加入

只要知道群组id，就可以主动加入群组。

关于几种群组的解释：

公开群组：用户可以直接被允许加入群组，不需要群主或管理员进行验证；

验证群组：用户加入群组的时候需要群主或管理员同意才可以加入;

私有群组：只能群主或管理员邀请加入。

API介绍

void joinGroup(java.lang.String groupId,
               java.lang.String declare,
               ECGroupManager.OnJoinGroupListener l)
用户申请加入群组
参数:
groupId - 申请加入的群组ID
declare - 申请加入理由
l - 申请结果回调

代码示例

我们假设"出彩中国人"群组已经有Tony和John两位成员，现在Smith要加入"出彩中国人"群组，则代码如下：

// 申请加入的群组id
String groupId = "出彩中国人群组ID";
// 设置申请加入理由
String declare = "Smith申请加入群组";
// 获得SDK群组管理类
ECGroupManager groupManager = ECDevice.getECGroupManager();
// 调用审请加入群组接口，设置结果回调
groupManager.joinGroup(groupId, declare
        , new ECGroupManager.OnJoinGroupListener() {
    @Override
    public void onJoinGroupComplete(ECError error, String groupId) {
        if(SdkErrorCode.REQUEST_SUCCESS == error.errorCode)|| SdkErrorCode.MEMBER_ALREADY_EXIST == error.errorCode)) {
            // 申请加入群组成功(SdkErrorCode.MEMBER_ALREADY_EXIST代表申请者已经是群组成员)
            // 根据申请的群组权限（permission字段）来区分
            // 是否直接加入成功或者需要管理员审核
            if(permission == 1) {
                // 群组申请不需要验证，直接加入
                // 这里可以跳转到群组聊天界面、更新UI
                return;
            }
            Toast.makeText(Context , "申请加入群组成功，请等待管理员审核" ,
                    Toast.LENGTH_SHORT).show();
            return ;
        }
        // 群组申请失败
        Log.e("ECSDK_Demo", "join group fail , errorCode="
                + error.errorCode);
    }
    @Override
    public void onComplete(ECError error) {
        // 不需要处理忽略
    } 
    });

申请加入群组请求通知

接收他人加入操作时，需要设置回调监听，参考文档：IM接收消息回调。

示例代码

@Override
//"设置SDK接收消息回调"—OnChatReceiveListener
public void OnReceiveGroupNoticeMessage(ECGroupNoticeMessage notice) {
    if (notice == null) {
        return;
        
    }
    // 有人申请加入群组（仅限于管理员）
    if (notice.getType() == ECGroupNoticeMessage.ECGroupMessageType.PROPOSE) {
        ECProposerMsg proposerMsg = (ECProposerMsg) notice;
        // 处理申请加入群组请求通知
    }
}

同意加入

群主或者管理员，可以进行同意他人进群的操作。

API介绍

void ackJoinGroupRequest(java.lang.String groupId,
                         java.lang.String member,
                         ECAckType type,
                         ECGroupManager.OnAckJoinGroupRequestListener l)
管理员验证用户申请加入群组
参数:
groupId - 申请的群组ID
member - 申请者账号
type - 验证回复类型（同意或者拒绝）
l - 回复结果回调

示例代码

Tony同意Smith加入的请求，代码如下：

// 创建回复验证参数响应状态 ECAckType.AGREE：通过 ECAckType.REJECT：拒绝
ECAckType ackType = ECAckType.AGREE;
// 所属的群组ID
String groupId = "出彩中国人群组ID";
// 申请者账号ECProposerMsg.getProposer()
String proposer = "Smith的账号";
// 获得SDK群组管理类
ECGroupManager groupManager = ECDevice.getECGroupManager();
// 调用验证申请群组接口，设置结果回调
groupManager.ackJoinGroupRequest(groupId, proposer, ackType ,
        new ECGroupManager.OnAckJoinGroupRequestListener() {
            @Override
            public void onAckJoinGroupRequestComplete(ECError error
                    , String groupId, String member) {
                if(error.errorCode == SdkErrorCode.REQUEST_SUCCESS) {
                    // 回复群组申请成功
                    return ;
                }
                // 回复群组申失败
                Log.e("ECSDK_Demo", "ack group apply fail , errorCode="
                        + error.errorCode);
            }
            @Override
            public void onComplete(ECError error) {
                // 忽略
            }
          } 
        );

成员加入通知

Smith加入成功后，群组中成员Tony和John收到的通知回调方法代码如下：(参考Demo中的IMChattingHelper.java)

参考文档：IM接收消息回调。

//该通知回调接口是初始化时设置的 "设置SDK接收消息回调"—OnChatReceiveListener
@Override
public void OnReceiveGroupNoticeMessage(ECGroupNoticeMessage notice) {
    if (notice == null) {
        return;
    }
    // 有人退出群组通知（群组成员）
    if (notice.getType() == ECGroupNoticeMessage.ECGroupMessageType.QUIT) {
        ECQuitGroupMsg quitGroupMsg = (ECQuitGroupMsg) notice;
        // 处理某人退出群组通知
    }}

邀请加入

只能群主或管理员邀请别人加入群组。

API介绍

void inviteJoinGroup(java.lang.String groupId,
                     java.lang.String reason,
                     java.lang.String[] members,
                     ECGroupManager.InvitationMode confirm,
                     ECGroupManager.OnInviteJoinGroupListener l)
管理员邀请加入群组
参数:
groupId - 邀请加入的群组ID
reason - 邀请加入群组的邀请愿意members - 邀请的成员
confirm - ECGroupManager.InvitationMode.NEED_CONFIRM 需要对方验证， ECGroupManager.InvitationMode.FORCE_PULL 不需要对方验证
l - 邀请结果回调

代码示例

我们假设"出彩中国人"群组的创建者Tony邀请Smith加入群组，则代码如下：(参考Demo中的CreateGroupActivity.java)

 // 设置群组ID
 String groupId = "出彩中国人群组ID";
 // 设置邀请加入理由
 String declare = "Tony邀请Smith加入群组";
 // 设置邀请加入的群组成员（可多选）
 String[] members = new String[]{"Smith的账号"};
 // 是否需要对方确认（NEED_CONFIRM 需要对方验证，FORCE_PULL 不需要对方验证）
 ECGroupManager.InvitationMode confirm = ECGroupManager.InvitationMode.NEED_CONFIRM;
 // 获得SDK群组管理类
 ECGroupManager groupManager = ECDevice.getECGroupManager();
 // 调用邀请加入群组接口，设置结果回调
groupManager.inviteJoinGroup(groupId,declare,members,confim,new ECGroupManager.OnInviteJoinGroupListener() {
    @Override
    public void onComplete(ECError error) {
        // 可以忽略不需要处理
    }
    @Override
    public void onInviteJoinGroupComplete(ECError error
            , String groupId, String[] members) {
        if(error.errorCode == SdkErrorCode.REQUEST_SUCCESS) {
            // 邀请加入成功 ,1默认是直接就拉进群组
            if(confim == 1) {
                // 直接拉进群组，不需要被邀请成员是否同意
                return ;
            }
            Toast.makeText(Context , "邀请加入群组成功，请等待Smith验证" ,
                    Toast.LENGTH_SHORT).show();
            return ;
        }
        // 群组邀请成员失败
        Log.e("ECSDK_Demo", "invite join group fail , errorCode="
                + error.errorCode);
    }
    }
    );

用户验证管理员邀请加入群组

如果Tony邀请Smith加入的时候，接口参数不指定加入需要Smith确认，则smith直接被邀请加入。如果指定需要Smith

同意才能加入，则Smith收到如下通知回调，并在回调里面回复"同意"或"拒绝"加入。参考文档：IM接收消息回调。

API介绍

void ackInviteJoinGroupRequest(java.lang.String groupId,
                               ECAckType type,
                               java.lang.String invitee,
                               ECGroupManager.OnAckInviteJoinGroupRequestListener l)
用户验证管理员邀请加入群组
参数:
groupId - 邀请加入的群组ID
type - 回复类型（同意或者拒绝）
l - 回复结果回调

代码示例

//该通知回调接口是初始化时设置的 "设置SDK接收消息回调"—OnChatReceiveListener
@Override
public void OnReceiveGroupNoticeMessage(ECGroupNoticeMessage notice) {
    if (notice == null) {
        return;
    }
    // 有人加入群组通知（群组成员）
    if (notice.getType() == ECGroupNoticeMessage.ECGroupMessageType.INVITE) {
        ECInviterMsg inviterMsg = (ECInviterMsg) notice;
        // 处理群组管理员邀请加入群组通知
        String groupId = inviterMsg.getGroupId();
    }} 
// 创建回复验证参数响应状态
// ECAckType.AGREE：通过 ECAckType.REJECT：拒绝
ECAckType ackType = ECAckType.AGREE;
// 所属的群组ID
String groupId = "出彩中国人群组ID";
// 邀请者账号（ECInviterMsg.getAdmin()）
String inviter = "Tony的账号";
// 获得SDK群组创建管理类
ECGroupManager groupManager = ECDevice.getECGroupManager();
// 调用回复邀请加入群组接口，设置结果回调
groupManager.ackInviteJoinGroupRequest(groupId, ackType,inviter,
        new ECGroupManager.OnAckInviteJoinGroupRequestListener() {
            @Override
            public void onAckInviteJoinGroupRequestComplete(ECError error , 
                                                            String groupId) {
                if (error.errorCode == SdkErrorCode.REQUEST_SUCCESS) {
                    // 回复群组邀请成功
                    return;
                }
                // 回复群组邀请失败
                Log.e("ECSDK_Demo", "ack group apply fail , errorCode="
                        + error.errorCode);
            }
            @Override
            public void onComplete(ECError error) {
                // 忽略
            }
        } 
      );

退出群组

API介绍

void quitGroup(java.lang.String groupId,
               ECGroupManager.OnQuitGroupListener l)
退出群组
参数:
groupId - 群组 ID
l - 退出结果

代码示例

我们假设Smith要退出群组，则代码如下：

// 设置需要退出的群组id
String groupId = "出彩中国人群组ID";
// 获得SDK群组创建管理类
ECGroupManager groupManager = ECDevice.getECGroupManager();
// 调用退出群组接口，设置结果回调
groupManager.quitGroup(groupId, new ECGroupManager.OnQuitGroupListener() {
    @Override
    public void onQuitGroupComplete(ECError error, String groupId) {
        if (error.errorCode == SdkErrorCode.REQUEST_SUCCESS) {
            // 退出群组成功
            // 这里可以删除本地群组缓存，删除群组聊天纪录等
            return;
        }
        // 退出群组失败
        Log.e("ECSDK_Demo", "quit group fail , errorCode="
                + error.errorCode);
    }
    @Override
    public void onComplete(ECError error) {
        // 忽略
    }});

退出群组通知

退出群组成功后，群组中的成员会收到通知。设置位置参考文档：IM接收消息回调。

代码示例

Smith退出成功后，群组中成员Tony和John收到的通知回调方法代码如下：(参考Demo中的IMChattingHelper.java)

//该通知回调接口是初始化时设置的 "设置SDK接收消息回调"—OnChatReceiveListener
@Override
public void OnReceiveGroupNoticeMessage(ECGroupNoticeMessage notice) {
    if (notice == null) {
        return;
    }
    // 有人退出群组通知（群组成员）
    if (notice.getType() == ECGroupNoticeMessage.ECGroupMessageType.QUIT) {
        ECQuitGroupMsg quitGroupMsg = (ECQuitGroupMsg) notice;
        // 处理某人退出群组通知
    } 
    }

群主踢人

只有群主可以进行踢人操作。

API介绍

void deleteGroupMember(java.lang.String groupId,
                       java.lang.String member,
                       ECGroupManager.OnDeleteGroupMembersListener l)
删除成员
参数:
groupId - 群组ID
member - 移除的成员
l - 移除结果回调

代码示例

我们假设群主Tony要把Smith要踢出群组，则代码如下：

// Smith所在的群组id
String grouId = "出彩中国人群组ID";
// Smith账号
String member = "Smith的账号";
// 获得SDK群组创建管理类
ECGroupManager groupManager = ECDevice.getECGroupManager();
// 调用群组移除成员接口，设置结果回调
groupManager.deleteGroupMember(grouId, member,
        new ECGroupManager.OnDeleteGroupMembersListener() {
    @Override
    public void onDeleteGroupMembersComplete(ECError error
            , String groupId, String members) {
        if(error.errorCode == SdkErrorCode.REQUEST_SUCCESS){
            // 移除成员成功
            // 将Smith账号从本地群组关联关系中移除
            // 通知UI更新
            return;
        }
        // 退出群组失败
        Log.e("ECSDK_Demo", "remove group member fail " +
                ", errorCode=" + error.errorCode);
    }
    @Override
    public void onComplete(ECError error) {
        // 忽略不处理
    } 
    });

移除成员通知

群组中所有成员都会收到的Smith被踢的消息，包括Smith自己，Smith判断被踢用户的id等于自己，则从本地删除群组，此通知回调方法代码如下：(参考Demo中的IMChattingHelper.java) 。设置回调参考文档： IM接收消息回调。

//该通知回调接口是初始化时设置的 "设置SDK接收消息回调"—OnChatReceiveListener
@Override
public void OnReceiveGroupNoticeMessage(ECGroupNoticeMessage notice) {
    if (notice == null) {
        return;
    }
    // 有人被移除出群组
    if (notice.getType() == 
            ECGroupNoticeMessage.ECGroupMessageType.REMOVE_MEMBER) {
        ECRemoveMemberMsg removeMemberMsg = (ECRemoveMemberMsg) notice;
        // 处理群组移除成员通知
        if ("Smith账号".equals(removeMemberMsg.getMember())) {
            // 如果是自己则将从本地群组关联关系中移除
            // 通知UI处理刷新
        }
    } }

解散群组

只有群主才能解散群组。

API介绍

void deleteGroup(java.lang.String groupId,
                 ECGroupManager.OnDeleteGroupListener l)
删除群组
参数:
groupId - 需要被删除的群组ID
l - 删除群组回调

代码示例

我们假设群主Tony要解散"出彩中国人"，则代码如下：

// 被解散的群组id
String grouId = "出彩中国人群组ID";
// 获得SDK群组创建管理类
ECGroupManager groupManager = ECDevice.getECGroupManager();
// 调用群组移解散接口，设置结果回调
groupManager.deleteGroup(groupId, new ECGroupManager.OnDeleteGroupListener() {
    @Override
    public void onDeleteGroupComplete(ECError error, String groupId) {
        if(error.errorCode == SdkErrorCode.REQUEST_SUCCESS){
            // 群组解散成功
            // 将群组信息从本地缓存中删除 通知UI更新
            return;
        }
        // 解散群组失败
        Log.e("ECSDK_Demo", "del group fail " +
                ", errorCode=" + error.errorCode);
    }
    @Override
    public void onComplete(ECError error) {
        // 忽略不处理
    } 
    });

群组解散通知

群组中所有成员收到的通知回调方法代码如下，设置回调参考文档： IM接收消息回调。

//该通知回调接口是初始化时设置的 "设置SDK接收消息回调"—OnChatReceiveListener
@Override
public void OnReceiveGroupNoticeMessage(ECGroupNoticeMessage notice) {
    if (notice == null) {
        return;
    }
    // 群组被解散
    if (notice.getType() ==ECGroupNoticeMessage.ECGroupMessageType.DISMISS) {
        ECDismissGroupMsg dismissGroupMsg = (ECDismissGroupMsg) notice;
        // 处理群组被解散通知
        // 将群组从本地缓存中删除并通知UI刷新
    } 
    }

获取群成员

API介绍

void queryGroupMembers(java.lang.String groupId,
                       ECGroupManager.OnQueryGroupMembersListener l)
查询群组成员
参数:
groupId - 需要查询的成员所在的群组ID
l - 查询结果

代码示例

代码如下：(参考Demo中的GroupMemberService.java)

// 需要获取群组成员的群组id
String grouId = "出彩中国人群组ID";
// 获得SDK群组管理类
ECGroupManager groupManager = ECDevice.getECGroupManager();
// 调用获取群组成员接口，设置结果回调
groupManager.queryGroupMembers(groupId,
        new ECGroupManager.OnQueryGroupMembersListener() {
            @Override
            public void onQueryGroupMembersComplete(ECError error
                    , List<ECGroupMember> members) {
                if (error.errorCode == SdkErrorCode.REQUEST_SUCCESS && members != null) {
                    // 获取群组成员成功
                    // 将群组成员信息更新到本地缓存中（sqlite） 通知UI更新
                    return;
                }
                // 群组成员获取失败
                Log.e("ECSDK_Demo", "sync group detail fail " +
                        ", errorCode=" + error.errorCode);
            }
            @Override
            public void onComplete(ECError error) {
                // 忽略不处理
            }
        });

群组搜索

可以根据群组名字或者群组ID来搜索群组(群组名称为纯数字或纯字母时需要输入完整的群名称) 。 (参考Demo中的SearchGroupActivity.java)

API介绍

void searchPublicGroups(ECGroupMatch match,
                        ECGroupManager.OnSearchPublicGroupsListener l)
按条件搜索公共群组
参数:
match - 群组搜索条件
l - 搜索结果回调

代码示例

// 创建查询参数规则（按照群组id检索）
ECGroupMatch match = new ECGroupMatch(ECGroupMatch.SearchType.GROUPID);
// 设置检索词（根据匹配规则输入群组I的或者名称）
match.setkeywords("出彩的中国人");
// 获得SDK群组管理类
ECGroupManager groupManager = ECDevice.getECGroupManager();
// 调用检索群组接口，设置结果回调
groupManager.searchPublicGroups(match, 
        new ECGroupManager.OnSearchPublicGroupsListener() {
    @Override
    public void onSearchPublicGroupsComplete(ECError error
            , List<ECGroup> groups) {
        if (error.errorCode == SdkErrorCode.REQUEST_SUCCESS && groups != null){
            // 检索群组成功
            // 根据查询到的群组选择是否申请加入群组
            return;
        }
        // 检索群组取失败
        Log.e("ECSDK_Demo", "search group fail " +
                ", errorCode=" + error.errorCode);
    }
    @Override
    public void onComplete(ECError error) {
        // 忽略不需要处理
    }});

获取个人所在的群组

查询自己创建或者加入的全部群组或者讨论组。

API介绍

void queryOwnGroups(ECGroupManager.Target target,
                    ECGroupManager.OnQueryOwnGroupsListener l)
查询加入的群组
参数:
l - 结果回调
target - 返回值类型

代码示例

用户登录后，通常首先调取此接口获取自己所在群组/讨论组，此接口会返回群组的id、名称、免打扰状态等信息，其示例代码如下：

// 获得SDK群组创建管理类
ECGroupManager groupManager = ECDevice.getECGroupManager();
// 调用查询个人加入的群组接口，设置结果回调
//Target.Group是群组，Target.Discussion是讨论组
groupManager.queryOwnGroups(Target.Group，new ECGroupManager.OnQueryOwnGroupsListener() {
    @Override
    public void onQueryOwnGroupsComplete(ECError error, List groups){
        if(SdkErrorCode.REQUEST_SUCCESS == error.errorCode) {
            // 请求成功
            // 进行本地数据库与服务器数据同步
            // 删除不存在或者没有加入的群组
            return ;
        }
        // 查询个人加入的群组失败
        Log.e("ECSDK_Demo", "query own groups fail " +
                ", errorCode=" + error.errorCode);
    }
    @Override
    public void onComplete(ECError error) {
        // 忽略
    } 
    });