将 DataChannels 用于聊天、传感器更新和控制事件等应用消息。标准音频和视频传输请使用媒体轨道。
发布端创建一个具名通道。多个订阅者可以接收其消息,并且可以有一名被选中的订阅者在该发布者通道上回复。
你的后端发起经过认证的 SFU API 调用。浏览器和原生端点拥有对应的 WebRTC 通道。凭据和信令边界见应用架构。
要连接两个端点并发送第一条消息,请遵循完整的消息配方。传输设置把每个端点连接到 SFU。应用通道分配选择要发布或接收的具名消息。
从 DataChannel 传输已连接的发布端和订阅端开始。各自拥有自己的 SFU 会话和 PeerConnection。这些步骤只添加通道,不重复传输设置。
- 在后端调用
POST /apps/{appId}/sessions/{publisherSessionId}/datachannels/new。在请求的dataChannels数组中添加一项,设置location: "local"和所选的dataChannelName。检查发布结果,并在订阅前保留成功的分配。 - 在订阅者会话上调用
POST /apps/{appId}/sessions/{subscriberSessionId}/datachannels/new。其dataChannels项使用location: "remote"、发布者的sessionId,以及相同的dataChannelName。检查订阅结果并保留成功的分配。 - 把每个通道的
id作为channelId返回给对应端点。用pc.createDataChannel(name, { negotiated: true, id: channelId })创建浏览器通道。发布者和订阅者 ID 可以不同。此配置默认使用可靠、有序投递。 - 安装订阅者的消息处理程序,并等待通道打开。在发布者发送消息前,让订阅者通过你的应用报告就绪。确认订阅者收到该消息。
要在一个会话上分配多个通道,请在一次创建请求中批量放入这些项。该请求应全部是本地发布,或全部是远程订阅。
若需其他投递设置,按下文为每个端点的 API 分配和浏览器通道做配置。整个操作过程中遵循按会话的变更排序。Connection API 提供认证和完整请求 schema。
发布端为每个具名通道选择一种投递策略:ordered、maxRetransmits 和 maxPacketLifeTime。每个订阅者必须在其 API 请求中镜像该策略,并且每个端点用相同设置配置其浏览器 DataChannel。
同一会话或应用中的通道可以使用不同策略。为不同策略发布独立的具名通道,例如可靠的 commands 和不可靠的 player-state。发布者与其订阅者之间的不对称可靠性不在受支持契约内。
DataChannels 默认使用可靠、有序投递。为每个通道上的消息选择策略:
| 载荷 | 示例设置 | 原因 |
|---|---|---|
| 离散命令或文本 | ordered: true,无重传上限 |
保留消息顺序 |
| 彼此独立但都重要的消息 | ordered: false,无重传上限 |
允许乱序,同时保留重传 |
| 可替换状态或指针移动 | ordered: false,maxRetransmits: 0 |
允许丢失旧更新 |
可选投递字段为:
| 字段 | 含义 |
|---|---|
ordered |
省略表示 true。设为 false 以允许乱序投递。 |
maxRetransmits |
首次发送后的最大重传次数。设为零表示不重传。 |
maxPacketLifeTime |
尝试发送和重传一条消息的传输时间预算,单位为毫秒。 |
最多设置 maxRetransmits 和 maxPacketLifeTime 之一。两者都省略表示可靠投递。省略重试上限与设置 maxRetransmits: 0 不同。排序与重试行为相互独立:无序投递仍可以可靠。
maxPacketLifeTime 是传输预算,不是端到端的消息年龄截止时间。使用应用时间戳或序列号丢弃过期更新。可靠投递不提供持久存储,也不确认命令已执行。
你的应用需要把发布者的策略连同发布会话 ID 和通道名称提供给订阅者。用该策略和各自已分配的通道 ID 配置每个浏览器。协商型 DataChannels 不会自动把这些设置传达给浏览器。
waitForAck 和 canReply 按每次订阅单独选择。它们不会改变已发布通道的投递策略。
对于可替换的玩家状态,后端创建发布者分配时使用无序且不重传:
{
"dataChannels": [
{
"location": "local",
"dataChannelName": "player-state",
"ordered": false,
"maxRetransmits": 0
}
]
}检查结果后,将其通道 ID 返回给发布者。在发布者浏览器中,publisherPc 是其 PeerConnection,publisherChannelId 是其已分配 ID:
const publisherChannel = publisherPc.createDataChannel("player-state", {
negotiated: true,
id: publisherChannelId,
ordered: false,
maxRetransmits: 0,
});在每个订阅者会话上,后端用相同投递策略请求同一发布:
{
"dataChannels": [
{
"location": "remote",
"sessionId": "<PUBLISHER_SESSION_ID>",
"dataChannelName": "player-state",
"ordered": false,
"maxRetransmits": 0
}
]
}检查订阅结果后,将其通道 ID 返回给该订阅者。在订阅者浏览器中使用其自己的 subscriberPc 和 subscriberChannelId:
const subscriberChannel = subscriberPc.createDataChannel("player-state", {
negotiated: true,
id: subscriberChannelId,
ordered: false,
maxRetransmits: 0,
});云游戏为可靠键盘事件和不可靠指针移动使用独立具名通道。Pocket Radio 把可靠设备消息放在 robot 上,把可替换更新放在 spectrum 上。
在远程订阅上设置 waitForAck: true,可在订阅者发出就绪信号前暂停发布者到订阅者的投递。该字段仅适用于 location: "remote",默认值为 false。
本示例订阅一个使用可靠、有序默认值的 device-events 发布。后端在订阅者会话上创建远程订阅:
{
"dataChannels": [
{
"location": "remote",
"sessionId": "<PUBLISHER_SESSION_ID>",
"dataChannelName": "device-events",
"waitForAck": true
}
]
}协商通道打开后,订阅者发送就绪消息:
// channel is the negotiated remote DataChannel for this subscription.
if (channel.readyState === "open") {
channel.send("ready");
} else {
channel.addEventListener("open", () => channel.send("ready"), { once: true });
}SFU 会消费这条第一条消息并打开闸门。它必须在创建远程订阅后 30 秒内到达。否则 SFU 会拆除该闸控通道。重试时请创建新订阅。
此确认建立的是订阅者就绪,不是应用命令确认。在命令之前另发一条就绪消息,并在需要时使用你自己的命令 ID 和确认。
该闸门不是持久重放队列。必须投递的发布者流量应在就绪确认之后再发送。没有 canReply 时,订阅者后续消息不会转发给发布者。
当订阅者需要在同一发布者通道上回复时,设置 canReply: true。该字段仅适用于 location: "remote",默认值为 false。
回复权限具有这些属性:
- 一个发布者 DataChannel 最多由一名订阅者持有。
- 授予另一名订阅者会替换先前的选择。
- 回复只到达发布者,不会转发给其他订阅者。
你的后端必须认证操作者并授权该授予。canReply 控制的是 SFU 回传路径。谁可以获得该权限由应用状态决定。
本示例使用相同的可靠、有序 device-events 策略。后端在接收会话上创建订阅:
{
"dataChannels": [
{
"location": "remote",
"sessionId": "<PUBLISHER_SESSION_ID>",
"dataChannelName": "device-events",
"canReply": true
}
]
}协商通道打开后,该订阅者可以向发布者发送消息。
要在现有订阅上授予或撤销权限,从后端调用 PUT /apps/{appId}/sessions/{subscriberSessionId}/datachannels/update:
{
"dataChannels": [
{
"location": "remote",
"sessionId": "<PUBLISHER_SESSION_ID>",
"dataChannelName": "device-events",
"canReply": true
}
]
}设置 canReply: false 以撤销权限。用 canReply: true 更新新订阅者以转移权限。在更改应用所显示的控制者状态前,检查每一项结果。
权限授予后,现有协商通道会承载回复。应用示例见 Pocket Radio 的操作者归属 ↗和云游戏控制权归属。
一次订阅可以同时设置 waitForAck 和 canReply。其第一条消息打开就绪闸门并被消费。之后的消息在该订阅者持有回复权限期间到达发布者。
在后端发送 PUT /apps/{appId}/sessions/{sessionId}/datachannels/close,并带上该端点会话上已分配的 ID:
{
"dataChannels": [{ "id": 2 }, { "id": 3 }]
}按 id 匹配结果。close_track_error 项表示通道不存在或已关闭。保留其他失败或未报告的 ID 以便重试。参见关闭结果处理。
关闭不需要 SDP 交换。先关闭端点的通道对象,不再需要时再关闭其 PeerConnection。若仍有未完成工作,遵循拆除顺序。
DataChannels 可以把编码媒体作为二进制应用消息承载。SFU 转发这些字节,但不解释其媒体格式。发布和订阅、投递设置、传输拥塞控制以及数据统计仍然适用。
你的应用负责提供媒体分帧、兼容解码器、播放时序、同步,以及从缺失或迟到帧中恢复。控制写入节奏并限制应用缓冲区。SFU 编解码器协商、simulcast 和 WebSocket 媒体适配器作用于媒体轨道。它们不会解释嵌入 DataChannel 消息中的媒体。
运行 DataChannel 示例 ↗,建立两个端点、打开就绪闸门、发送发布者消息和订阅者回复,并比较无序更新。
该示例把 SFU App Secret 保留在本地 Node.js 服务器上。它是实验性的 localhost 练习,没有公开应用认证或房间成员资格。按其 API 和生命周期指南 ↗查看协商和拆除。