助教端 WEB SDK API

[TOC]

生命周期

概述

初始化 SDK、登录/退出房间、页面卸载时销毁资源。演示页在 demo-boot.js 中调用 DWLive.init，在 onbeforeunload 中调用 DWLive.destroy；被踢出时在 onKickOut 中调用 logout 并跳转登录页。

相关 API

初始化

初始化 SDK

DWLive.init(options)

options 参数说明（助教场景常用）：

使用示例：

DWLive.init(window.DEMO_CONFIG.dwInit)

登录

未传有效 token 时 SDK 内部会自动发起登录；演示页在 onLoginError 中可配置 DEMO_CONFIG.retryLoginOnError 后手动重试。

DWLive.login(opt)

opt 与 init 入参字段一致（至少包含 userid、roomid）。

退出直播间

DWLive.logout(object)

object 参数说明：

使用示例：

DWLive.logout({
  success: function () {
    window.location.href = './login'
  },
  error: function (data) {
    console.warn(data.msg)
  }
})

销毁 SDK

DWLive.destroy()

页面关闭前建议调用，释放播放器、Socket、画板等资源。

使用示例：

window.onbeforeunload = function () {
  if (typeof DWLive.destroy === 'function') {
    DWLive.destroy()
  }
}

登录回调

登录成功

DWLive.onLoginSuccess = function (data) {}

返回 data 数据说明（节选，以实际登录结果为准）：

{
  viewer: {
    groupId: "分组ID"
  }
  // 登录成功后 SDK 会写入 DWLive.token、DWLive.viewerid、DWLive.viewername 等
}

使用示例（初始化 hdChat，见 demo-boot.js）：

DWLive.onLoginSuccess = function (data) {
  DWLive.groupId = data.viewer.groupId
  window.hdchat = new hdChat({
    container: document.getElementById('chat'),
    roomId: DWLive.roomid,
    accountId: DWLive.userid,
    token: DWLive.token,
    user: { role: 2, userid: DWLive.viewerid, username: DWLive.viewername }
  })
}

登录失败

DWLive.onLoginError = function (error) {}

被踢出直播间

DWLive.onKickOut = function (data) {}

使用示例：

DWLive.onKickOut = function () {
  DWLive.logout({
    success: function () {
      window.location.href = './login'
    }
  })
}

房间与状态

概述

获取直播状态、在线人数、房间上下文（含在线用户列表、房间设置）；监听开播/停播、主画面切换等信令。演示页 demo-live-status-assistant.js 组合 DWLive.livestatus 与多个回调展示状态条；demo-user-assistant.js、demo-room-base-assistant.js 依赖 onRoomContext。

相关 API

属性

直播状态

DWLive.livestatus

说明：

房间上下文

监听房间上下文推送

SDK 约每 15s 与服务端同步一次，助教端在 assistantsdk/socket/assistant.js 中订阅 room_context 并回调。

DWLive.onRoomContext = function (res) {}

返回 res 数据说明（结构以服务端为准，演示中常用字段）：

{
  users: [ // 在线用户列表
    {
      userId: "用户ID",
      userName: "昵称",
      userRole: "student",
      groupId: "分组ID"
    }
  ],
  roomSettings: {
    room_base_user_count: 100 // 当前人数展示基数
  }
}

直播事件

监听直播开始

DWLive.onLiveStart = function (data) {}

返回 data 数据说明：

{
  "action": "publish_stream"
}

监听直播停止

DWLive.onLiveEnd = function (data) {}

监听在线人数

DWLive.onUserCountMessage = function (j) {}

监听房间设置变更

DWLive.onRoomSettings = function (data) {}

主画面切换

监听视频/文档主画面切换

DWLive.onSwitchVideoDoc = function (main) {}

main 为布尔或业务约定值，表示当前是否以视频为主画面。演示页同步 #doc-main 的 data-module 并调用 switchPptToVideo()。

监听线路/源切换

DWLive.onSwitchSource = function (data) {}

data 为 JSON 字符串，解析后含 source_type 等字段。

互动与聊天配置回调

互动 Token

DWLive.onInteractionToken = function (data) {}

用户导出等 REST 接口需 hdChat 侧 interactiveToken，演示页从 hdChat 实例读取。

互动设置

DWLive.onInteractionSettings = function (data) {}

互动断开

DWLive.onInteractionDisconnect = function (res) {}

自定义表情配置

DWLive.onChatCustomEmoji = function (data) {}

线路

概述

获取 CDN 线路列表、切换线路、只听音频；演示见 demo/js/ui.js（「优选网络」「只听音频」按钮）。

