即时通讯
  • iOS
  • Android : Java
  • macOS
  • Windows
  • Web
  • 小程序
  • Flutter
  • Unity3D
  • uni-app
  • React Native
  • 产品简介
  • 下载
  • 快速开始
    • 跑通示例源码
    • 实现基本消息收发
  • 用户相关
  • 房间相关
  • 群组相关
  • 消息相关
  • 呼叫邀请
  • 会话管理
  • 离线推送
  • 客户端 API
  • 服务端 API
  • SDK 错误码
  • 常见问题
  • 文档中心
  • 即时通讯
  • 房间相关
  • 房间管理

房间管理

更新时间:2023-08-28 14:59

功能简介

ZIM SDK 提供多人房间聊天功能,支持用户向房间内发送文本消息或自定义消息,实现了多人在线交流、同步分享。

多人房间聊天功能可应用于小班课或者会议室等场景,房间成员数量上限请参考 计费说明

前提条件

在实现“房间管理”功能之前,请确保:

实现流程

用户可以通过以下两种方式,创建房间并进入房间。

房间内的用户,可以通过 sendRoomMessage 接口,向房间内发送消息,详情请参考 收发房间消息

如果 roomID 已存在:

如果 roomID 不存在:

  • 调用 createRoom 接口,可以直接创建、并加入到此房间内。
  • 调用 enterRoom 接口,会直接创建一个房间、并进入到此房间内。

创建房间、加入房间

以下流程中,我们以客户端 A 创建并加入房间,客户端 B 加入房间为例。

1. 注册回调

所有进入房间的用户,都需注册 onRoomMemberJoinedonRoomMemberLeftonRoomStateChanged 回调,用于监听房间其他成员的变动和接收房间连接状态发生改变的事件通知。

注册 onRoomMemberJoined 回调示例源码:

@Override
public void onRoomMemberJoined(ZIM zim, ArrayList<ZIMUserInfo> memberList, String roomID) {
    super.onRoomMemberJoined(zim, memberList, roomID);
    }

注册 onRoomMemberLeft 回调示例源码:

@Override
public void onRoomMemberLeft(ZIM zim, ArrayList<ZIMUserInfo> memberList, String roomID) {
    super.onRoomMemberLeft(ZIM zim, ArrayList<ZIMUserInfo> memberList, String roomID);
}

注册 onRoomStateChanged 回调示例源码:

@Override
public void onRoomStateChanged(ZIM zim, ZIMRoomState state, ZIMRoomEvent event, JSONObject extendedData, String roomID) {
    super.onRoomStateChanged(zim, state, event, extendedData, roomID);
}

2. 创建房间

客户端 A 登录后,创建一个房间,可以调用 createRoom 接口,传入 ZIMRoomInfo 信息,即可创建并加入房间。同时可以通过错误码 ZIMError 的参数值,判断是否创建成功。相关错误码请查看 常见错误码

创建成功后会收到 onRoomStateChanged 的通知回调,ZIMRoomState 为 CONNECTED, ZIMRoomEvent 为 SUCCESS。

  • “roomID”、“roomName” 支持开发者自定义规则生成。建议开发者将 “roomID” 设置为一个有意义的值,可将其与自己的业务账号系统进行关联。
  • 调用 createRoom 接口创建房间后,会直接加入房间,无需再调用 joinRoom 接口加入房间。
// roomID 最大 32 字节的字符串。仅支持数字,英文字符 和 '!', '#', '$', '%', '&', '(', ')', '+', '-', ':', ';', '<', '=', '.', '>', '?', '@', '[', ']', '^', '_', '{', '}', '|', '~'。
// roomName 最大 64 字节的字符串,无特殊字符限制。
ZIMRoomInfo zimRoomInfo = new ZIMRoomInfo();
zimRoomInfo.roomID = roomID;
zimRoomInfo.roomName = roomName;
zim.createRoom(zimRoomInfo, new ZIMRoomCreatedCallback() {
    @Override
    public void onRoomCreated(ZIMRoomFullInfo zimRoomFullInfo, ZIMError error) {
        if (error.code == ZIMErrorCode.SUCCESS) {
            // 创建成功             
        } else {
            // 创建失败             
        }                                
    }
});

3. 加入房间

