SDK 事件与后台监听对照

@scooper/meeting-sdk 不直接重写后端 CometD/SSE 订阅逻辑。底层仍由 scooper.dispatch.js 完成后端监听，SDK 做三件事：

1. 初始化并登录 scooper.dispatch。
2. 对 scooper.dispatch.event_const 中的事件逐项 listen。
3. 转换成稳定的 SDK 事件名，通过 sdk.on(...)、callbacks.onEvent(...) 和具名 callback 对外通知。

这样第三方不用直接关心 CometD channel，但不会丢后端通知。

如果第三方页面不能直连 dispatch-web，也可以启用 backendListener。此时第三方后台通过 server/ adapter 订阅同一批 channel，再通过 SSE/WebSocket 推给前端 SDK。前端收到后仍按本文档中的 SDK 事件名触发业务 callback。

监听链路

后台 CometD/SSE channel
  -> scooper.sse.subscribe(...)
  -> scooper.dispatch fireListen(event_const.X, payload)
  -> ScooperMeetingSDK DISPATCH_EVENT_MAP
  -> sdk.on(SDK.EVENT.X, handler) / callbacks.onX(payload)

后台桥接模式：

dispatch-web CometD channel
  -> @scooper/meeting-sdk/server
  -> 第三方 SSE/WebSocket
  -> backendListener
  -> sdk.on(SDK.EVENT.X, handler) / callbacks.onX(payload)

通用监听方式

const sdk = ScooperMeetingSDK.create({
  callbacks: {
    onEvent(event, payload) {
      console.log("[all]", event, payload);
    },
    onMeetingStatus(meet) {
      console.log("会场状态", meet);
    },
    onCallStatus(status) {
      console.log("号码状态", status);
    },
    onDispatchReAuth(info) {
      console.warn("需要重新鉴权", info);
    },
  },
});

sdk.on(ScooperMeetingSDK.EVENT.MEETING_MEMBER, (member) => {
  console.log("成员变化", member);
});

后台桥接事件

启用 backendListener 时，SDK 会额外触发以下桥接状态事件：

SDK 事件	具名 callback	含义
backend:connected	onBackendListenerConnected	已连接第三方后台 SSE/WebSocket 或自定义 transport
backend:message	onBackendListenerMessage	收到后台桥接原始 envelope，随后会继续触发 envelope.event 对应的业务事件
backend:error	onBackendListenerError	后台桥接连接或解析异常
backend:disconnected	onBackendListenerDisconnected	后台桥接断开

示例：

const sdk = ScooperMeetingSDK.create({
  backendListener: {
    enabled: true,
    transport: "sse",
    url: "/scooper-events"
  },
  callbacks: {
    onBackendListenerMessage(message) {
      console.log(message.channel, message.event);
    },
    onMeetingStatus(meet) {
      console.log("会场状态", meet);
    }
  }
});

后台 channel 对照表

{accId} 表示 scooper.dispatch 登录后按账号追加的主题前缀，例如 /123/meet/status。

