SDK集成指引 / Zego娃娃机H5 API文档

---

手动安装

目前 JSSDK 仅支持通过拷贝库文件的方式，集成步骤如下。

1 准备环境

请确保开发环境满足以下技术要求：

• IE ✔ 10+ Edge ✔ Firefox ✔ 21+ Chrome ✔ 45+ Safari 9+ Opera ✔ 15+
• 支持WebGL

2 下载 SDK

请从 jZego-SDK 下载 SDK。
最新版 1.0.15
更新于 2018-02-7

异步与同步SDK加载条件判断(关于平台判断,客户可以根据自己的实际情况自己设置, Demo仅供参考)

// 1、script加载模式
<script id="jZego"></script>
<script>
var jZego = document.getElementById('jZego');

console.log('navigator = ', navigator);
var ua = navigator.userAgent.toLowerCase();
if (/iphone|ipad|ipod/i.test(ua)) {                             // 在ios中
    if (ua.match(/MicroMessenger/i) == "micromessenger") {      // 微信中
        if (window.__wxjs_is_wkwebview === true) {              // wkwebview
            setSdk(true);
            console.log('ios 微信 wk');
        } else {                                                // UIWebView
            setSdk(false);
            console.log('ios 微信 ui');
        }
    } else if (/QQ|UIWebView/i.test(ua)) {                      // 在QQ中
        setSdk(false);
        console.log('ios QQ ui');
    } else {
        setSdk(true);
        console.log('ios 其他');
    }
} else if (/Android/i.test(ua)) {                                // 在android中
    var index = ua.indexOf("android");
    var androidVersion = parseFloat(navigator.userAgent.slice(index + 8));
    console.log(androidVersion);
    if (androidVersion < 4.4 ){                                  // 安卓版本小于4.4
        setSdk(false);
        console.log('android 版本小于4.4');
    } else {                                                     // 安卓版本大于4.4
        setSdk(true);
        console.log('android 版本大于4.4');
    }
} else {                                                        // 电脑或者其他
    setSdk(true);
}
// 设置sdk版本
function setSdk(type){
    if (type) {     // 同步版本  适用于性能好的机器
        window.quality = true;
        jZego.setAttribute('src', '/static/js/jZego/jZego-1.0.15.min.js');
    } else {        // 异步版本  适用于性能不好的机器  视频将会码率降级
        window.quality = false;
        jZego.setAttribute('src', '/static/js/jZego/jZego-1.0.15.async.min.js');
    }
}
</script>

// 2、require加载模式
var ZegoClient;
console.log('navigator = ', navigator);
var ua = navigator.userAgent.toLowerCase();
if (/iphone|ipad|ipod/i.test(ua)) {                              // 在ios中
    if (ua.match(/MicroMessenger/i) == "micromessenger") {      // 微信中
        if (window.__wxjs_is_wkwebview === true) {              // wkwebview
            setSdk(true);
            console.log('ios 微信 wk');
        } else {                                                // UIWebView
            setSdk(false);
            console.log('ios 微信 ui');
        }
    } else if (/QQ|UIWebView/i.test(ua)) {                      // 在QQ中
        console.log('ios QQ ui');
        setSdk(false);
    } else {
        setSdk(true);
        console.log('ios 其他');
    }
} else if (/Android/i.test(ua)) {                                // 在android中
    var index = ua.indexOf("android");
    var androidVersion = parseFloat(navigator.userAgent.slice(index + 8));
    console.log(androidVersion);
    if (androidVersion < 4.4 ){
        setSdk(false);
        console.log('android 版本小于4.4');
    } else {
        setSdk(true);
        console.log('android 版本大于4.4');
    }
} else {                                                        // 电脑或者其他平台
    setSdk(true);
}
function setSdk(type){
    if (type) {     // 同步版本  适用于性能好的机器
        window.quality = true;
        ZegoClient = require('@static/js/jZego/jZego-1.0.15.min.js');
    } else {        // 异步版本  适用于性能不好的机器  视频将会码率降级
        window.quality = false;
        ZegoClient = require('@static/js/jZego/jZego-1.0.15.async.min.js');
    }
}

使用异步SDK

1、针对低性能手机/webview需要使用async异步sdk版本，配置辅助文件jsmpeg.stub.min.js，作为worker运行在浏览器后台对视频进行解码操作， 性能好的手机/webview依旧使用同步sdk版本

2、同步与异步版本的sdk接口没有变化，只有在startPlayingStream这个接口增加了第四个参数，参数值为字符串的1,
例子： zg.startPlayingStream(streamID, view, viewMode, '1'); 表示调用降级后的视频流，视频流比原先降了4分之一质量；