相关 API

获取线路列表

DWLive.getLine()

返回 data 数据说明（H5 播放器示例）：

[
  {
    "selected": true,   // 当前选中线路
    "name": "线路_1"
  },
  {
    "selected": false,
    "name": "线路_2"
  }
]

Flash 播放器返回 JSON 数组，字段含 index、name、select（'1' 表示当前线路）等，与 ui.js 中 net.select == '1' 判断一致。

获取当前线路索引

DWLive.getCurrentLine()

返回：当前线路索引（number），与 changeLine 入参一致。

切换线路

DWLive.changeLine(lineIndex, callback)

使用示例：

var lines = DWLive.getLine()
// 用户选择后
DWLive.changeLine(selectedIndex)

只听音频

DWLive.onlyAudio()

切换只听音频/恢复视频；H5 播放器可能无效果。演示中配合 #btn-audio 按钮 toggle 样式 only-audio-enable。

播放器与其它

DWLive.switchFullScreen(flag)

开始播放回调

DWLive.on_live_play = function () {}

文档与跑马灯

概述

文档列表、翻页、适宽/适高、文档模式；开播后根据 DWLive.marquee 在视频区或文档区展示跑马灯。演示见 ui.js、demo-boot.js 中 switch_main_show_marquee。

相关 API

文档

文档模式常量

DWLive.DocModeType.NormalMode  // 0 普通模式
DWLive.DocModeType.FreeMode    // 1 自由模式

获取文档列表

DWLive.getDocs(callback)

DWLive.getDocs(function (data) {
  console.log(data)
})

设置文档模式

DWLive.setDocMode(type)

跳转到指定文档页

DWLive.changePageTo(docId, pageIndex)

文档区域自适应

DWLive.docAdapt(enable)

演示在 window.on_hdLive_drawPanel_complete 中调用 DWLive.docAdapt(true)。

跑马灯

视频区显示跑马灯

DWLive.showMarquee(marquee)

关闭视频区跑马灯

DWLive.closeMarquee()

文档区显示跑马灯

DWLive.showMarqueeDoc(marquee)

marquee 可为 JSON 字符串或对象，内容来自登录后 DWLive.marquee。

关闭文档区跑马灯

DWLive.closeMarqueeDoc()

使用示例（主画面切换后，demo-boot.js）：

window.switch_main_show_marquee = function () {
  var m = DWLive.marquee
  if (!$('#doc-main').attr('data-module')) {
    DWLive.closeMarquee()
    DWLive.showMarqueeDoc(typeof m === 'string' ? m : JSON.stringify(m))
  } else {
    DWLive.closeMarqueeDoc()
    DWLive.showMarquee(m)
  }
}

问答

概述

助教发布/回复问答、全体禁言问答与聊天；信令通过 Socket 下发。演示见 demo-qa-assistant.js。

相关 API

主动调用

发布问答（上墙）

DWLive.publishQuestion(questionId, callback)

回复问答

DWLive.answerQuestion(data, callback)

data 参数说明：

使用示例：

DWLive.answerQuestion({
  questionId: 'xxx',
  content: '回复内容',
  isPrivate: 0,
  userId: DWLive.viewerid,
  userName: DWLive.viewername,
  questionUserId: '提问用户ID'
})

全体禁言问答

DWLive.silenceQa(callback)

恢复问答

DWLive.unSilenceQa(callback)

全体禁言聊天

DWLive.silenceChat(callback)

恢复聊天

DWLive.unSilenceChat(callback)

以上四个方法的 callback(err) 在 emit 异常时返回错误对象。

信令回调

收到提问

DWLive.onQuestion = function (j) {}

返回数据结构（JSON 字符串或对象，演示中解析后）：

{
  "action": "question",
  "value": {
    "id": "问题ID",
    "userId": "提问用户ID",
    "userName": "昵称",
    "content": "问题内容",
    "groupId": "分组ID",
    "publish": false,
    "extra": {}
  }
}

收到回答

DWLive.onAnswer = function (j) {}

问答发布成功通知

DWLive.onQaPublish = function (data) {}

返回 data 数据说明：

{
  "value": {
    "questionId": "已发布的问题ID"
  }
}

聊天管控与用户

概述

对单个用户禁言、IP 禁言、踢出；在线/离线用户查询与导出。列表数据主要来自 onRoomContext；导出依赖 hdChat 互动 token。演示见 demo-user-assistant.js。

相关 API

用户管控

用户禁言

DWLive.chatBan(opt, callback)