客户端 B 加入房间,可以调用 joinRoom 接口,传入由 A 创建的房间 roomID,即可加入房间。同时可以根据错误码 ZIMError 的参数值,判断用户是否加入成功。相关错误码请查看 常见错误码

加入成功后会收到 onRoomStateChanged 的通知回调,ZIMRoomState 为 CONNECTED, ZIMRoomEvent 为 SUCCESS。

zim.joinRoom(roomID, new ZIMRoomJoinedCallback() {
    @Override
    public void onRoomJoined(ZIMRoomFullInfo zimRoomFullInfo, ZIMError error) {
        if (error.code == ZIMErrorCode.SUCCESS) {
            // 加入房间成功。
        } else {
            // 加入房间失败。
        }     
    }
});

4. 房间成员变动通知

当房间有其他成员加入时,可以使用 setEventHandler 的回调接口 onRoomMemberJoined 方法,实现对其他房间成员加入的监听。

例如,当客户端 B 加入由 A 创建的房间时,A 将收到房间内成员变动的通知。

zim.setEventHandler(new ZIMEventHandler() {
    // 加入房间通知
    @Override
    public void onRoomMemberJoined(ZIM zim, ArrayList<ZIMUserInfo> memberList, final String roomID) {
    // 通过该通知收到加入房间的用户信息        
    }
});

进入房间

以下流程中,我们以客户端 X 创建并进入房间,客户端 Y 直接进入房间为例。

  1. 注册 onRoomMemberJoinedonRoomMemberLeftonRoomStateChanged 回调,详情请参考 创建房间、加入房间 - 1. 注册回调
  2. 客户端 X 登录后,调用 enterRoom 接口,传入 ZIMRoomInfo 信息,进入房间;如果传入的 roomID 不存在,将会自动创建一个房间并进入该房间。
  3. 客户端 Y 登录后,调用 enterRoom 接口,传入由 X 创建的房间 roomID,直接进入房间。
  4. 进入房间成功后会收到 onRoomStateChanged 的通知回调,ZIMRoomState 为 CONNECTED, ZIMRoomEvent 为 SUCCESS。
  5. 房间内的用户,同样可以使用 setEventHandler 的回调接口 onRoomMemberJoined 方法,实现对房间内成员加入的监听。
ZIMRoomInfo zimRoomInfo = new ZIMRoomInfo();
zimRoomInfo.roomID = roomID;
zimRoomInfo.roomName = roomName;

ZIMRoomAdvancedConfig config = new ZIMRoomAdvancedConfig();

zim.enterRoom(zimRoomInfo, config, new ZIMRoomEnteredCallback() {
    @Override
    public void onRoomEntered(ZIMRoomFullInfo zimRoomFullInfo, ZIMError error) {
        if (error.code == ZIMErrorCode.SUCCESS) {
            // 进入成功             
        } else {
            // 进入失败             
        }                                
    }
});

离开房间

用户如果想要离开房间,可以调用 leaveRoom 接口,传入房间的 roomID,即可退出此房间;房间内的其他用户可以通过 setEventHandler 的回调接口 onRoomMemberLeft,收到成员变动通知。

离开房间成功后会收到 onRoomStateChanged 的通知回调,ZIMRoomState 为 DISCONNECTED, ZIMRoomEvent 为 SUCCESS。

离开房间后,将不能收到房间内的消息。

// 离开房间
zim.leaveRoom(roomID, new ZIMRoomLeftCallback() {
            @Override
            public void onRoomLeft(String roomID, ZIMError errorInfo) {

            }
});
zim.setEventHandler(new ZIMEventHandler() {
     // 离开房间通知
    @Override
    public void onRoomMemberLeft(ZIM zim, ArrayList<ZIMUserInfo> memberList, final String roomID) {
    // 通过该通知收到离开房间的用户信息        
    }
});

当所有成员离开房间后,房间将自动销毁。ZIM SDK 支持通过 ZIMRoomAdvancedConfig 设置房间延迟销毁,最大延迟为 3 小时。

网络中断对房间生命周期的影响

ZIM 房间类似于在线聊天室、网络中断会导致房间进入重连状态并抛出 onRoomStateChanged。详情请参考 场景 4 :ZIM 房间断网

本篇目录