3、异步sdk的辅助文件jsmpeg.stub.min.js的引入方式有三种，开发者可自己决定：
（1）jsmpeg.stub.min.js和异步sdk文件放置于同一个目录下，异步sdk内部会自动去同级目录下加载jsmpeg.stub.min.js
（2）调用zg.config接口，配置workerUrl参数，该参数表示jsmpeg.stub.min.js的引入路径
例子 zg.config({ workerUrl: 'http://www.zego.im/static/js/jZego/jsmpeg-stub.min.js' });
浏览器不允许跨域请求资源，此处url需要是同域名下的地址
（3）调用zg.config接口，配置workerPlayerJSBlob参数，该参数表示jsmpeg.stub.min.js内容Blob化后的数据格式（可解决跨域问题）

例子：
var xmlhttp2,workerPlayerJSBlob;
xmlhttp2 = new XMLHttpRequest();
xmlhttp2.onreadystatechange = function() {
    if (xmlhttp2.readyState == 4) {
        if (xmlhttp2.status == 200) {
            // Blob化所需要的只是jsmpeg-stub.min.js的文本内容，所以除了ajax方式获取，开发者也可以预先导入该文件，不用通过ajax请求获得
            workerPlayerJSBlob = new Blob([xmlhttp2.responseText], {type : 'text/javascript'});
        }
    }
};
xmlhttp2.open("GET", '/static/js/jZego/jsmpeg-stub.min.js', false); // 此处请求地址为客户端自己的资源地址
xmlhttp2.send();
zg.config({ workerPlayerJSBlob: workerPlayerJSBlob });
if (window.quality) {   // window.quality变量为上面选择SDK版本时候定义的
    zg.startPlayingStream(useStreamList[m].stream_id, useStreamList[m].videoView);
} else {                // 降级处理
    zg.startPlayingStream(useStreamList[m].stream_id, useStreamList[m].videoView, '', '1');
}

（4）workerUrl与workerPlayerJSBlob二者选其一，如果都配置以workerPlayerJSBlob为优先

SDK更新日志

• 1.0.15
  （1）提升性能
  （2）修复异步SDK在单页应用中canvas销毁失败，导致不能重新播放问题

• 1.0.14
  （1）修复viewMode传参数问题，canvas渲染模式从1.0.10版本后（包含1.0.10）默认为1:裁剪模式
  （2）修复反复stopPlayingStream/startPlayingStream操作导致内存泄漏问题

• 1.0.13
  （1）config接口增加workerPlayerJSBlob参数，配置jsmpeg-stub.min.js文件内容的Blob格式数据（可解决跨域问题）
  workerPlayerJSBlob构造方式:
  

  var xmlhttp2,workerPlayerJSBlob;
  xmlhttp2 = new XMLHttpRequest();
  xmlhttp2.onreadystatechange = function() {
    if (xmlhttp2.readyState == 4) {
        if (xmlhttp2.status == 200) {
            // Blob化所需要的只是jsmpeg-stub.min.js的文本内容，所以除了ajax方式获取，开发者也可以预先导入该文件，不用通过ajax请求获得
            workerPlayerJSBlob = new Blob([xmlhttp2.responseText], {type : 'text/javascript'});
        }
    }
  };
  xmlhttp2.open("GET", '/static/js/jZego/jsmpeg-stub.min.js', false); // 此处请求地址为客户端自己的资源地址
  xmlhttp2.send();
  配置参数:
  zg.config({
    workerPlayerJSBlob: workerPlayerJSBlob
  });

• 1.0.12
  （1）config接口增加workerUrl参数，自定义jsmpeg-stub.min.js的资源地址

  配置参数:
  zg.config({
    workerUrl: 'http://test.zego.im/static/js/jZego/jsmpeg-stub.min.js'
  });

• 1.0.11
  （1）修复异步SDK文件stopPlayingStream没有销毁cavans id的bug

• 1.0.10
  （1）增加setUserStateUpdate接口
  （2）增加onGetTotalUserList回调