opt 参数说明：

解除用户禁言

DWLive.chatUnBan(opt, callback)

IP 禁言

DWLive.ipBan(opt, callback)

解除 IP 禁言

DWLive.ipUnBan(opt, callback)

踢出用户

DWLive.kickout(opt, callback)

使用示例：

DWLive.kickout({ viewerid: userId }, function () {
  console.log('已踢出')
})

演示中禁言/解禁也可优先使用 hdChat.banUser 等 UI 侧 API，与运营端行为一致；REST/Socket 双路径以业务选型为准。

用户导出与离线查询

离线用户查询

DWLive.hdSearchOfflineUsers(params, callback)

params 参数说明：

离线用户导出

DWLive.hdExportOfflineUsers(params, callback)

参数同 hdSearchOfflineUsers；成功回调 callback({ success: true, blob })，前端触发下载。

在线用户导出

DWLive.hdExportOnlineUsers(params, callback)

params 参数说明：

在线人数基数

概述

设置观看端展示的在线人数基数；读取当前基数随 DWLive.onRoomContext 中 roomSettings.room_base_user_count 更新。演示见 demo-room-base-assistant.js（互动工具「设置用户基数」）。

相关 API

设置

设置人数基数

DWLive.roomBaseUserCount(num, callback)

下发信令格式（经 Pusher）：

{
  "action": "room_base_user_count",
  "value": {
    "baseCount": 500
  }
}

使用示例：

DWLive.roomBaseUserCount(500, function (err) {
  if (err) console.warn(err)
})

读取

监听当前基数（随房间上下文）

DWLive.onRoomContext = function (res) {}

从 res.roomSettings.room_base_user_count 读取当前基数（演示在 DemoRoomBaseUserPanel_onRoomContext 中同步到弹层输入框）：

window.DemoRoomBaseUserPanel_onRoomContext = function (res) {
  var rs = res && res.roomSettings
  if (!rs) return
  var v = rs.room_base_user_count
  if (v !== undefined && v !== null && v !== '') {
    console.log('当前人数基数', v)
  }
}

SDK 约每 15s 与服务端同步 room_context（见 assistantsdk/socket/assistant.js），设置成功后下次推送会带上新基数。

广播

概述

历史广播列表、删除广播走 DWLive REST；实时发布在演示中走 hdChat（releaseBroadcast），与运营端一致。Socket 推送 broadcast_msg / broadcast_action 供各端同步。演示见 demo-broadcast-assistant.js。

相关 API

DWLive（REST / Socket）

获取历史广播列表

DWLive.getBroadcastList(opt)

opt 参数说明：

返回列表项示例：

[
  {
    id: "广播ID",
    content: "广播内容",
    createTime: "2024-01-01 12:00:00"
  }
]

使用示例：

DWLive.getBroadcastList({
  success: function (rows) {
    console.log(rows)
  },
  fail: function () {
    console.warn('加载失败')
  }
})

删除历史广播

DWLive.deleteBroadcast(broadcastId, opt)

使用示例：

DWLive.deleteBroadcast('广播ID', {
  success: function () {
    console.log('已删除')
  },
  fail: function () {
    console.warn('删除失败')
  }
})

演示页删除走 hdchat.removeBroadcast(id)；deleteBroadcast 为 SDK REST 等价能力，可按业务选型。

发布广播（Socket 实时）

DWLive.broadcastMsg(content, callback)

经 Socket 下发 broadcast_msg；观看端在 onBroadcastMsg 中收到。演示发布优先用 hdChat，与运营端 IM 一致。

监听广播消息

DWLive.onBroadcastMsg = function (value) {}

返回 value 数据说明：

{
  "content": "广播正文"
}

监听广播删除

DWLive.removeBroadcastMsg = function (data) {}

对应 Socket 事件 broadcast_action，各端同步移除历史条目。

hdChat（发布 / 删除 / 事件）

发布广播

hdchat.releaseBroadcast(content)

返回 Promise 或 jQuery Deferred；内容为空或超长时返回 false。字数上限见 hdchat.options.account 配置。

使用示例：

var ret = hdchat.releaseBroadcast('广播内容')
if (ret === false) {
  alert('内容为空或超长')
  return
}
ret.then(function () {
  console.log('发布成功')
})

删除广播

hdchat.removeBroadcast(broadcastId)

IM 事件：广播发布 / 删除

hdchat.on('broadcastRelease', function (payload) {})
hdchat.on('broadcastRemove', function (payload) {})

