开放平台

三、直播SDK接口说明

1、进入和退出直播间

（1）进入直播间

接口：QSLiveSDK.enterRoom(req: QSLiveReq)

接口说明可参考第二章中joinLive()接口的参数说明。对于快速集成的客户来说，可以不关心该接口。

注意：当处于直播间小窗状态时，进入其他直播间前需要SDK集成方先退出上一场直播间，否则会直接调起上一场直播间。

（2）退出直播间

接口：QSLiveSDK.exitRoom()接口。

对于快速集成的客户来说，可以不关心该接口。

（3）监听直播间进入结果

如果想要监听进入直播间是否成功，可以调用以下接口监听进入直播间结果回调

QSLiveSDK.registerLiveConnectResult(callback: QSLiveConnectResultCallback)

private val connectCallback = object : QSLiveConnectResultCallback {
    override fun onConnectSuccess() {
        QSLiveSDK.getChatService()?.addChatCallback(chatCallback)
        QSLiveSDK.getVoiceChatService()?.addVoiceChatCallback(voiceCallback)
        fetchHistoryMessage()
        connectResultLiveData.postValue(true)
    }

    override fun onConnectFailed(code: Int, message: String) {
        connectResultLiveData.postValue(false)
    }
}

2、监听直播间推流状态

QSLiveSDK.getChatRoomService().addChatRoomCallback(callback: QSLiveRoomCallback)

 

private val heartBeatCallback = object: QSLiveRoomCallback {
    override fun onLiveStatusChanged(liveStatus: QSLiveStatus) {
        when (liveStatus) {
            QSLiveStatus.START -> "直播开始推流"
            QSLiveStatus.END, QSLiveStatus.NOT_START,
            QSLiveStatus.WAIT,
            QSLiveStatus.END_RECORDING,
            QSLiveStatus.RECORDED -> "直播已结束"
            else -> {}
        }
    }
}

 

3、获取直播间信息

获取直播间相关的信息，主要信息如下：

roomId: String —— 聊天室ID
hostName: String —— 主播名称
title: String —— 活动主题
audienceJoinUrl —— 观众链接
startTime: Long —— 活动开始时间
endTime: Long —— 活动结束时间
liveCover: String —— 活动封面

相关接口：QSLiveSDK.getLiveRoomInfo(): QSLiveRoomInfo

4、获取拉流地址

接口：QSLiveSDK.getPullUrl(conferenceId: String): PullUrlResp?

该方法可以获取到直播拉流地址。该方法是一个suspend方法，如果调用方使用Java调用，可采用如下方式：

import org.jetbrains.annotations.NotNull;

import kotlin.coroutines.CoroutineContext;

public class JavaTest {

public static void main(String[] args) {
    QSLiveSDK.INSTANCE.getPullUrl("coferenceId", new Continuation<PullUrlResp>() {
            @Override
            public void resume(PullUrlResp value) {
                // todo 处理回调数据
            }

            @Override
            public void resumeWithException(@NotNull Throwable exception) {

            }

            @NotNull
            @Override
            public CoroutineContext getContext() {
                return null;
            }
        });
    }
}

如果使用kotlin调用，需要放到协程中调用。

5、直播间观众服务

直播SDK提供直播间观众进入、退出、被踢出直播间相关的回调，方便集成方处理相关的业务逻辑

注册监听接口： QSLiveCoreSDK.getMemberService()?.addMemberCallback(memberCallbackQSLiveMemberCallback)

接口回调类：

interface QSLiveMemberCallback {
    /**
     * 有新的观众进入直播间
     */
    fun onMemberAdd(user: QSLiveUserInfo) {}

    /**
     * 有观众离开直播间
     */
    fun onMemberRemove(userId: String) {}

    /**
     * 直播间观众信息变化
     */
    fun onMemberChanged(user: QSLiveUserInfo) {}

    /**
     * 当主播把当前观众踢出直播间时会收到此回调
     */
    fun onKickOut() {}
}

6、集成观众连麦

观众连麦有两种类型：HandUpType.MESSAGE，HandUpType.SOCKET；具体使用哪种类型，取决于主持人通过何种方式获取连麦列表；如果主持人使用云会议 PC 客户端，则请使用 HandUpType.SOCKET 类型；如果主持人通过直播 sdk 获取连麦列表（即QSLiveVoiceChatService.getRequestMemberList），请使用 HandUpType.MESSAGE。

举手方法请调用 QSLiveVoiceChatService.requestVoiceChat()，并且传入相应的类型，默认类型为 HandUpType.MESSAGE。

在举手过程中，如果观众想要取消举手请调用 QSLiveVoiceChatService.cancelVoiceChat()，并传入相应的类型；

当主持人对连麦观众进行操作时，观众会收到以下回调；

interface QSLiveVoiceCallback {
    /**
     * 主播对于连麦请求的回应
     * @param status 0: 同意；1: 不同意
     */
    fun onAudienceRequestResult(status: Int) {}

    /**
     * 观众收到主持人结束发言的回调
     */
    fun onAudienceSpeakingFinish() {}
}

主持人可以邀请观众发言，通过调用 QSLiveVoiceChatService.inviteVoiceChat()；

观众会收到相应回调，观众可以调用 agreeHostInvite 或 denyHostInvite 来同意或者拒绝主持人的邀请，主持人会收到相应回调；