• 1.0.9
  （1）增加onUserStateUpdate回调
  (2）增加enableDecode接口

• 1.0.8
  （1）增加onPlayQualityUpdate回调

• 1.0.7
  （1）修复客户端收到新增的流，启动starPlayingStream不能播放问题

• 1.0.6
  （1）增加对zg.sendRoomMsg接口发消息的频率控制，最快只能500毫秒发一次
  （2）优化jsmpeg的webgl.js

• 1.0.5
  （1）修复zg.sendRoomMsg接口中成功回调函数返回的msg_category、msg_type、msg_content不正确问题

• 1.0.4
  （1）修复onRecvRoomMsg不是一个function的bug

• 1.0.3
  （1）发送房间IM消息回调增加msgId字段

• 1.0.2
  （1）处理了单页应用情况下，jsmpeg离开和进入房间后，流不重新播放问题
  （2）fix了没填写log地址，websocket报错问题
  （3）去掉了poster参数
  （4）添加了发送IM消息接口

• 1.0.1
  （1）startPlayingStream接口增加了判断，如果本地流列表中存在与传入的stream_id相对应的流，则不做播放处理
  （2）startPlayingStream接口添加了poster，viewMode参数，poster没有使用到，在下个版本去掉，viewMode决定视频的渲染模式，默认值为0，表示填充；1表示裁剪，不变形，满足其中一边长度，另一边会被裁剪。2表示变形，但是视频内容全部显示出现

• 1.0.0 初版SDK

3 集成 SDK

3.1

1. 使用script引入

   <script src="jZego.1.0.15.js"></script>

4 使用 SDK / Zego娃娃机H5 API文档

4.1 请求接口

4.1.1 ZegoClient.config(option)

初始化配置，配置参数如下：

4.1.2 ZegoClient.login(roomid, role, token, success, error)

登录房间，登录参数如下：

streamList数组中stream的对象结构

4.1.3 ZegoClient.logout

登出房间，无参数;
调用之后会向娃娃机发送登出信令，之后重置当前房间中用户与娃娃机进行交互所需的关键数据，并置空websocket对象

4.1.4 ZegoClient.sendCustomCommand(dstMembers, customContent, success, error)

发送自定义命令, 参数如下:

回调参数说明：

• seq：消息发送序号
• customContent： 发送内容
• err: 错误对象

调用限制：
1.不能发送房间广播的自定义消息
2.不能发送多个接受者的自定义消息

4.1.5 ZegoClient.startPlayingStream(streamid, viewNativeDom, viewMode, streamQuality)

开始播放流, 参数如下:

• viewMode参数 支持1.0.3+版本
• streamQuality 支持1.0.12+版本
• 视频流降级需要用户主动向技术支持人员提出需求，然后ZEGO后台配置，否则传第四个参数无效

4.1.6 ZegoClient.stopPlayingStream(streamid)

停止播放流, 参数如下:

4.1.7 ZegoClient.setPlayVolume(streamid, volume)

设置流音量大小, 参数如下:

4.1.8 ZegoClient.sendRoomMsg(msg_category, msg_type, msg_content, success, error)

发送房间消息, 参数如下:

4.1.9 ZegoClient.release

释放ZegoClient资源, 退出房间，并释放流资源， 参数无
调用之后会向娃娃机发送登出信令，之后重置当前房间中用户与娃娃机进行交互所需的关键数据，并置空websocket对象和销毁播放器对象

4.1.10 ZegoClient.enableDecode(streamId, enable)

设置jsmpeg是否进行解码(默认开启)， 参数如下：

• enable参数设置为false后，对应streamId的视频画面静止，拉流质量(onPlayQualityUpdate)不再回调

4.1.11 ZegoClient.setUserStateUpdate(update)

设置是否关注房间成员变化(默认为false)， 参数如下：

• update参数设置为true后，SDK登录成功后会自动拉取当前房间所有成员列表通过onGetTotalUserList回调
  
• 之后进出房间的用户变化通过onUserStateUpdate回调
  
• 该设置为房间配置，只能是创建房间的人设置
  
• 在网络异常或其他情况下，SDK会再次拉取房间所有成员，再次回调onGetTotalUserList
  

4.2 回调接口

4.2.1 ZegoClient.onDisconnect(err)

房间连接断开通知, 参数如下:

4.2.2 ZegoClient.onKickOut(err)

被踢下线通知, 参数如下:

4.2.3 ZegoClient.onRecvCustomCommand(from_userid, from_idname, custom_content)

自定义命令消息通知, 参数如下:

4.2.4 ZegoClient.onStreamUpdated(type, streamList)

流更新通知, 参数如下:

流信息对象结构：

4.2.5 ZegoClient.onStreamExtraInfoUpdated(streamList)

流状态变更通知，（不包含增加，删除）, 参数如下:

流信息对象结构：

4.2.5 ZegoClient.onPlayStateUpdate(type, streamId)

流信息变更通知，（不包含增加，删除）, 参数如下:

4.2.6 ZegoClient.onRecvRoomMsg(chat_data, server_msg_id, ret_msg_id)

房间消息通知, 参数如下:

消息对象结构：

4.2.7 ZegoClient.onPlayQualityUpdate(streamId, streamQuality)

拉流质量回调，参数如下:

streamQuality对象结构：

4.2.8 ZegoClient.onUserStateUpdate(roomId, userList)

房间成员变化回调，设置setUserStateUpdate为true时回调。参数如下:

成员对象结构:

4.2.8 ZegoClient.onGetTotalUserList(roomId, userList)

房间所有成员回调，设置setUserStateUpdate为true时回调。参数如下:

成员对象结构:

4.3 错误码列表