Skip to content

Skill references guides sdk transports

AKStream documentation edited this page Nov 12, 2026 · 2 revisions

WebRTC 的自动、UDP 与 TCP 接入

Web/H5、Android、iOS 和 UniApp 的 Web/原生 RTC 端统一使用 mediaTransport。默认 auto;显式 udp 或 tcp 使用对应的 TURN 中继。请使用包含 TURN/TCP 兼容修复的 MediaServer 与同批 SDK;旧安装包不会因更新 SDK 或文档而自动获得该服务端能力。

模式 客户端行为 适用场景
auto 保留 connection-settings 下发的 ICE 策略与地址,允许直连和中继,由 ICE 选路 常规业务默认;通常直连开销更低
udp 只保留 UDP TURN 地址,强制 relay,不回退到 TCP 或直连 明确验证 UDP 中继、统一中继策略
tcp 只保留 TCP TURN 地址,强制 relay,不回退到 UDP 或直连 客户端网络禁止 UDP,或明确要求客户端经 TCP 中继

这里的 UDP/TCP 描述客户端到 TURN这一段。常规 TURN/TCP 的另一段仍是 TURN → MediaServer:UDP,媒体服务器侧仍需允许该 UDP 通信。TCP 在丢包时的重传和队头阻塞可能增加延迟;它是受限网络的接入选择,不是画质或流畅度保证。

最少代码

Web/H5:

const rtc = new AkRtcWebClient(serverUrl, events, { mediaTransport: 'tcp' })
await rtc.join(roomId, accessTicket, { platform: 'pc-web' })
// 摄像头、麦克风、订阅和屏幕共享都使用同一会话策略。

也可以在入会前调用 rtc.setMediaTransport('udp'),用 rtc.getMediaTransport() 读取选择。auto、udp、tcp 以外的值会报参数错误。入会后切换须先 leave(),重新设置并使用新票据入会;已消耗的一次性票据不能重复使用。

Android:

client.setMediaTransport("tcp");
client.joinWithAccessTicket(serverUrl, roomId, accessTicket, passcode);

iOS:

try client.setMediaTransport("tcp")
client.joinWithAccessTicket(baseURL: serverUrl, roomID: roomId,
                           accessTicket: accessTicket, passcode: passcode)

两端都提供 getMediaTransport()。iOS ReplayKit 和 WebView 原生屏幕共享继承主会话的选择;集成时须一起更新 SDK 和宿主分发物。

UniApp 的 UTS 创建选项或 join 载荷均可设置,入会载荷优先:

const id = createRtcClient({ serverUrl, mediaTransport: 'tcp', onEvent })
invokeRtcClient(id, 'join', JSON.stringify({ roomId, accessTicket, passcode }), onResult)

JavaScript 门面使用 await uniClient.join({ roomId, accessTicket, mediaTransport: 'tcp' })。uni-app/uni-app x 原生端需要包含本次 SDK 的自定义基座;仅替换页面不能更新基座中的 AAR/XCFramework。

微信小程序的 live-pusher/live-player 使用 RTMP/HTTP-FLV,不走浏览器 WebRTC。该端只接受 auto,显式 UDP/TCP 选择会返回不支持错误,不能据此声称小程序支持 TURN/TCP。

部署和凭据

  1. 业务后端签发一次性 RTC 入会票据,客户端入会后由 SDK 读取当前房间的 connection-settings。不要把管理 API Token 或媒体管理密钥写入客户端。
  2. 自动模式同时允许节点提供的 UDP/TCP TURN;指定模式会筛选服务端返回的 URL,并保留它对应的用户名和凭据。不要把 UDP 端口直接改成 TCP 后猜测服务能力。
  3. UDP TURN 使用节点的 ICE UDP 监听;TCP TURN 使用 ICE TCP 监听。以实际配置为准,例如 turn:media.example.com:3478?transport=udp 和 turn:media.example.com:3479?transport=tcp。对外映射、主机防火墙及中继端口范围须配套允许。
  4. 直接 ICE-TCP 的 RTC TCP 监听与 TURN TCP 监听不同,不能把 RTC TCP 媒体端口填进 TURN URL。auto 可由协商选用直接 ICE-TCP;tcp 选项明确强制 TURN/TCP。
  5. turn:...?transport=tcp 不代表 TLS。turns: 需要另有已配置的 TLS TURN 服务、可信证书和相应凭据;SDK 不会替节点开启 TLS,也不会自动部署外置 TURN。

没有匹配地址时,Web/H5 抛出 RTC_TRANSPORT_UNAVAILABLE;原生端通过现有失败回调返回具体原因,UniApp 通过调用结果或错误事件反馈。不会静默换协议。存在地址但服务未修复、映射不通或认证失败时,ICE 仍会失败,不能把配置成功当成媒体成功。

确认实际走的协议

WebRTC 中 relay 候选的 protocol 可能为 udp,它描述中继候选这一段。判断客户端是否使用 TCP TURN,要看选中候选对所关联的本地候选 relayProtocol:

const stats = await peer.getStats() // peer 为业务持有的 RTCPeerConnection
for (const pair of stats.values()) {
  if (pair.type !== 'candidate-pair' || pair.state !== 'succeeded' || !pair.nominated) continue
  const local = stats.get(pair.localCandidateId)
  console.log(local?.candidateType, local?.protocol, local?.relayProtocol)
}
// TCP 中继应为 relay / udp / tcp;不要记录凭据或完整 SDP。

第三方无需读取 SDK 私有字段;可使用浏览器 WebRTC 诊断页或自己持有的原生 PeerConnection 统计,并结合 SDK 媒体诊断确认音视频字节、视频解码和音频播放持续增长。单独出现 701、TCP 建连成功、Binding 成功或收到首次 401 都不能替代媒体验收。

Web/H5、原生及 UniApp Demo 都在入会区域提供“自动 / UDP 中继 / TCP 中继”。先分别用 UDP、TCP 完成两人音视频,再验证屏幕共享、切换网络和离会资源释放;不同浏览器、手机真机、企业代理和公网环境须单独验收。参见验收与排障。

微信原生小程序的完整接入、能力边界与函数参考见小程序指南和小程序 SDK API。

Clone this wiki locally