核心概念与生命周期

1. 推荐生命周期（强烈建议）

1.1 初始化

• 在应用启动时调用一次 setup(config)
• 尽早注册长期存在的“全局”事件处理器（例如 AGENT_STATUS、RECONNECT_ATTEMPT）

1.2 登录阶段

• 调用 login(params) 与后端建立会话
• 仅在登录成功后再执行通话控制类操作（外呼、保持、转接、质检/班长监控等）

1.3 运行阶段

• 以 Promise 响应作为操作成功/失败的主要判断依据（推荐）
• 以 事件驱动 UI 状态与业务流程流转（振铃、桥接、座席状态变化等）

1.4 登出 / 销毁

• 调用 logout()
• 对你注册过的事件处理器，使用 off 移除监听

2. 操作（Promises）与事件（Events）

SDK 提供两条信息通道：

• 操作响应（Promise resolve）：用于表示后端是否成功接受/执行了该操作
• 事件通知（on/off/once）：用于表示通话生命周期与状态流转过程中实际发生了什么

典型示例：

• 当你调用 previewObCall() 时：
  • 首先会收到 previewObCallResp（操作响应）
  • 如果成功，随后会收到 previewObCallStart / previewObCallRinging / previewObCallBridge / previewObCallResult 等事件

完整时序请参见 10-Key-Flows-Sequence-Diagrams.md。

3. 关键标识：uniqueId 与 mainUniqueId

你会在操作与事件中看到两个标识（请以 06-Types.md 为准）：

• uniqueId：单条通话腿（单通道）的唯一标识
• mainUniqueId：主通话唯一标识，用于串联一整条完整通话链路

很多状态更新（例如 agentStatus）在 deviceStatus=3/4（振铃/通话中）时都会带上这两个字段。

4. 座席状态机：state / stateAction

很多事件载荷中都包含：

• state：粗粒度的座席状态（例如 idle/busy/ringing/talking）
• stateAction：更细粒度的动作/原因（例如“预览外呼客户振铃”“保持”“开始咨询”等）

你可以据此实现 UI 规则与操作保护（例如只有当座席处于 talking 时才允许执行 hold）。

参见 08-State-Machine-stateAction.md。

5. 重连（reconnectAttempt）

发生断线后，SDK 会自动尝试重连，并派发事件：

• attempt：当前尝试次数（从 1 开始）
• maxAttempts：最大尝试次数（固定为 20）

推荐实践：

• 监听 RECONNECT_ATTEMPT，当超过最大尝试次数后提示重新登录
• 关键操作（外呼/转接/班长操作）应建立在“已登录 / WebSocket 可用”的前置判断之上

载荷详情见 05-Events.md。

6. 队列与班长场景

在班长/质检监控场景下：

• 使用 getQueueStatus() 发起按需查询
• 使用 queueStatus 事件接收队列指标、队列成员与排队来电信息

相关类型与结构定义见类型