管理社区
社区(Server)是一群有着共同兴趣爱好的人的专属天地,也可以是同学朋友的社交圈子。社区是环信圈子三层基础架构的最上层,各种消息事件均发生在社区内。任何用户均可以自由加入或退出社区,无需审批。
技术原理
环信即时通讯 IM Web SDK 支持你通过调用 API 在项目中实现如下功能:
- 创建和管理社区;
- 管理社区成员;
- 监听社区事件。
前提条件
实现方法
创建和管理社区
创建社区
可创建社区数量根据套餐版本有所不同。每个用户最多可创建 100 个社区,超过需要联系商务。
- 调用
createServer
方法创建社区。创建者多设备登录时,其他设备会同时收到onMultiDeviceEvent
回调,事件为serverCreate
。
示例代码如下:
let options = {
name: 'server name',
icon: 'image url',
description: 'a test server',
ext: '',
}
WebIM.conn.createServer(options).then(res => {
console.log(res)
})
创建社区时,需设置以下参数,如下表所示。
参数 | 类型 | 描述 |
---|---|---|
name | String | 社区名称。 |
icon | String | 社区图标。 |
description | String | 社区描述。 |
ext | String | 社区扩展字段。 |
-
邀请用户加入社区。
调用 inviteUserToServer
方法邀请用户加入社区。受邀用户会收到 onServerEvent
回调,事件为 inviteToJoin
。邀请人多设备登录时,其他设备会同时收到 onMultiDeviceEvent
回调,事件为 serverInviteUser
。
示例代码如下:
let options = {
serverId: 'serverId',
userId: 'userId',
message: 'welcome',
}
WebIM.conn.inviteUserToServer(options).then(res => {
console.log(res)
})
用户确认是否加入社区。
若同意加入社区,调用
acceptServerInvite
方法。用户加入社区后,将可以收到社区消息。邀请人收到onServerEvent
回调,事件为acceptInvite
,社区内所有成员(不包括加入社区的该新成员)收到onServerEvent
回调,事件为memberPresence
。受邀用户多设备登录时,其他设备会同时收到onMultiDeviceEvent
回调,事件为serverAcceptInvite
。示例代码如下:
let options = { serverId: 'serverId', inviter: 'userId', } WebIM.conn.acceptServerInvite(options).then(res => { console.log(res) })
若拒绝加入社区,调用 rejectServerInvite
方法。邀请人收到 onServerEvent
回调,事件为 refuseInvite
。受邀用户多设备登录时,其他设备会同时收到 onMultiDeviceEvent
回调,事件为 serverRefuseInvite
。
示例代码如下:
let options = {
serverId: 'serverId',
inviter: 'userId',
}
WebIM.conn.rejectServerInvite(options).then(res => {
console.log(res)
})
修改社区信息
社区所有者和管理员可调用 updateServer
方法修改社区基本信息。社区信息修改后,除操作者外的社区所有成员会收到 onServerEvent
回调,事件为 update
。操作者多设备登录时,其他设备会同时收到 onMultiDeviceEvent
回调,事件为 serverUpdate
。
示例代码如下:
let options = {
serverId: 'serverId',
name: 'new name',
icon: 'image url',
description: 'a test server',
ext: '',
}
WebIM.conn.updateServer(options).then(res => {
console.log(res)
})
添加社区标签
社区所有者和管理员可以调用 addServerTags
方法为社区增加标签。非社区内用户可以通过搜索标签全名查找社区。每个社区最多可添加 10 个标签。
示例代码如下:
let options = {
serverId: 'serverId',
tags: ['学习', '体育'],
}
WebIM.conn.addServerTags(options).then(res => {
console.log(res)
})
移除社区标签
社区所有者和管理员可以调用 removeServerTags
方法移除社区已有标签。
示例代码如下:
let options = {
serverId: 'serverId',
tags: ['tagId', 'tagId'],
}
WebIM.conn.removeServerTags(options).then(res => {
console.log(res)
})
解散社区
仅社区所有者可调用 destroyServer
方法解散社区。解散社区后将删除本地的社区数据,除社区所有者外的社区所有成员会收到 onServerEvent
回调,事件为 destroy
。操作者多设备登录时,其他设备会同时收到 onMultiDeviceEvent
回调,事件为 serverDestroy
。
示例代码如下:
WebIM.conn.destroyServer({serverId: 'serverId'}).then(res => {
console.log(res)
})
获取社区详情
社区成员可以调用 getServerDetail
方法获取社区的详情。
示例代码如下:
WebIM.conn.getServerDetail({serverId: 'serverId'}).then(res => {
console.log(res)
})
获取已加入社区
用户可以调用 getJoinedServers
方法获取已加入的社区列表。
示例代码如下:
WebIM.conn.getJoinedServers({pageSize: '10',cursor: ''}).then(res => {
console.log(res)
})
分页获取社区成员列表
社区成员可以调用 getServerMembers
方法分页获取指定社区中的成员列表。
示例代码如下:
WebIM.conn.getServerMembers({serverId: 'serverId'}).then(res => {
console.log(res)
})
管理社区成员
加入社区
每个用户最多加入 100 个社区,超过需要联系商务。用户可以通过以下两种方式加入社区:
- 搜索社区名称和标签(同时支持 REST 通过社区 ID 搜索),主动申请加入社区。
- 社区内成员邀请用户加入。
通过邀请加入频道,详见 创建社区。下面介绍用户如何申请加入社区。
- 用户可以调用
getServers
方法根据社区名称和标签名称搜索社区。
目前所有社区都为公开,任何用户都可以搜索到。
示例代码如下:
WebIM.conn.getServers({keyword: 'keyword'}).then(res => {
console.log(res)
})
-
用户调用
joinServer
方法加入社区。加入成功后,社区内其他成员收到onServerEvent
回调,事件为memberPresence
。多设备登录时,其他设备会同时收到onMultiDeviceEvent
回调,事件为serverJoin
。
示例代码如下:
WebIM.conn.joinServer({serverId: 'serverId'}).then(res => {
console.log(res)
})
退出社区
社区所有者不支持退出社区操作,只能解散社区。
退出社区分为主动退出和被动退出,被动退出即为被社区所有者或管理员踢出社区。
用户主动退出社区
用户可调用 leaveServer
方法退出社区。退出成功后,社区其他成员会收到 onServerEvent
回调,事件为 memberAbsence
。多设备登录时,操作者其他设备会同时收到 onMultiDeviceEvent
回调,事件为 serverLeave
。
示例代码如下:
WebIM.conn.leaveServer({serverId: 'serverId'}).then(res => {
console.log(res)
})
用户被踢出社区
社区所有者和管理员调用 removeServerMember
方法将普通成员踢出社区,管理员只能被社区所有者踢出社区。被踢出社区的成员、社区所有者和管理员(除操作者外)会收到 onServerEvent
回调,事件为 removed
。操作者多设备登录时,其他设备会同时收到 onMultiDeviceEvent
回调,事件为 serverRemoveMember
。
示例代码如下:
WebIM.conn.removeServerMember({serverId: 'serverId',userId:'userId'}).then(res => {
console.log(res)
})
查询用户是否在社区内
用户可调用 isInServer
方法查询自己是否已经加入了指定社区。
示例代码如下:
WebIM.conn.isInServer({serverId: 'serverId'}).then(res => {
console.log(res)
})
查询自己在社区里的角色
用户可调用 getServerRole
方法查询自己在社区中的角色。
示例代码如下:
WebIM.conn.getServerRole({serverId: 'serverId'}).then(res => {
console.log(res)
})
设置社区管理员
仅社区所有者可以调用 setServerAdmin
方法设置社区管理员。成功设置后,除社区所有者之外的其他社区成员会收到onServerEvent
回调,事件为 updateRole
。操作者多设备登录时,其他设备会同时收到 onMultiDeviceEvent
回调,事件为 serverSetRole
。
社区管理员除了不能解散社区等少数权限外,拥有对社区的绝大部分权限。
示例代码如下:
WebIM.conn.setServerAdmin({serverId: 'serverId',userId:'userId'}).then(res => {
console.log(res)
})
移除社区管理员
仅社区所有者可以调用 removeServerAdmin
方法移除社区管理员。成功移除后,社区内所有人会收到 onServerEvent
回调,事件为 updateRole
。操作者多设备登录时,其他设备会同时收到 onMultiDeviceEvent
回调,事件为 serverSetRole
。
若社区管理员被移除管理员权限后,将只拥有社区普通成员的权限。
示例代码如下:
WebIM.conn.removeServerAdmin({serverId: 'serverId',userId:'userId'}).then(res => {
console.log(res)
})
监听社区事件
WebIM.conn.addEventHandler('CIRCLE',{
onServerEvent:(msg) => {
switch (msg.operation){
case "update":
//社区信息更新。社区所有成员(除操作者外)会收到该事件。
break;
case "destroy":
//社区被解散。社区所有成员(除社区所有者外)会收到该事件。
break;
case "memberPresence":
//有用户加入社区。社区所有成员(除加入社区的新成员外)会收到该事件。
break;
case "memberAbsence":
//有成员主动退出社区。社区所有者和管理员会收到该事件。
break;
case "inviteToJoin":
//用户收到社区加入邀请。受邀用户会收到该事件。
break;
case "acceptInvite":
//用户同意社区加入邀请。邀请人会收到该事件。
break;
case "refuseInvite":
//用户拒绝社区加入邀请。邀请人会收到该事件。
break;
case "removed":
//有成员被移出社区。被移除者、社区所有者和管理员(除操作者外)会收到该事件。
break;
case "updateRole":
//社区成员的角色发生变化。社区所有成员(除操作者外)会收到该事件。
break;
default:
break;
}
},
});