后台 channel	dispatch event_const	SDK 事件	具名 callback	含义
/conn	CONN_CNG	dispatch:connectionChanged	onDispatchConnectionChanged	调度登录与 CometD/SSE 连接状态变化
{accId}/server/config	CHANGE_CFG	dispatch:configChanged	onDispatchConfigChanged	后台配置变化
内部数据加载完成	DATA_INIT	dispatch:dataInitialized	onDispatchDataInitialized	调度初始数据加载完成
API 调用内部响应	METHOD_RT	dispatch:methodResponse	onDispatchMethodResponse	调度 API 统一响应，SDK 的部分 Promise 会等待它
{accId}/respData	PACK_RES_DATA	dispatch:responseData	onDispatchResponseData	后端调度协议响应包
/cdispatch/disconnect	DISPATCH_DISCONNECT	dispatch:disconnect	onDispatchDisconnect	调度连接断开
402/session 失效处理	REAUTH_NOTIFY	dispatch:reAuth	onDispatchReAuth	需要重新鉴权
{accId}/call/in	CALL_IN	call:incomingQueue	onCallIncomingQueue	呼入队列新增/移除
{accId}/call/hold	CALL_HOLD	call:hold	onCallHold	保持队列变化
{accId}/call/status	CALL_STS	call:status	onCallStatus	号码状态变化
{accId}/call/status, {accId}/call/record/status	CALL_RECORD	call:recordStatusChanged	onCallRecordStatusChanged	兼容旧录音状态事件
{accId}/call/record	RECORD_NOTIFY	call:recordNotify	onCallRecordNotify	通话记录、通话录音/录像记录
{accId}/call/recordStatus	RECORD_STATUS_NOTIFY	call:recordStatusNotify	onCallRecordStatusNotify	通话录音 ON/OFF 状态
{accId}/meet/status	MEET_STS	meeting:status	onMeetingStatus	会场状态：新增、销毁、锁定、录音、编辑等
{accId}/meet/join, {accId}/meet/leave, {accId}/meet/memsts	MEET_MEM	meeting:member	onMeetingMember	成员入会、离会、角色等级变化
{accId}/meet/status	MEET_LST	meeting:list	onMeetingList	会场列表新增/移除
{accId}/meet/record	MEET_RECORD_NOTIFY	meeting:record	onMeetingRecord	会议记录、会议录音/录像记录
{accId}/meet/memRecord	MEET_MEM_RECORD_NOTIFY	meeting:memberRecord	onMeetingMemberRecord	会场历史成员记录
{accId}/meet/memRecordDelALL	MEET_MEM_RECORD_DEL_ALL_NOTIFY	meeting:memberRecordClear	onMeetingMemberRecordClear	会场历史成员记录清空
/meetScreenSetIndex	MEET_SCREEN_SET_INDEX	meeting:screenSetIndex	onMeetingScreenSetIndex	混屏画面布局
/meetMixScreen	MEET_MIX_SCREEN	meeting:mixScreen	onMeetingMixScreen	混屏开关
/meet/meetOper	MEET_OPER_NOTIFY	meeting:memberOperation	onMeetingMemberOperation	成员操作，例如等候室
{accId}/meet/handsUp	MEET_HANDS_UP_NOTIFY	meeting:handsUp	onMeetingHandsUp	举手发言
/meetSplitScreenSetIndex	MEET_SPLIT_SCREEN_SET_INDEX	meeting:splitScreenSetIndex	onMeetingSplitScreenSetIndex	分屏画面布局
/meetSplitScreen	MEET_SPLIT_SCREEN	meeting:splitScreen	onMeetingSplitScreen	分屏开关
/meetShareTel	MEET_SHARE_TEL	meeting:shareTel	onMeetingShareTel	共享桌面号码
dispatch 内部软手柄事件	SHANDLE_CALL_NOTIFY	dispatch:softHandlerCall	onDispatchSoftHandlerCall	内置软手柄呼叫通知
dispatch 内部软手柄事件	SHANDLE_HANGUP_NOTIFY	dispatch:softHandlerHangup	onDispatchSoftHandlerHangup	内置软手柄挂断通知
/shandlePreemptRegister 与内部软手柄事件	SHANDLE_REGISTER_NOTIFY	dispatch:softHandlerRegister	onDispatchSoftHandlerRegister	内置软手柄注册、抢注册

独立 sc-soft-handler 事件

如果 SDK 配置了 softHandler.enabled = true，还会创建独立 ScSoftHandler 实例并桥接以下事件：

sc-soft-handler 事件	SDK 事件	具名 callback
register/autoRegister	softHandler:autoRegister	onEvent
registerResult	softHandler:registerResult	onSoftHandlerRegisterResult
unregisterResult	softHandler:unregisterResult	onSoftHandlerUnregisterResult
error	softHandler:error	onSoftHandlerError
incomingcall	softHandler:incomingCall	onSoftHandlerIncomingCall
incomingcall/autoAnswer / SoftHandlerEvent.IN_CALL_ANSWER	softHandler:incomingCallAutoAnswer	onSoftHandlerIncomingCallAutoAnswer
ringing	softHandler:ringing	onEvent
accepted	softHandler:accepted	onSoftHandlerAccepted
hangup	softHandler:hangup	onSoftHandlerHangup
hangupResult	softHandler:hangupResult	onEvent
callingResult	softHandler:callingResult	onEvent
answerResult	softHandler:answerResult	onEvent

SDK 会把独立 ScSoftHandler 的关键事件同步成 dispatch 兼容事件：registerResult 会触发 dispatch:softHandlerRegister，hangup 会触发 dispatch:softHandlerHangup，非 call_dispatch 的普通来电会触发 dispatch:softHandlerCall。