interface QSLiveVoiceCallback {
    /**
     *  观众收到主播的连麦邀请，观众端实现
     *  @param userId 主播邀请的观众，回调中需要比对观众自己的 id
     *  @param hostId 主播 Id
     */
    fun onHostRequest(userId: String, hostId: String) {}


    /**
     * 观众对于主播邀请连麦的回应，主持人端实现
     * @param userId 观众的 Id
     * @param status 0: 同意；1: 不同意
     */
    fun onHostRequestResult(userId: String, status: Int) {}
}

7、会中自定义 View

连麦成功后，需要会中和直播间的 UI 一致；

自定义 View 需要实现 下面的接口：

interface AudienceCustomView {
    /**
     * 提供自定义 View 在会中的共享池容器，共享池将始终填充该容器
     */
    fun getVideoContainer(): FrameLayout
}

自定义 View 的具体实现可参考 demo 中的 InteractionCustomView ；

设置自定义 View 需要实现 QSMeetingCustomViewProvider ，具体如下：

QSLiveSDK.setMeetingCustomViewProvider(object: QSMeetingCustomViewProvider(){
    override fun provideCustomView(context: Context): AudienceCustomView {
        return InteractionCustomView(context)
    }
})

8、会中共享池

如果您只是想要直播间实时的画面而不想发生页面的跳转，推荐您直接获取会中共享池；

首先在连麦成功后进行入会，注册入会的回调 ；

interface QSJoinMeetingCallback {

    /**
     * 入会成功
     */
    fun onJoinSuccess()

    /**
     * 入会过程中，用户自己取消
     */
    fun onJoinCancelled() {}

    /**
     * 入会失败
     * @param errorCode 错误码
     * @param message 错误信息
     */
    fun onJoinFailed(errorCode: Int, message: String)
}

在入会成功的回调中调用 setUpLivePool 方法；

/**
 * 向指定容器中添加共享池，注意此操作会移除该容器中的所有子视图，并添加共享池；
 * 如果你要为共享池添加控制视图，请在此方法之后设置；
 * @param container 承载共享池的容器
 */
fun setUpLivePool(container: ConstraintLayout)

9、入白名单会议

该方法不再建议使用，后续会废弃。推荐使用带jointId参数的直播链接入会。 如果预约的会议是白名单会议，需要额外调用一个接口获取jointId，在调用TangInterface.joinConference()接口时传入jointId和phone

获取jointId时，需要按角色区分嘉宾或观众。注意观众身份拿jointId时需要传入当前这场会的主持人ID（hostId）和观众链接（会议信息中的audienceUnionUrl）

QSLiveCoreSDK.getJointId(req: QSGetJointIdReq, role: QSLiveRole, callback: (success: Boolean, jointId: String, msg: String?) -> Unit)

enum class QSLiveRole {
    /**
    * 嘉宾身份
    */
    ROLE_GUEST,

    /**
    * 观众身份
    */
    ROLE_AUDIENCE
}

10、启用云会议会中的互动功能

在使用直播SDK通过嘉宾链接或观众链接入会时，如果需要互动功能，可以调用该接口

QSLiveSDK.enableMeetingInteraction()

11、添加自定义分享功能

我们提供了用户可自定义分享功能，以满足用户不同的分享需求

/**
 * 添加自定义分享类型
 * @param location 添加的位置
 * @param list 自定义分享类型
 * @param insertHead 是否从头部添加 否则从尾部添加
 */
QSLiveSDK.getLiveCustomConfig().addCustomShareTypes(location, customTypes)

/**
  * 分享位置
 */
enum class LiveShareLocation {
    ROOM,   // 直播间
    POSTER  // 海报
}

/**
  * 自定义分享数据
  */
class LiveCustomShareData {
    var customKey: String? = null  // 自定义key
    var customTitle: String? = null // 自定义标题
    var customIconRes: Int? = null // 自定义Icon 本地资源
    var customIconUrl: String? = null // 自定义Icon 网络资源
}

/**
  * 添加自定义分享回调
  */
QSLiveSDK.getLiveCustomConfig().customShareListener = object : LiveShareListener {

        override fun onShareStart(
            context: Context,
            location: LiveShareLocation,
            shareInfo: LiveCustomShareInfo
        ) {}
    }

/**
  * 自定义分享的回调数据
  */
class LiveCustomShareInfo {
    var key: String? = null            // 自定义分享的key
    var liveTitle: String? = null      // 直播标题
    var liveLogo: String? = null      // 直播logo
    var liveLink: String? = null       // 直播链接
    var liveCode: String? = null       // 直播码
    var livePoster: String? = null    // 直播海报
    var liveTimeStart: Long? = null    // 直播开启时间
    var liveTimeEnd: Long? = null      // 直播结束时间
    var liveHost: String? = null      // 直播主办方
}

/**
  * 设置已有分享功能的开关项
  */
QSLiveSDK.getLiveCustomConfig().setCustomShareConfig(customShareConfig)

/**
  * 分享功能开关项详情
  */
class CustomShareConfig(
    var linkEnable: Boolean = true  // 分享链接是否可用
    var posterEnable: Boolean = true  // 分享海报是否可用
    var posterSaveEnable: Boolean = true  // 海报下载是否可用
)

12、埋点

埋点服务在进入直播间成功以后自动启动，不再需要手动调用启动