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

下载pdf
更新时间:2019-09-27 10:09

手动安装

目前 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)

初始化配置,配置参数如下:

参数 含义 类型
option.appid appid 数值
option.server 娃娃机服务器地址 字符串
option.idName 用户id 字符串
option.nickName 用户昵称 字符串
option.logLevel 本地log级别 0:debug 1:info 2:warn 3:error 98:report 100:disable 数值
option.logUrl 远程log服务器地址 websocket地址 字符串

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

登录房间,登录参数如下:

参数 含义 类型
roomid 房间id 字符串
role 角色类型,1:主播 2:观众 数值
token 登录验证token 字符串
success 成功回调函数 function(streamList)
error 失败回调函数 function(err)

streamList数组中stream的对象结构

参数 含义 类型
stream_id 流Id 字符串
anchor_id_name 流对应的用户Id 字符串
anchor_nick_name 流对应的用户昵称 字符串
extra_info 流附加信息 字符串

4.1.3 ZegoClient.logout

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

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

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

参数 含义 类型
dstMembers 接收消息者列表 字符串数组(数组成员有且仅有一个)
customContent 自定义消息内容 字符串
success 成功回调函数 function(seq, customContent)
error 失败回调函数 function(err, seq, customContent)

回调参数说明:

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

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

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

开始播放流, 参数如下:

参数 含义 类型
streamid 流id 字符串
viewNativeDom 控件view Dom对象
viewMode 视频渲染模式 数值;默认0:填充,1裁剪,2变形
streamQuality 流质量(降级4分之一) 字符串;默认为空,拉取高质量流;
取值字符串 '1',拉取降级视频流(降级4分之一)
  • viewMode参数 支持1.0.3+版本
  • streamQuality 支持1.0.12+版本
  • 视频流降级需要用户主动向技术支持人员提出需求,然后ZEGO后台配置,否则传第四个参数无效

4.1.6 ZegoClient.stopPlayingStream(streamid)

停止播放流, 参数如下:

参数 含义 类型
streamid 流id 字符串

4.1.7 ZegoClient.setPlayVolume(streamid, volume)

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

参数 含义 类型
streamid 流id 字符串
volume 音量 数值0-100

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

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

参数 含义 类型
msg_category 消息业务类型 数值 1:系统消息 2:聊天消息
msg_type 消息格式类型 数值 1: 文本消息 2:图片url 3:文件url
msg_content 消息内容 字符串
success 成功回调函数 function(seq, msgId, msg_category, msg_type, msg_content)
error 失败回调函数 function(err, seq, msg_category, msg_type, msg_content)

4.1.9 ZegoClient.release

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

4.1.10 ZegoClient.enableDecode(streamId, enable)

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

参数 含义 类型
streamid 流id 字符串
enable 是否解码 布尔值
  • enable参数设置为false后,对应streamId的视频画面静止,拉流质量(onPlayQualityUpdate)不再回调

4.1.11 ZegoClient.setUserStateUpdate(update)

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

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

4.2 回调接口

4.2.1 ZegoClient.onDisconnect(err)

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

参数 含义 类型
err.code 错误码 字符串
err.msg 错误信息 字符串

4.2.2 ZegoClient.onKickOut(err)

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

参数 含义 类型
err.code 错误码 字符串
err.msg 错误信息 字符串

4.2.3 ZegoClient.onRecvCustomCommand(from_userid, from_idname, custom_content)

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

参数 含义 类型
from_userid 服务器用户唯一id 字符串
from_idname 用户id 字符串
custom_content 自定义命令消息 字符串

4.2.4 ZegoClient.onStreamUpdated(type, streamList)

流更新通知, 参数如下:

参数 含义 类型
type 变更类型 数值,0:添加, 1:删除
streamList 变更流列表 对象数组

流信息对象结构:

参数 含义 类型
stream_id 流Id 字符串
anchor_id_name 流对应的用户Id 字符串
anchor_nick_name 流对应的用户昵称 字符串
extra_info 流附加信息 字符串

4.2.5 ZegoClient.onStreamExtraInfoUpdated(streamList)

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

参数 含义 类型
streamList 变更流列表 对象数组

流信息对象结构:

参数 含义 类型
stream_id 流Id 字符串
anchor_id_name 流对应的用户Id 字符串
anchor_nick_name 流对应的用户昵称 字符串
extra_info 流附加信息 字符串

4.2.5 ZegoClient.onPlayStateUpdate(type, streamId)

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

参数 含义 类型
type 流状态类型 数值 start:0, stop:1, error:2
streamId 流id 字符串

4.2.6 ZegoClient.onRecvRoomMsg(chat_data, server_msg_id, ret_msg_id)

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

参数 含义 类型
chat_data 消息内容 数组
server_msg_id 服务器最新消息id 数值
ret_msg_id 当前推送消息id 数值

消息对象结构:

参数 含义 类型
id_name 用户Id 字符串
nick_name 用户昵称 字符串
role 用户角色 数值
msg_id 消息Id 数值
msg_category 消息类别 数值
msg_type 消息类型 数值
msg_content 消息内容 字符串
send_time 发送时间 数值

4.2.7 ZegoClient.onPlayQualityUpdate(streamId, streamQuality)

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

参数 含义 类型
streamId 流Id 字符串
streamQuality 流质量 对象

streamQuality对象结构:

参数 含义 类型
fps 帧率 数值
kbs 码率 数值

4.2.8 ZegoClient.onUserStateUpdate(roomId, userList)

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

参数 含义 类型
roomId 房间Id 字符串
userList 成员列表 对象数组

成员对象结构:

参数 含义 类型
action 行为 数值 1:进入房间 2:退出房间
idName 用户id 字符串
nickName 用户昵称 字符串
role 角色类型 数值 1:主播 2:观众
logintime 登录时间 字符串

4.2.8 ZegoClient.onGetTotalUserList(roomId, userList)

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

参数 含义 类型
roomId 房间Id 字符串
userList 成员列表 对象数组

成员对象结构:

参数 含义 类型
idName 用户id 字符串
nickName 用户昵称 字符串
role 角色类型 数值 1:主播 2:观众

4.3 错误码列表

错误码 含义
ZegoClient.Success 成功
ZegoClient.Error.Param 参数错误
ZegoClient.Error.Timeout 超时
ZegoClient.Error.Network 网络错误
ZegoClient.Error.Kickout 用户被踢
ZegoClient.Error.Server 服务返回错误
ZegoClient.Error.Unknown 未知错误