管理社区
管理社区
社区（Server）是一群有着共同兴趣爱好的人的专属天地，也可以是同学朋友的社交圈子。社区是环信圈子三层基础架构的最上层，各种消息事件均发生在社区内。社区分为公开社区和私密社区。对于公开社区，任何用户均可查询社区列表，可自由加入或退出社区，无需审批；对于私密社区，用户无法查询社区列表，只能通过社区成员邀请加入社区，无法申请加入社区。
超级社区中的频道基于即时通讯 IM 的群组或聊天室（频道 ID 为群组 ID 或聊天室 ID）创建，解散群组或聊天室时需注意以下几点：
1. 在环信控制台或者通过客户端解散群组或聊天室、群组或聊天室加人、踢人等操作时请谨慎操作，需确保操作的群组或者聊天室不是超级社区使用的。2. 如果将超级社区使用的频道对应的群组或者聊天室删除，会出现数据不一致情况，导致用户加入不了社区、频道、在频道内发不了消息等情况发生。3. 在清理群组或者聊天室数据时，需先确认要删除的群组 ID 或聊天室 ID 与超级社区的频道 ID 是否一致。你可以调用获取频道详情 API 确认要删除的群组或聊天室是否为超级社区的频道。如果是，请不要进行删除。4. 如果需要清理超级社区数据，调用删除社区和删除频道等 API。
技术原理
环信 Circle Android SDK 提供 EMCircleManager 类和 EMCircleServer 类用于社区管理，支持你通过调用 API 在项目中实现如下功能：
- 创建和管理社区；
- 管理社区成员；
- 监听社区事件。
前提条件
开始前，请确保满足以下条件：
- 完成 Circle SDK 的初始化，即完成 IM SDK 3.9.9.2 版本的初始化，详见 IM SDK 初始化
- 了解环信即时通讯 IM 的使用限制，详见 使用限制。
- 了解 Circle 的使用限制，详见 使用限制。
实现方法
创建和管理社区
创建社区
社区分为公开社区和私密社区。每个用户最多可以创建 100 个社区。若要提升上限，请联系商务。
- 调用
createServer方法创建社区。
示例代码如下：
EMCircleServerAttribute attribute = new EMCircleServerAttribute();
attribute.setName(name);
attribute.setDesc(desc);
attribute.setIcon(icon);
EMClient.getInstance().chatCircleManager().createServer(attribute, new EMValueCallBack<EMCircleServer>() {
@Override
public void onSuccess(EMCircleServer value) {
}
@Override
public void onError(int error, String errorMsg) {
}
});
创建社区时，需设置社区属性 EMCircleServerAttribute，如下表所示。
| 参数 | 类型 | 描述 | 是否必需 |
|---|---|---|---|
name | String | 社区名称，不能超过 50 个字符。 | 是 |
icon | String | 社区头像 URL，不能超过 500 个字符。 | 否 |
type | EMCircleServerType | 社区类型： - （默认） Public：公开社区；- Private：私密社区。 | 否 |
backgroundUrl | String | 社区背景 URL，不能超过 500 个字符。 | 否 |
desc | String | 社区描述，不能超过 500 个字符。 | 否 |
ext | String | 社区自定义扩展字段，不能超过 500 个字符。 | 否 |
- 邀请用户加入社区。
社区成员调用 inviteUserToServer 方法邀请用户加入社区。受邀用户收到 EMCircleServerListener#onReceiveInvitation 事件。
示例代码如下：
EMClient.getInstance().chatCircleManager().inviteUserToServer(serverId, inviteeUserId, "欢迎加入server", new EMCallBack() {
@Override
public void onSuccess() {
}
@Override
public void onError(int code, String error) {
}
}
);
- 用户确认是否加入社区。
- 若同意加入社区，调用
acceptServerInvitation方法。邀请人收到EMCircleServerListener#onInvitationBeAccepted事件，社区内所有成员（不包括加入社区的该新成员）会收到EMCircleServerListener#onMemberJoinedServer事件。示例代码如下：
EMClient.getInstance().chatCircleManager().acceptServerInvitation(serverId, inviterUserID, new EMValueCallBack<EMCircleServer>() {
@Override
public void onSuccess(EMCircleServer value) {
}
@Override
public void onError(int error, String message) {
}
});
- 若拒绝加入社区，调用
declineServerInvitation方法。邀请人收到EMCircleServerListener#onInvitationBeDeclined事件。示例代码如下：
EMClient.getInstance().chatCircleManager().declineServerInvitation(serverId, inviterUserID, new EMCallBack() {
@Override
public void onSuccess() {
}
@Override
public void onError(int code, String message) {
}
});
修改社区信息
社区所有者和管理员可调用 updateServer 方法修改社区信息，包括社区名称、类型、描述、头像 URL、背景 URL 和自定义扩展信息。社区信息修改后，社区的所有成员（除操作者外）会收到 EMCircleServerListener#onServerUpdated 事件。
示例代码如下：
EMCircleServerAttribute serverAttribute = new EMCircleServerAttribute();
serverAttribute.setName("name");
serverAttribute.setIcon("iconUrl");
serverAttribute.setDesc("update desc");
serverAttribute.setExt("");
EMClient.getInstance().chatCircleManager().updateServer(serverId, serverAttribute, new EMValueCallBack<EMCircleServer>() {
@Override
public void onSuccess(EMCircleServer circleServer) {
}
@Override
public void onError(int error, String errorMsg) {
}
});
解散社区
仅社区所有者可调用 destroyServer 方法解散社区。社区解散后，社区所有成员（除社区所有者）会收到 EMCircleServerListener#onServerDestroyed 事件并被移出社区。
示例代码如下：
EMClient.getInstance().chatCircleManager().destroyServer(serverId, new EMCallBack() {
@Override
public void onSuccess() {
}
@Override
public void onError(int code, String error) {
}
});
添加社区标签
社区所有者和管理员可以调用 addTagsToServer 方法为社区添加标签。非社区内用户可以通过搜索标签全名查找社区。每个社区最多可添加 10 个标签。
示例代码如下：
String tag = "动漫";
ArrayList<String> tags = new ArrayList<>();
tags.add(tag);
EMClient.getInstance().chatCircleManager().addTagsToServer(serverId, tags, new EMValueCallBack<List<EMCircleTag>>() {
@Override
public void onSuccess(List<EMCircleTag> tags) {
}
@Override
public void onError(int error, String errorMsg) {
}
});
移除社区标签
社区所有者和管理员可以调用 removeTagsFromServer 方法移除社区已有标签。
示例代码如下：
ArrayList<String> tagsRemoved = new ArrayList<>();
tagsRemoved.add("你要移除的tagId");
EMClient.getInstance().chatCircleManager().removeTagsFromServer(serverId, tagsRemoved, new EMCallBack() {
@Override
public void onSuccess() {
}
@Override
public void onError(int error, String errorMsg) {
}
});
获取社区标签列表
社区成员可调用 fetchServerTags 方法获取社区的标签列表。
EMClient.getInstance().chatCircleManager().fetchServerTags(serverId, new EMValueCallBack<List<EMCircleTag>>() {
@Override
public void onSuccess(List<EMCircleTag> value) {
}
@Override
public void onError(int error, String errorMsg) {
}
});
搜索公开社区
社区成员可以调用 fetchServers 方法按查询类型（EMCircleServerSearchType）搜索公开社区，即按社区名称或社区标签名称查询。
- 根据社区名称搜索，支持基于通过社区全名搜索和模糊搜索分页获取数据。若使用模糊搜索，你需要传入社区名称中最左侧的单个字或词汇，或包含该字或词汇的关键字。例如社区名称为
足球社区01，传入足或足球都可搜索出该社区，而使用球或社区01则搜索不到该社区。 - 若根据标签名称搜索，需传入完整的标签名称，不支持模糊搜索。该类型查询直接获取带有该标签的所有社区，不支持分页查询。
EMCircleServerSearchType searchType=EMCircleServerSearchType.EM_CIRCLE_SERVER_SEARCH_TYPE_NAME;
String keyword="足球";
EMClient.getInstance().chatCircleManager().fetchServers(searchType, keyword, 20, null, new EMValueCallBack<EMCursorResult<EMCircleServer>>() {
@Override
public void onSuccess(EMCursorResult<EMCircleServer> value) {
}
@Override
public void onError(int error, String errorMsg) {
}
});
获取社区详情
社区成员可以调用 fetchServerDetail 方法获取社区的详情。
示例代码如下：
EMClient.getInstance().chatCircleManager().fetchServerDetail(serverId, new EMValueCallBack<EMCircleServer>() {
@Override
public void onSuccess(EMCircleServer value) {
}
@Override
public void onError(int error, String errorMsg) {
}
});
获取已加入社区
社区成员可以调用 fetchJoinedServers 方法获取已加入的社区列表。
示例代码如下：
EMClient.getInstance().chatCircleManager().fetchJoinedServers(20, null, new EMValueCallBack<EMCursorResult<EMCircleServer>>() {
@Override
public void onSuccess(EMCursorResult<EMCircleServer> value) {
}
@Override
public void onError(int error, String errorMsg) {
}
});
分页获取社区成员列表
社区成员可以调用 fetchServerMembers 方法分页获取指定社区中的成员列表，该列表包含社区创建者。
示例代码如下：
EMClient.getInstance().chatCircleManager().fetchServerMembers(serverID, 20, null, new EMValueCallBack<EMCursorResult<EMCircleUser>>() {
@Override
public void onSuccess(EMCursorResult<EMCircleUser> value) {
}
@Override
public void onError(int error, String errorMsg) {
}
});
管理社区成员
加入社区
每个用户最多可加入 100 个社区，超过需要联系商务。用户可以通过以下两种方式加入社区：
搜索公开社区获得社区 ID，主动申请加入该社区。
社区内成员邀请用户加入。
公开社区支持申请加入和邀请加入，而私密社区仅支持邀请加入。通过邀请加入社区，详见 创建社区。
下面介绍用户如何申请加入公开社区。
用户 搜索公开社区获得社区 ID。
用户调用
joinServer方法加入社区。加入成功后，社区内其他成员会收到EMCircleServerListener#onMemberJoinedServer事件。
示例代码如下：
EMClient.getInstance().chatCircleManager().joinServer(serverId, new EMValueCallBack<EMCircleServer>() {
@Override
public void onSuccess(EMCircleServer value) {
}
@Override
public void onError(int code, String error) {
}
}
);
退出社区
社区成员若退出社区，则会退出该社区下的所有频道。社区所有者不支持退出社区操作，只能解散社区。
退出社区分为主动退出和被动退出，被动退出即成员被社区所有者或管理员移出社区。
用户主动退出社区
用户可调用 leaveServer 方法退出社区。退出成功后，社区内其他成员会收到 EMCircleServerListener#onMemberLeftServer 事件。
示例代码如下：
EMClient.getInstance().chatCircleManager().leaveServer(serverId, new EMCallBack() {
@Override
public void onSuccess() {
}
@Override
public void onError(int code, String error) {
}
});
用户被移出社区
社区所有者和管理员调用 removeUserFromServer 方法将普通成员移出社区，管理员只能被社区所有者移出社区。被移出社区的成员、社区所有者和管理员（除操作者外）会收到 EMCircleServerListener#onMemberRemovedFromServer 事件。
示例代码如下：
EMClient.getInstance().chatCircleManager().removeUserFromServer(serverId, userId, new EMCallBack() {
@Override
public void onSuccess() {
}
@Override
public void onError(int code, String error) {
}
});
查询当前用户是否在社区内
用户可调用 checkSelfIsInServer 方法查询自己是否已经加入了指定社区。
示例代码如下：
EMClient.getInstance().chatCircleManager().checkSelfIsInServer(serverId, new EMValueCallBack<Boolean>() {
@Override
public void onSuccess(Boolean value) {
}
@Override
public void onError(int error, String errorMsg) {
}
});
查询当前用户的社区角色
用户可调用 fetchSelfServerRole 方法查询当前用户在社区中的角色。
示例代码如下：
EMClient.getInstance().chatCircleManager().fetchSelfServerRole(serverId, new EMValueCallBack<EMCircleUserRole>() {
@Override
public void onSuccess(EMCircleUserRole value) {
}
@Override
public void onError(int error, String errorMsg) {
}
});
设置社区管理员
仅社区所有者可以调用 addModeratorToServer 方法设置社区管理员。成功设置后，社区所有成员（除社区所有者外）会收到 EMCircleServerListener#onRoleAssigned 事件。
社区管理员除了不能创建和解散社区等少数权限外，拥有对社区的绝大部分权限。
示例代码如下：
EMClient.getInstance().chatCircleManager().addModeratorToServer(serverId, userId, new EMCallBack() {
@Override
public void onSuccess() {
}
@Override
public void onError(int code, String error) {
}
});
移除社区管理员
仅社区所有者可以调用 removeModeratorFromServer 方法移除社区管理员。成功移除后，社区所有成员（除社区所有者外）会收到 EMCircleServerListener#onRoleAssigned 事件。
社区管理员被移除管理员权限后，将只拥有社区普通成员的权限。
示例代码如下：
EMClient.getInstance().chatCircleManager().removeModeratorFromServer(serverId, userId, new EMCallBack() {
@Override
public void onSuccess() {
}
@Override
public void onError(int code, String error) {
}
});
监听社区事件
EMCircleManager 中提供社区事件的监听接口。开发者可以通过设置此监听，获取社区中的事件，并做出相应处理。如果不再使用该监听，需要移除，防止出现内存泄漏。
EMCircleServerListener circleServerListener = new EMCircleServerListener() {
//社区被创建。参数社区创建的成员（除操作者外）会收到该事件。
@Override
public void onServerCreated(EMCircleServer server) {
}
//社区被解散。社区所有成员（除社区所有者外）会收到该事件。
@Override
public void onServerDestroyed(String serverId, String initiator) {
}
//社区信息更新。社区所有成员（除操作者外）会收到该事件。
@Override
public void onServerUpdated(EMCircleServerEvent event) {
}
//有用户加入社区。社区所有成员（除加入社区的新成员外）会收到该事件。
@Override
public void onMemberJoinedServer(String serverId, String member) {
}
//有成员主动退出社区。社区所有者和管理员会收到该事件。
@Override
public void onMemberLeftServer(String serverId, String member) {
}
//有成员被移出社区。被移除者、社区所有者和管理员（除操作者外）会收到该事件。
@Override
public void onMemberRemovedFromServer(String serverId, List<String> members) {
}
//用户收到社区加入邀请。受邀用户会收到该事件。
@Override
public void onReceiveInvitation(EMCircleServerEvent event, String inviter) {
}
//用户同意社区加入邀请。邀请人会收到该事件。
@Override
public void onInvitationBeAccepted(String serverId, String invitee) {
}
//用户拒绝社区加入邀请。邀请人会收到该事件。
@Override
public void onInvitationBeDeclined(String serverId, String invitee) {
}
//社区成员的角色发生变化。社区所有成员（除操作者外）会收到该事件。
@Override
public void onRoleAssigned(String serverId, String member, EMCircleUserRole role) {
}
};
//添加社区事件监听
EMClient.getInstance().chatCircleManager().addServerListener(circleServerListener);
//移除社区事件监听
EMClient.getInstance().chatCircleManager().removeServerListener(circleServerListener);
//清空所有社区事件的监听
EMClient.getInstance().chatCircleManager().clearServerListeners();