incomingcall/autoAnswer 是软手柄 SoftHandlerEvent.IN_CALL_ANSWER 的实际事件值，表示软手柄识别 self_call_handle 后发出的自呼叫通知。SDK 默认会在收到该事件时调用 softHandler.answer({ audioSend: true, audioRecv: true, videoSend, videoRecv: true }) 完成内部自应答；如需完全由业务层接管，可设置 softHandler.autoAnswerSelfCall = false。incomingcall 中的 notifyType=call_dispatch 会按原 dispatch 逻辑处理：如果号码命中最近一次调度应答窗口，SDK 自动应答；否则不再派发 dispatch:softHandlerCall，避免和调度呼入面板重复。可通过 softHandler.autoAnswerDispatchCall = false 关闭这一路自动应答。

运行时查看监听表

SDK 会把监听表公开出来，便于对接方自检：

console.table(ScooperMeetingSDK.DISPATCH_EVENT_MAP);
console.table(sdk.getDispatchEventMap());

扩展自定义后台事件

如果后端或定制版 scooper.dispatch.js 增加了新的 fireListen 事件，SDK 可以通过 dispatch.extraEvents 桥接，不需要改源码。

按 event_const key 桥接：

const sdk = ScooperMeetingSDK.create({
  dispatch: {
    extraEvents: [
      {
        constKey: "CUSTOM_NOTIFY",
        event: "custom:notify",
        category: "dispatch",
        backendChannels: ["/custom/notify"],
        description: "定制后台通知",
      },
    ],
  },
  callbacks: {
    onEvent(event, payload) {
      console.log(event, payload);
    },
  },
});

如果底层没有挂在 event_const 上，也可以直接按原始事件名桥接：

const sdk = ScooperMeetingSDK.create({
  dispatch: {
    extraEvents: [
      {
        rawEvent: "customNotify",
        event: "custom:notify",
        category: "dispatch",
        backendChannels: ["/custom/notify"],
        description: "定制后台通知",
      },
    ],
  },
});

SDK 生命周期与本地事件

这些事件不来自后台推送，由 SDK 自身在本地派发，DISPATCH_EVENT_MAP 里没有对应条目。

SDK 事件	常量	触发时机	callback
sdk:ready	EVENT.READY	init() 全部子系统初始化完成	onReady
sdk:error	EVENT.ERROR	任何 SDKError 产生时（含 reject 前）	onError
sdk:destroyed	EVENT.DESTROYED	destroy() 完成	—
dispatch:login	EVENT.DISPATCH_LOGIN	login() 成功	onDispatchLogin
video:init	EVENT.VIDEO_INIT	initVideo() 创建出 VideoWebRtc 实例	onVideoInit
video:playSuccess	EVENT.VIDEO_PLAY_SUCCESS	底层 playsuccess	onVideoPlaySuccess
video:playError	EVENT.VIDEO_PLAY_ERROR	底层 playError	onVideoPlayError
video:close	EVENT.VIDEO_CLOSE	底层 afterclose	onVideoClose
softHandler:ready	EVENT.SOFT_HANDLER_READY	软手柄实例创建完成	onSoftHandlerReady
meeting:alreadyInMeeting	无常量（裸字符串）	joinMeeting() 发现该号码已在会中、跳过重复请求	—

视频控制器透传事件

initVideo() 之后，SDK 会把 VideoWebRtc 的原始事件按下表转发。除上面 4 个有 EVENT 常量外， 其余只能用裸字符串监听（sdk.on("video:click", fn)），ScooperMeetingSDK.EVENT 里取不到。

底层事件	SDK 事件	是否有 EVENT 常量
initsucc	video:init	是
playsuccess	video:playSuccess	是
playError	video:playError	是
afterclose	video:close	是
msginfo	video:message	否
errorMsg	video:error	否
remoteStream	video:remoteStream	否
localStream	video:localStream	否
screenchange	video:screenChange	否
dragEnd	video:dragEnd	否
startpoll	video:startPoll	否
stoppoll	video:stopPoll	否
click	video:click	否

同理，软手柄侧的 softHandler:autoRegister、softHandler:ringing、softHandler:hangupResult、 softHandler:callingResult、softHandler:answerResult 也是裸字符串事件，没有 EVENT 常量。

注意

• SDK 只负责前端监听桥接，后台是否实际推送某个 channel 仍取决于 dispatch-web 当前版本、账号权限、调度中心配置和业务操作。
• 如果使用 dispatch.initialize("sub")，子页面事件由上层主 dispatch 转发；SDK 仍按同一事件表监听。
• 如果使用 dispatch.useNativeShandle = false，SDK 创建的独立软手柄也会把注册、挂断、普通来电映射到 dispatch:softHandler*，同时保留原始 softHandler:* 事件用于排查底层状态。