【Web SDK】常见集成问题集锦

此贴总结了目前用户集成 Agora Web SDK 过程中遇到的各类常见问题,希望能够帮助开发者们更简单地去集成 Web 端 SDK。也欢迎各位开发者们在本帖中讨论和补充。

更多 Web SDK 相关链接:
Agora Web SDK API Reference
快速集成 Agora Web SDK 并在 app 里实现音视频互动直播
SDK/Demo 下载

Agora Web SDK 支持哪些浏览器?

https://docs.agora.io/cn/faq/browser_support

Agora Web SDK 如何与 Agora Native SDK 互通?

  • 在通信模式下,Agora Web SDK 和 Agora Native SDK 默认互通,无需额外设置。
  • 在直播模式下,PC 或移动端用户(使用 Agora Native SDK 的用户)必须调用 enableWebSdkInteroperability 打开互通功能,详见移动、桌面、Web 端互通

如何在移动端使用 Web SDK?

Agora Web SDK 新增 H5 实时直播组件,支持在移动端网页播放音视频流。该功能可以实现通过在社交 app 内(如微信群、微信公众号、钉钉)分享网页链接,让用户在 app 中打开链接就能直接观看实时视频,降低了分享门槛,方便扩大目标受众范围。详情请参考:
https://docs.agora.io/cn/Interactive%20Broadcast/web_in_app?platform=Web

调用 API 常见报错


  • User is not in the session 报错原因: websocket 未建立连接。基本都是调用 API 时序不正确导致的。例如连接释放了还在调用 API,或者连接尚未建立就调用部分 API。

  • cannot read property “appendChild” of null: 这个报错一般是 play 指定的 dom 不存在或者 id 没有找到,基本都是业务逻辑处理的问题,例如 play 之前没有及时生成相应的父容器。

  • Invalid elementID :play 时指定的容器不符合参数规则。

  • UID_CONFLICT :同一个 uid 多次加入同一个频道导致互踢。请保持频道内 uid 的唯一性。

  • Failed to execute ‘addStream’ on ‘RTCPeerConnection’: parameter 1 is not of type ‘MediaStream’ :本地 stream 没有 init 成功就 publish 导致的。

  • media access MEDIA_NOT_SUPPORT: video/audio streams not supported yet /enumerateDevices() not supported :没有使用正确的浏览器。或者没有使用 https / localhost 打开页面(由于浏览器的安全策略对除 127.0.0.1 以外的 HTTP 地址作了限制,Agora Web SDK 仅支持 HTTPS 协议或者 http://localhosthttp://127.0.0.1),请勿使用 HTTP 协议部署你的项目),导致没有权限调用底层的获取设备 API。

  • Cannot read property ‘stringUid’ of undefined : 一般都是由于没有 join 成功就 publish 导致的报错。

  • Uncaught TypeError: Failed to execute ‘createObjectURL’ on ‘URL’: No function was found that matched the signature provided / Uncaught DOMException: Failed to execute ‘addTransceiver’ on ‘RTCPeerConnection’: This operation is only supported in ‘unified-plan’. 在浏览器上开启了手机模拟调试导致。

  • INVALID_VENDOR_KEY:鉴权失败。appid 填写的不正确。以及,请检查是否有启用 APP 证书,若有启用,必须使用动态密钥鉴权方式,即 join 时需要传入正确的 Token 值。

  • video 标签的 status 是 paused 或 aborted
    paused 可能的原因:
    1)频繁操作 dom 导致浏览器暂停播放器;
    2)无法解码视频流;
    3)视频包需要等待音频包同步播放,而音频包播放不了,需要手动触发播放。关于自动播放策略的更多信息,请参考 Autoplay Policy Changes
    aborted 可能的原因:
    video 标签在 play 前被删除了。

  • Failed to set remote answer sdp: Called in wrong state: kStable: 这个错误是因为调用 switchDevice 导致的,该报错没有任何影响,在 2.9.0 及之后的版本不会再出现此报错。

  • cannot read property ‘stringuid’ of undefined:没有 join 成功就调用 publish 导致

