进入房间

下载pdf
更新时间:2019-12-11 11:22

1 功能简介

语聊房是维护了一组麦位状态信息的语音互动直播间。语聊房中的用户数不设上限,可以通过调用相关接口创建、加入、离开房间。加入房间将自动开始收听房间内的互动直播,并可以接收房间内的聊天消息、信令。

初始化 SDK 之后,需要先进入房间,才能使用其他功能。

IM及信令功能的使用详见 进阶功能-IM进阶功能-信令

2 使用步骤

2.1 初始化 SDK

参考文档:常用功能-初始化

2.2 设置代理

调用如下 API 设置 ZegoChatroom 代理对象。通过设置语聊房代理,可以收到语聊房内的一些事件回调,在 SDK 实例生命周期之内代理只需要设置1次,开发者可以按自己的需求在回调里实现自己的业务。

示例代码如下:

//添加语聊房代理,SDK 内部会弱引用代理对象
[ZegoChatroom.shared addDelegate:self];

...

//移除语聊房代理
[ZegoChatroom.shared removeDelegate:self];

2.3 处理登录回调

在您调用加入房间的方法时需要注意,场景的对应方法没有Block回调,房间的登录状态会在代理方法中回调。

回调代理方法如下:

//房间登录状态、事件回调
- (void)chatroom:(ZegoChatroom *)chatroom
didLoginEventOccur:(ZegoChatroomLoginEvent)event
     loginStatus:(ZegoChatroomLoginStatus)status
           error:(nullable NSError *)error;

以下是房间登录状态/事件的定义:

//语聊房登录状态
typedef NS_ENUM(NSInteger, ZegoChatroomLoginStatus) {
    kZegoChatroomLoginStatusLogout,//未登录
    kZegoChatroomLoginStatusStartLogin,//开始登录请求
    kZegoChatroomLoginStatusLogin,//已登录
    kZegoChatroomLoginStatusTempBroken,//暂时断开房间连接
};

//语聊房登录事件
typedef NS_ENUM(NSInteger, ZegoChatroomLoginEvent) {
    kZegoChatroomLoginEventLogin,//开始登录请求
    kZegoChatroomLoginEventLoginSuccess,//登录请求成功
    kZegoChatroomLoginEventLoginFailed,//登录请求失败
    kZegoChatroomLoginEventLogout,//退出登录
    kZegoChatroomLoginEventTempBroke,//房间连接暂时断开,无需额外处理,SDK会尝试自行恢复连接
    kZegoChatroomLoginEventReconnect,//房间连接恢复
    kZegoChatroomLoginEventDisconnect,//重连超时,停止重连断开房间连接,如果开启自动重连,语聊房则会在设置的期限内尝试自行恢复连接
    kZegoChatroomLoginEventKickOut,//被踢出房间,断开房间连接
};

而语聊房场景的登录状态/事件的改变如下图:

2.4 进入房间

进入房间分为传入初始麦位数和传入自定义麦位两种方法。传入初始麦位数是传入自定义麦位的便利方法,实际上会为房间初始化一组空麦位;传入自定义麦位方法可以用来实现创建房间并上麦之类的需求。

进入一个不存在的房间时会先初始化房间,而初始化房间需要先初始化麦位。由于每次进入房间,我们无法提前知道是否需要初始化麦位,所以我们目前每次进入房间都需要设置初始麦位。

麦位的介绍与操作详见:快速开始-操作麦位

进入房间示例代码如下:

[ZegoChatroom.shared joinRoomWithRoomID:@"YourRoomID"
                               roomName:@"YourRoomName" 
                              seatCount:9 
                             liveConfig:nil];

进入房间(自定义麦位)示例代码如下:

NSArray<ZegoChatroomSeat*>*seats = [self getInitialSeats];
[ZegoChatroom.shared joinRoomWithRoomID:@"YourRoomID"
                               roomName:@"YourRoomName"
                       initialSeats:seats
                     liveConfig:nil];

旧版 SDK 的进入房间分为初始化并进入房间和进入已有房间两种,考虑到提高开发者的使用便利性,目前已弃用。

2.5 离开房间

调用如下 API 离开房间,SDK 内部会自动执行断开推拉流相关操作并清理相关状态值。

示例代码如下:

//离开房间
[ZegoChatroom.shared leaveRoom];

2.6 (可选)自动重试登录

语聊房场景默认打开了自动重试登录功能,在网络连接断开的情况下,SDK 会不断重试登录。

登录自动重连配置可以通过 autoReconnectRoom 属性来动态开关。
登录自动重连超时时间可以通过 autoReconnectTimeout 属性来进行配置。

在某些情况下,SDK 会认为不适合继续重连,从而中断重试操作,具体情况如下:

//语聊房重连终止原因
typedef NS_ENUM(NSInteger, ZegoChatroomReconnectStopReason) {
    kZegoChatroomReconnectStopReasonLogout,//手动调用离开房间
    kZegoChatroomReconnectStopReasonKickout,//被服务器踢出
    kZegoChatroomReconnectStopReasonTimeout,//重连超时
    kZegoChatroomReconnectStopReasonAudience,//观众无权创建房间
    kZegoChatroomReconnectStopReasonSyncError,//重新登录房间后同步麦位失败(v1.1添加)
    kZegoChatroomReconnectStopReasonTokenError,//CustomToken非法或已过期(v1.3添加)
};

//语聊房登录重连终止回调
- (void)chatroom:(ZegoChatroom *)chatroom didAutoReconnectRoomStop:(ZegoChatroomReconnectStopReason)reason;

中断重连将会执行语聊房登录重连终止回调。

3 时序图

创建并加入、退出房间的完整调用时序图如下:

4 API参考列表

API 描述
属性
userInfo 当前用户
roomID 当前登录房间ID
liveConfig 语聊房上麦效果配置
loginStatus 房间登录状态
autoReconnectRoom 登录失败是否自动重连
autoReconnectTimeout 登录自动重连超时时间
方法
- joinRoomWithRoomID:roomName:seatCount:liveConfig: 进入房间
- joinRoomWithRoomID:roomName:initialSeats:liveConfig: 进入房间(自定义麦位)
- leaveRoom 离开当前房间

5 相关文档

登录成功后,就可以使用语聊房相关功能来实现操作麦位及更多进阶功能。

常用功能-上麦配置
常用功能-操作麦位