ZIM SDK 提供多人房间聊天功能,支持用户向房间内发送文本消息或自定义消息,实现了多人在线交流、同步分享。
多人房间聊天功能可应用于小班课或者会议室等场景,房间成员数量上限请参考 计费说明。
在实现“房间管理”功能之前,请确保:
已在 ZEGO 控制台 创建项目,获取到了接入 ZIM SDK 服务所需的 AppID 和 ServerSecret。ZIM 服务权限不是默认开启的,使用前,请先在 ZEGO 控制台 自助开通 ZIM 服务(详情请参考 项目管理 - 即时通讯),若无法开通 ZIM 服务,请联系 ZEGO 技术支持开通。
已获取登录 SDK 所需的 Token,详情请参考 使用 Token 鉴权。
已集成 ZIM SDK,详情请参考 快速开始 - 实现基本收发消息 的 “3 集成 SDK”。
用户可以通过以下两种方式,创建房间并进入房间。
房间内的用户,可以通过 sendRoomMessage 接口,向房间内发送消息,详情请参考 收发房间消息。
如果 roomID 已存在:
如果 roomID 不存在:
以下流程中,我们以客户端 A 创建并加入房间,客户端 B 加入房间为例。
所有进入房间的用户,都需注册 roomMemberJoined、roomMemberLeft 和 roomStateChanged 回调,用于监听房间其他成员的变动和接收房间连接状态发生改变的事件通知。
注册 roomMemberJoined 回调示例源码:
zim.on('roomMemberJoined', (zim, data) => {
// to do something
});
注册 roomMemberLeft 回调示例源码:
zim.on('roomMemberLeft', (zim, data) => {
// to do something
});
注册 roomStateChanged 回调示例源码:
zim.on('roomStateChanged', (zim, data) => {
// to do something
});
客户端 A 登录后,创建一个房间,可以调用 createRoom 接口,传入 ZIMRoomInfo 信息,即可创建并加入房间。同时可以通过错误码 ZIMError
的参数值,判断是否创建成功。相关错误码请查看 常见错误码。
创建成功后会收到 roomStateChanged 的通知回调,ZIMRoomState 为 ZIMRoomStateConnected, ZIMRoomEvent 为 Success。
// roomID 最大 32 字节的字符串。仅支持数字,英文字符 和 '!', '#', '$', '%', '&', '(', ')', '+', '-', ':', ';', '<', '=', '.', '>', '?', '@', '[', ']', '^', '_', '{', '}', '|', '~'。
// roomName 最大 64 字节的字符串,无特殊字符限制。
var roomInfo = { roomID: '', roomName: '' };
zim.createRoom(roomInfo)
.then(function ({ roomInfo }) {
// 操作成功
})
.catch(function (err) {
// 操作失败
});
客户端 B 加入房间,可以调用 joinRoom 接口,传入由 A 创建的房间 roomID,即可加入房间。同时可以通过错误码 ZIMError
的参数值,判断是否创建成功。相关错误码请查看 常见错误码。
加入成功后会收到 roomStateChanged 的通知回调,ZIMRoomState 为 ZIMRoomStateConnected, ZIMRoomEvent 为 Success。
var roomID = '';
zim.joinRoom(roomID)
.then(function ({ roomInfo }) {
// 操作成功
})
.catch(function (err) {
// 操作失败
});
当房间有其他成员加入时,将通过 on 的回调接口 roomMemberJoined,向其他已在成员发送消息通知。
例如,当客户端 B 加入由 A 创建的房间时,A 将收到房间内成员变动的通知。
// 加入房间通知,通过该通知收到加入房间的用户信息
zim.on('roomMemberJoined', function (zim, { roomID, memberList }) {
console.log(roomID, memberList);
});
以下流程中,我们以客户端 X 创建并进入房间,客户端 Y 直接进入房间为例。
var roomInfo = { roomID: '', roomName: '' };
zim.enterRoom(roomInfo)
.then(function ({ roomInfo }) {
// 操作成功
})
.catch(function (err) {
// 操作失败
});
// 加入房间通知,通过该通知收到加入房间的用户信息
zim.on('roomMemberJoined', function (zim, { roomID, memberList }) {
console.log(roomID, memberList);
});
客户端 B 如果想要离开房间,可以调用 leaveRoom 接口,传入房间的 roomID,即可退出此房间;房间内的其他用户可以通过 on 的回调接口 roomMemberLeft,收到成员变动通知。
离开房间成功后会收到 roomStateChanged 的通知回调,ZIMRoomState 为 ZIMRoomStateDisconnected, ZIMRoomEvent 为 Success。
离开房间后,将不能收到房间内的消息。
var roomID = '';
zim.leaveRoom(roomID)
.then(function ({ roomID }) {
// 操作成功
})
.catch(function (err) {
// 操作失败
});
// 离开房间通知,通过该通知收到离开房间的用户信息
zim.on('roomMemberLeft', function (zim, { roomID, memberList }) {
console.log(roomID, memberList);
});
当所有成员离开房间后,房间将自动销毁。ZIM SDK 支持通过 ZIMRoomAdvancedConfig 设置房间延迟销毁,最大延迟为 3 小时。
开发者可以在后台调用 ZIM 服务端接口进行 销毁房间。房间被销毁后,用户通过 roomStateChanged 收到房间状态(ZIMRoomState)从 Connected
转变为 Disconnected
的事件通知。根据 ZIM SDK 版本不同,回调中描述导致房间连接状态发生变更的事件(ZIMRoomEvent)如下所示:
KickedOut
。RoomNotExist
。ZIM 房间类似于在线聊天室、网络中断会导致房间进入重连状态并抛出 roomStateChanged。详情请参考 场景 4 :ZIM 房间断网。
联系我们
文档反馈