演示在 DemoBroadcastPanel_attachHdchat 中订阅，用于刷新历史列表 UI。

公告

概述

公告发布/删除在演示中通过 hdChat 完成；DWLive 亦提供等价 REST 封装（releaseAnnouncement / removeAnnouncement），登录后可通过 Socket announcement 或 onAnnouncementShow 同步展示。见 demo-announcement-assistant.js。

相关 API

hdChat（演示主路径）

发布公告

hdchat.releaseAnnouncement(content)

返回 Promise / jQuery Deferred；校验失败返回 false。

使用示例：

var ret = hdchat.releaseAnnouncement('公告内容')
if (ret === false) {
  alert('内容为空或超长')
  return
}
ret.then(function () {
  console.log('发布成功')
})

删除公告

hdchat.removeAnnouncement()

无参数，删除当前房间公告。

事件：公告展示 / 更新

hdchat.on('announcementShow', function (content) {})
hdchat.on('announcementUpdate', function (res) {})

announcementUpdate 返回 res 示例（删除时）：

{
  "action": "remove"
}

初始化后可通过 hdchat.announceMentData 读取当前公告文案。

DWLive（REST / Socket）

发布公告

DWLive.releaseAnnouncement(content, opt)

使用示例：

DWLive.releaseAnnouncement('公告内容', {
  success: function () {
    console.log('发布成功')
  },
  fail: function (msg) {
    console.warn(msg)
  }
})

删除公告

DWLive.removeAnnouncement(opt)

登录后公告展示（REST 拉取）

DWLive.onAnnouncementShow = function (announcement) {}

进入房间后若已有公告，SDK 在 getLiveRoomInfo 流程中回调，参数为公告字符串。

Socket：公告发布 / 删除

DWLive.onAnnouncementRelease = function (announcement) {}
DWLive.onAnnouncementRemove = function (data) {}

对应 Socket 事件 announcement，action 为 release / remove。

随堂测（助教）

概述

助教发布随堂测、停止答题、关闭、发送奖杯；统计与进行中状态通过 REST 与 Socket 信令获取。演示见 demo-practice-assistant.js。

相关 API

助教操作

发布随堂测

DWLive.hdPublishPractice(encodedData, callback)

type 与题目选项示例（演示）：

var payload = {
  type: 0, // 0 单选 1 多选 2 判断，以 TYPE_MAP 为准
  options: [
    { index: 0, isCorrect: 1 },
    { index: 1, isCorrect: 0 }
  ]
}
var dataStr = encodeURIComponent(JSON.stringify(payload))
DWLive.hdPublishPractice(dataStr, function (res) {
  if (res.success && res.datas && res.datas.practiceId) {
    console.log('practiceId', res.datas.practiceId)
  }
})

停止答题

DWLive.hdStopPractice(practiceId, callback)

关闭随堂测

DWLive.hdClosePractice(practiceId, callback)

发送奖杯

DWLive.hdSendPracticePrize(prize, callback)

prize 参数说明：

{
  viewerId: "学员ID",
  viewerName: "学员昵称",
  type: 1  // 奖杯类型
}

查询与统计

获取随堂测题目信息

DWLive.getPracticeInfomation(practiceId, callback)

观看端/调试场景拉取单次随堂测详情；助教发布后以 practiceId 轮询统计为主。

获取随堂测统计

DWLive.getPracticeStatisInfo(practiceId, callback)

停止答题后拉取各选项人数、正确率等；演示在 onPracticePublishStop 中调用并渲染结果面板。

返回 data 结构（节选，以 interaction 域名为准）：

{
  "success": true,
  "data": {
    "practiceId": "xxx",
    "options": [ /* 各选项统计 */ ],
    "ranking": [ /* 排名 */ ]
  }
}

提交随堂测（调试 / 模拟学员）

DWLive.submitPracticeInfo(practiceId, opt, callback)

演示在 demo-boot.js 调试按钮中模拟学员提交。

回调

房间进行中活动（登录后拉取）

DWLive.onRoomOngoing = function (data) {}

进入房间后 SDK 请求 ongoing 接口；若存在进行中的随堂测，data.data.interaction[0].id 为 practiceId。

返回 data 示例：

{
  "success": true,
  "data": {
    "interaction": [
      { "id": "进行中的 practiceId", "type": "practice" }
    ]
  }
}

Socket：随堂测发布

DWLive.onPracticePublish = function (data) {}

返回 data 示例：

{
  "practiceId": "xxx"  // 或 practice_id
}

Socket：停止答题

DWLive.onPracticePublishStop = function (data) {}

