For AI agents: the complete documentation index is available at /apps-plugin/docs/llms.txt, the full documentation bundle is available at /apps-plugin/docs/llms-full.txt, and this page is available as Markdown at /apps-plugin/docs/js-api/network/connectSocket.md.

connectSocket

创建一个 WebSocket 连接,并返回可操作该连接的 SocketTask。

该 API 会同步返回 SocketTask,但连接创建本身是异步过程。调用方应先在返回的 SocketTask 上注册事件回调,再等待 onOpen 表示连接可用。后续发送消息使用 SocketTask.send,关闭连接使用 SocketTask.close。

扫码预览

扫码预览 connectSocket

支持版本

前端库版本不低于 0.0.30。

支持平台

平台支持情况
Android支持
iOS支持
PC不支持
HarmonyOS不支持

支持场景

场景支持情况
页面支持
卡片不支持

使用说明

  • 返回 SocketTask 不代表连接已经成功,连接成功以 onOpen 为准。

  • send 必须接收对象参数,并把要发送的内容放在 data 字段中。

  • 如果 protocols 非空,需要服务端支持并返回匹配的子协议。

  • 多次调用会创建多条连接,旧连接不会自动关闭;不再使用时应主动调用 close。

  • 连接失败、发送失败或关闭失败会通过 SocketTask.onError 通知。

  • 不再使用的连接应主动调用 SocketTask.close 释放资源,避免占用连接名额。

调用方式

同步 API

connectSocket(params: ConnectSocketParams): SocketTask

入参

名称类型必填默认值约束说明
headerRecord<string, string>否--WebSocket 握手阶段携带的 HTTP Header。

适合放置业务自定义 Header,例如鉴权 token、trace id、客户端能力标识等。
`referer` 由豆包客户端统一生成和管理,不应依赖该字段被业务传入值覆盖。
protocolsstring[]否--WebSocket 子协议数组。

会作为握手请求中的 `Sec-WebSocket-Protocol` 候选值传给服务端。
如果传入非空数组,服务端需要选择其中一个协议并在握手响应中返回;
服务端不支持或不返回匹配协议时,豆包客户端可能判定连接创建失败。
urlstring是--WebSocket 连接地址。

需要包含协议、域名、路径和可选 query,例如 `wss://example.com/socket?room=1`。
如果地址为空或不是字符串,本 API 会返回 `readyState` 为 `undefined` 的 SocketTask,
并异步触发 `onError`。

调用示例

import { connectSocket } from '@doubao-dev/framework/api';

const socketTask = connectSocket({
  url: 'wss://example.com/socket',
  header: { authorization: 'Bearer token' },
  protocols: ['chat.v1']
});

socketTask.onOpen(() => {
  socketTask.send({ data: 'hello' });
});

socketTask.onMessage((event) => {
  console.log(event.data);
});

socketTask.onClose((event) => {
  console.log(event.code, event.reason);
});

socketTask.onError((event) => {
  console.error(event.errMsg);
});

返回值

名称类型必返说明
close(params?: SocketTaskCloseParams) => void是关闭 WebSocket 连接。

调用后会发起关闭动作,并把 `readyState` 置为 `SocketTask.CLOSING`。
最终关闭完成时触发 `onClose`;关闭动作失败时触发 `onError`。
CLOSED3是表示 Socket 连接已关闭。

进入该状态后,该任务不会再收到新的消息,也不应继续调用 `send`。
CLOSING2是表示 Socket 连接关闭中。

调用 SocketTask.close 后,等待豆包客户端完成关闭流程时通常处于该状态。
CONNECTING0是表示 Socket 正在连接。

`connectSocket` 刚返回且豆包客户端尚未完成握手时通常处于该状态。
onClose(callback: (event: SocketTaskCloseEvent) => void) => void是监听 WebSocket 与服务器连接断开的事件。

主动关闭、服务端关闭、连接被回收都可能触发该回调。
回调触发后当前任务已经结束,不应继续使用。
onError(callback: (event: SocketTaskErrorEvent) => void) => void是监听 WebSocket 发生错误的事件。

连接创建、发送、关闭或 WebSocket 通道出现异常时触发。
该回调只表示发生错误,不等同于连接一定已经关闭;是否关闭应结合 `readyState`
或后续 `onClose` 事件判断。
onMessage(callback: (event: SocketTaskMessageEvent) => void) => void是监听 WebSocket 接收到服务器发送信息的事件。

服务端每下发一条消息都会触发一次回调。消息内容通过 `event.data` 返回,
类型可能是 `string` 或 `ArrayBuffer`。
onOpen(callback: (event: SocketTaskOpenEvent) => void) => void是监听 WebSocket 连接服务器成功的事件。

可以注册多个回调。连接成功后触发回调,并携带握手响应 Header、协议类型等信息。
通常应在该回调中或之后调用 `send`。
OPEN1是表示 Socket 连接已经打开。

进入该状态后可以调用 SocketTask.send 发送数据。
readyStatenumber | undefined是当前 Socket 连接状态 code。

可与 `CONNECTING`、`OPEN`、`CLOSING`、`CLOSED` 常量比较。
如果因为参数错误等原因导致豆包客户端没有成功创建连接,则为 `undefined`。
send(params: SocketTaskSendParams) => void是通过 WebSocket 连接发送数据。

该方法只发起发送动作,不返回发送结果。建议在 `readyState === SocketTask.OPEN`
或收到 `onOpen` 事件后调用;如果连接未就绪、数据编码失败或发送失败,
会触发 `onError`。

返回示例

{
  "readyState": 0
}

错误处理

同步调用失败时抛出错误。错误对象和通用错误码见 通用错误处理。

失败示例

{
  "errNo": 1501001,
  "errMsg": "websocket connection limit exceeded"
}

错误码

errNoerrMsg平台触发条件处理建议
104invalid parameterAndroid、iOS创建连接时 url 为空或非 ws/wss,或调用 send 时 base64 数据非法、dataType 不支持传入合法的 ws/wss url 与受支持的发送数据后重试。
110API call prohibitedAndroid、iOSsocket url 未通过域名白名单校验确认目标域名已在应用插件中配置后重试。
116resource not foundAndroid、iOS对已关闭或不存在的 socketTaskId 调用 send/close仅在 onOpen 后、onClose 前操作连接,不要复用已关闭的连接。
305network failureAndroid、iOS建立连接、发送或关闭过程中发生网络错误检查网络连接,必要时重新建立连接。
1501001websocket connection limit exceededAndroid、iOS同一应用插件的 WebSocket 连接数超过上限关闭不再使用的连接后重试。
1501002websocket is not openiOS连接尚未打开或已关闭时调用 send在收到 onOpen 事件后再发送数据。

通用错误码

errNoerrMsg说明平台
102internal error内部错误Android
113bridge unavailableJS API 暂不可用Android、iOS

平台差异

  • Android:建立连接失败统一返回 102;send 在连接未打开时返回 305 或 116。
  • iOS:send 在连接未打开时返回 1501002。

已知限制与注意事项

  • 同一应用插件内最多同时保持 5 条 WebSocket 连接,超过上限时 connectSocket 会立即同步失败并通过 SocketTask.onError 通知。