针对 chrome 70+ 上出现的因 autoplay 策略改动导致本地订阅流无法自动播放音频和视频的问题,有以下几种方式可以规避:

1、在 play 的回调里面做处理,当 err.status!==aborted 时,创建一个按钮让用户手势点击,然后触发 resume,此时就可以播放音视频了;

// 引导用户点击按钮恢复视频播放
stream.play("agora_remote"+ stream.getId(), function(err){
        if (err && err.status !== "aborted"){
               // 播放失败,一般为浏览器策略阻止。引导用户用手势触发恢复播放            
            var r = confirm("显示远端视频");
            if (r == true) { 
                        stream.resume().then(
                        function (result) {
                              console.log('恢复成功:' + result);
                        }).catch(
                        function (reason) {
                              console.log('恢复失败:' + reason);
                       });
           } else { 
                console.log("未知原因导致无法播放,请联系技术支持!");
           }
        }
});

2、本地创建流,在本地流 init 成功后,再去 play 远端流,此时可以规避 autoplay 策略导致的问题;

// 观众端直接创建流来恢复视频播放
stream.play("agora_remote"+ stream.getId(), function(err){
        if (err && err.status !== "aborted"){
               // 播放失败,一般为浏览器策略阻止。引导用户用手势触发恢复播放            
             localStream = AgoraRTC.createStream({ audio: true, video:false,screen:false});
             localStream.init(function() {
                        stream.resume().then(
                        function (result) {
                              console.log('恢复成功:' + result);
                        }).catch(
                        function (reason) {
                              console.log('恢复失败:' + reason);
                       });
           }, function (err) {
                    console.log("getUserMedia failed", err.msg);
                     });
        }
});

此外,在 360 浏览器上可能会遇到一个特殊的 autoplay 现象:能看见远端流听不到远端流。此时也需要按照上述方式做相应的处理。

如何切换视频流和屏幕共享流?

有两种方案:

1、调用 replacetrack 方法替换本地音视频流中的视频轨道为屏幕共享流。

优点:切换快、实时;
缺点:兼容性较差,该接口只支持 Chrome 65+,Safari 以及最新版 Firefox 浏览器。该方法在部分移动设备上可能不生效。

2、unpublish 和 close 本地音视频流,再重新调用 createStream 创建屏幕共享流,然后 init 和 publish 流。

优点:兼容性好;
缺点:无法动态切换视频流,需要先 unpublish 和 close,与方案 1 相比,切换稍慢一些。

设备报错问题


NotAllowedError

用户拒绝了获取音视频设备的请求


OverConstrainedError

指定的要求无法被设备满足,此异常是一个类型为0verconst rainedError的对象,拥有一个constraint属性,这个属性包含了当前无法被满足的constraint对,如果你开启了多个Tab页同时推流,请确定分辨率采集是一致的。


NotFoundError

找不到满足请求参数的媒体类型。

一类已知问题:用户采用第三方的虚拟摄像头软件,会导致 chrome 识别不了这个摄像头,但是 360 浏览器能识别,原因: 该虚拟摄像头软件是 32 位的软件 ,只有 32 位的应用才能使用,所以需要安装 32 位的 chrome 才可以识别。


NotReadableError

尽管用户已经授权使用相应的设备,操作系统上某个硬件、浏览器或者网页层面发生的错误导致设备无法被访问。

一类已知问题:部分 win10 的笔记本需要用 Chrome 兼容 win7 的模式打开才能使用摄像头,不然会报错:could not start video source


AbortError

尽管用户和操作系统都授予了访问设备硬件的权利,并且也没有出现 NotReadableError 这类硬件引起的问题,但仍然有一些其它问题的出现,导致了设备无法被使用。


TypeError

constraints 对象未设置[空],或者都被设置为 false。


SecurityError

没有使用 HTTPS 或 localhost 协议。