返回 data 示例：

{
  "practiceId": "xxx"
}

Socket：关闭随堂测

DWLive.onPracticeClose = function (data) {}

Socket：奖杯发送

DWLive.onPrizeSend = function (data) {}

返回 data 示例：

{
  "viewerId": "学员ID",
  "viewerName": "昵称"
}

演示在 demo-practice-assistant.js 中通过 chainDwLive 链式挂载以上 Socket 回调。

抽奖（助教 2.0）

概述

发起、取消、停止抽奖，查询状态与中奖记录；支持虚拟用户与在线用户搜索。REST 走 DWLive.hdLottery*，Socket 推送 lottery_create / lottery_cancel / lottery_complete 供 UI 同步。演示见 demo-lottery-assistant.js。

相关 API

REST 主动调用

发起抽奖

DWLive.hdLotteryCreate(bodyData, callback)

bodyData 主要字段（与演示表单一致）：

{
  liveId: "",                    // 当前直播 id，DWLive.liveId || DWLive.liveid
  participatingUserType: 0,      // 参与用户范围：0 全部 1 在线 等
  lotteryType: 0,                // 模板类型
  winnerNum: 3,                  // 中奖人数
  prize: { name: "奖品名称" },
  isPreset: false,               // 是否预设中奖用户
  presetWinnerUsers: [],         // { userId, userName }
  virtualWinners: [],            // 虚拟用户列表
  isUserCollection: false,       // 是否收集中奖信息
  winningUsersCollectTemplates: [ // 收集项模板
    { title: "名称", tips: "请输入您的姓名" }
  ]
}

成功回调 res.success 为 true 时，res.datas.lotteryId 为本轮抽奖 id。

取消抽奖

DWLive.hdLotteryCancel({ lotteryId: "xxx" }, callback)

停止抽奖

DWLive.hdLotteryStop({ lotteryId: "xxx" }, callback)

查询抽奖进行状态

DWLive.hdLotteryStatus(callback)

返回 res 示例（节选）：

{
  "success": true,
  "data": {
    "lotteryId": "进行中的抽奖ID",
    "status": 1
  }
}

演示打开配置弹层时轮询，用于恢复进行中的抽奖 UI。

中奖记录

DWLive.hdLotteryWinningInfo(callback)

获取虚拟用户

DWLive.hdLotteryGetVirtualUsers({ type: 0, length: 10 }, callback)

返回 users 示例：

{
  "success": true,
  "data": {
    "users": [
      { "userId": "...", "userName": "虚拟用户1" }
    ]
  }
}

搜索在线用户（预设中奖）

DWLive.hdLotterySearchOnlineUsers(userName, callback)

成功时 data.onlineUsers: [{ userId, userName }]。

Socket 回调

抽奖创建

DWLive.onLotteryCreated = function (data) {}

返回 data 示例：

{
  "lotteryId": "本轮抽奖ID"
}

抽奖取消

DWLive.onLotteryCanceled = function (data) {}

抽奖结束

DWLive.onLotteryCompleted = function (data) {}

演示在 demo-lottery-assistant.js 中链式挂载以上三个回调，与 REST 操作结果双通道更新 UI。

常见错误码（发起失败）

打卡

概述

直播打卡开始/结束信令与查询、提交接口。演示在 demo-boot.js 中绑定回调与调试按钮。

相关 API

获取打卡信息

DWLive.getHdInquirePunchInformation(callback)

提交打卡（结束打卡）

DWLive.hdCommitPunch(punchId, callback)

回调

打卡开始

DWLive.onHdLiveStartPunch = function (data) {}

使用示例：

DWLive.onHdLiveStartPunch = function () {
  DWLive.getHdInquirePunchInformation(function (res) {
    console.log('打卡信息', res)
  })
}

打卡结束

DWLive.onHdLiveStopPunch = function (data) {}

页面全局钩子

概述

非 DWLive 方法，但与演示页播放器、文档区联动相关。

相关 API

文档画板就绪

window.on_hdLive_drawPanel_complete = function () {}

使用示例：

window.on_hdLive_drawPanel_complete = function () {
  DWLive.docAdapt(true)
}

主画面切换后同步跑马灯

window.switch_main_show_marquee = function () {}

见本文「文档与跑马灯」章节示例；由页面在切换视频/文档主区域后调用。

主画面视频/文档切换（页面函数）

switchPptToVideo()

演示在 onSwitchVideoDoc、onSwitchSource 中与 #doc-main 的 data-module 联动调用。

附录：演示模块与 API 对照