XRTC开发文档
SDK
SDK引入
XRTC JS SDK支持es5和es6语法和开发方式,具体可参考WebRTC代码示例 。
es5方式可以直接在HTML文件中引入JS,如:
<script type="text/javascript" src="//xswitch.cn/static/js/verto-min.js"></script>
es6可以直接在package.json
中添加@xswitch/rtc
,或通过npm install @xswitch/rtc
、yarn add @xswitch/rtc
等安装SDK。
SDK使用
SDK使用Verto库连接Websocket。Verto是XSwitch中连接Websocket协议的JS库,支持连接、登录验证、API、以及WebRTC呼叫等。在呼叫中心应用中暂不考虑WebRTC部分。
在es5中,可以初始化一个实例变量,如:
var verto = new Verto();
在es6中,可以使用以下方法引入:
import verto, {Verto, VertoCallcenter} from '@xswitch/rtc'
verto
是一个单例,不需要初始化。
连接
可以使用以下代码连接:
const loginParams = {
xui_sessid: '你的用户 token 或分机 token'
};
const params = {
login: username + "@" + domain,
passwd: 'password',
socketUrl: socketUrl,
loginParams: loginParams,
useVdieo : true,
tag: "webcam",
// localTag:'webcamlocal',
ringFile: "./sounds/bell_ring2.wav",
audioParams: {
googAutoGainControl: false,
googNoiseSuppression: false,
googHighpassFilter: false
},
deviceParams: {
useCamera: 'any',
useMic: 'any',
useSpeak: 'any',
onResCheck: null
},
videoParams: {
"minWidth": "1280",
"minHeight": "720",
"minFrameRate": 15
},
// iceServers: true
}
verto.connect(params, callbacks);
verto.connect
之后verto
会使用提供的参数,连接并登录到服务器。登录成功之后触发onWSLogin
回调函数。
在实际使用时,除了前面几个跟登录相关的参数外,其它的如设备和音视频相关的参数都是可选的。设备和音视频相关的参数可以在后面的newCall
以及answer
时再补充。
注意:在一般使用时,在newCall
或answer
时补充音视频参数都是没有问题的。唯一例外的一个场景是刷新自动恢复。在通话中刷新页面时,Verto连接后,会收到一个clientReady
消息,Verto可以自动恢复通话,这时候就需要在connect
阶段就传入音视频参数,否则会由于音视频设备等问题导致没有声音或视频。
params参数
login
:登录信息,字符串,格式是user@domain
。其中,user
是分机号,domain
必须是正确的域,否则可能不能通过认证或订阅不到消息。一般来说可以在XSwitch Web界面首页上查到这个“域”。passwd
:密码,字符串。如果使用Token登录,passwd
的值必须固定设为"password"
字符串,否则填真正的密码。socketUrl
:Websocket的地址,具体由管理员配置,一般是wss://host:port/ws
。loginParams
:对象。xui_sessid
:字符串,用户或分机Token。如果使用密码登录,则不要提供该字段。
useVideo
:true|false
,是否启用视频。tag
:远端音视频标签,需要在HTML中已经存在,如<video id='webcam' autoplay></video>
localTag
:本地音视频标签,可选。ringFile
:响铃文件,如果做被叫时将会播放。audioParams
:音频参数。videoParams
:视频参数。deviceParams
:设备参数。iceServers
:Stun及TURN服务器设置。
音频参数(audioParams)
googAutoGainControl
:true|false
,是否启用自动增益控制。googNoiseSuppression
:true|false
,是否启用噪声抑制。googHighpassFilter
:true|false
,是否启用高通滤波。
视频参数(videoParams)
minWidth
:最小宽度,如1280
minHeight
:最小高度,如720
minFrameRate
:最小帧率,如
设备参数(deviceParams)
所有设备默认为'none'
,即不启用。设为'any'
可以自动选择。
useCamera
:使用哪个摄像头设备,字符串,摄像头设备的UUID。useMic
:麦克风。useSpeak
:扬声器。onResCheck
:资源检查回调函数,默认值为null
。
关于设备参数的详细信息可以参见WebRTC示例中关于设备的相关说明和代码。
callbacks回调对象
onMessage
:function(verto, dialog, msg, data)
,收到消息时回调。verto
:verto
实例dialog
:只在WebRTC中使用msg
:收到的消息对象,根据不同的消息内容不同data
:收到的数据,内容因具体的消息而异
onWSLogin
:function(verto, success)
,登录时回调。verto
:verto
实例success
:true|false
,是否成功。
onWSClose
:function (v, success)
,Websocket断开时回调。参数同上。onEvent
:function(v, e)
,事件回调。onDialogState
:呼叫过程中的会话状态回调。
具体的消息内容(msg
、data
等)可以在使用时打印出来看看。
会话状态定义
Verto.enum.state.ringing
:振铃Verto.enum.state.trying
:服务器已收到消息,正在呼叫Verto.enum.state.early
:回铃音,前媒体,Early MediaVerto.enum.state.active
:已应答Verto.enum.state.ringing
:已挂机Verto.enum.state.ringing
:资源已释放
完整参数参考示例
连接:
const vertoConnectOptions = {
login: `${username}@${domain}`, // 用户名 + @ + 域 拼接
passwd: password, // 用户密码
socketUrl: socketUrl, // websocket 连接地址
loginParams: {
xui_sessid: "x-x-x-x", //使用xui session 登录
xcc_token: "a-b-c-d", // 使用XCC token 登录
},
localTag: 'webcam-local', // 本地视频标签
useVideo: true, // 是否使用视频
tag: 'webcam', // 用于显示视频通话的 video 标签
ringer_tag: "ringer", // 用于播放铃声的 audio 标签
ringFile: "sounds/bell_ring2.wav", // 铃声文件
audioParams: { // 用于音频的 MediaConstraints
// Google Chrome 浏览器的音频配置
googAutoGainControl: false, // 自动增益
googNoiseSuppression: false, //噪音抑制
googHighpassFilter: false, // 高通滤波
googEchoCancellation: false, // 回音消除
// w3c 的音频配置
autoGainControl: false, // 自动增益
noiseSuppression: false, //噪音抑制
highpassFilter: false, // 高通滤波
echoCancellation: false, // 回音消除
//更多Constrains 参考 https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackSettings
},
videoParams: {
minWidth: 1280, // 最低分辨率宽度
maxWidth: 1280, // 最高分辨率宽度
minHeight: 720, // 最低分辨率高度
maxHeight: 720, // 最高分辨率高度
minFramerate: 15, //最低帧数
}
deviceParams: {
useCamera: 'any', // 使用的摄像头
useMic: 'any', // 使用的麦克风
useSpeak: 'any', // 使用的扬声器
},
iceServers: false, // 是否使用 STUN/TURN 服务器, true 时使用默认服务器, false 不使用, Array 时是自定义服务器 Array Item 是 https://developer.mozilla.org/en-US/docs/Web/API/RTCIceServer
};
const callbacks = {
// Verto Message Recieved 收到Verto消息的回调
/**
* @param {Verto} verto
* @param {VertoDialog} dialog
* @param {VertoEnum} msg
* @param {any} data
*/
onMessage: function(verto, dialog, msg, data) {
console.log('onMessage', msg, data);
},
/**
* 被叫接听之前回调,可以在这个回调中修改verto的参数
* 比如你想在呼叫之前修改显示视频流的标签,可以在这个回调中修改
* @param {VertoDialog} dialog
*/
beforeAnswer: async function(dialog) {
// 修改显示视频流的标签
dialog.changeMediaTag("#webcam");
},
/**
* Verto 呼叫
* @param {VertoDialog} dialog
*/
beforeCall: asnyc function(dialog) {
},
/**
* 通话状态变化,目前verto是单例,同时只能处理一路电话,所以使用的全局回调
* @param {VertoDialog} dialog
*/
onDialogState: function(dialog) {
//可以根据 dialog.state 来判断通话状态
},
/**
* 当 verto 成功登录之后触发的回调函数
* @param {Verto} verto
* @param {boolean} success
*/
onWSLogin: function(verto, success) {
},
}
verto.connect( vertoConnectOptions, callbacks)
订阅
连接成功后,要订阅感兴趣的消息(事件),函数原型如下:
verto.subscribe(eventChannel, { handler: onEvent });
eventChannel
:事件类型。eventChannel是以“.
”分割的主题名。如在呼叫中心应用中:vcc
:订阅所有vcc
开头的消息vcc.default
:订阅default
这个组的vcc
消息,如班长要订阅所有人的状态vcc.default.1007
:订阅1007
这个坐席的状态
handler
:回调函数,原型是:function(verto, event)
。verto
:verto
实例event
:事件
略。
呼叫
呼叫流程如下:
主叫
- 使用
verto.newCall
进行呼叫 - 在
callbacks -> onDialogState
中处理当前通话状态变更 主叫处理trying
主叫正在呼叫- optional 当服务器有earlymedia 的时候
early
active
当前呼叫已经接通hangup
呼叫已经挂断destroy
清理呼叫相关资源
被叫
- 在
callbacks -> onDialogState
中处理当前通话状态变更ringing
被叫振铃, 当振铃之后需要保存 onDialogState 的 dialog 对象,dialog 对象包含了呼叫相关信息,如主被叫号码等。ringing
状态代表有电话呼入,可以在这个状态下播放提示音,或者弹出提示框,让用户选择是否接听。- 接听。 调用保存的会话对象接听函数接听通话
//dialog.params.wantVideo 代表主叫是否是视频通话 const params = { useCamera: dialog.params.wantVideo ? "any" : "none", useVideo: true, //也可是false,不过就不会发送视频了 useMic: "any", //使用的麦克风id 不使用麦克风 设置为 'none' 通过 Verto.audioDevices 获取 } dialog.answer(params)
active
当前呼叫已经接通hangup
呼叫已经挂断destroy
清理呼叫相关资源
参数示例
const params = {
destination_number: "1000", //必填 被叫号码
caller_id_name: "1001", //必填 主叫名称
caller_id_number: "1001", //必填 主叫号码
useVideo: true, // 是否使用视频
useStereo: false, // 可选 是否使用立体声
useCamera: 'any', // 可选 使用的摄像头id 不使用摄像头 设置为 'none' 通过 Verto.videoDevices 获取
useCameraLabel: 'any', // 可选 使用的摄像头的标 Verto.videoDevices 获取
}
// 呼叫之后获取代表当前通话的 dialog 对象
let cur_dialog = verto.newCall(params);
const callbacks = {
//... other callbacks
onDialogState : (dialog) => {
switch(d.state) {
case Verto.enum.state.ringing:
// 被叫振铃
break;
case Verto.enum.state.trying:
// 主叫正在呼叫
break;
case Verto.enum.state.early:
// 收到early media
break;
case Verto.enum.state.active:
// 通话已经接通
break;
case Verto.enum.state.hangup:
// 通话挂断
break;
case Verto.enum.state.destroy:
// 通话销毁
case Verto.enum.state.held:
// 通话保持
break;
default:
break;
}
}
}
多连接
Verto是一个类,verto
是一个Verto的实例。为方便使用,ES6中有一个verto
单例,因而可以直接使用。
如果需要创建多个Websocket连接,比如同时连接多个Websocket服务器,或者在同一个Websocket服务器上创建多个连接,可以直接初始化多个实例。
var verto1 = new Verto();
var verto2 = new Verto();
...
verto1.connect(...);
verto2.connect(...);
注意:由于Verto内部使用localStorage
缓存了sessid
,所以在使用多个连接时,注意sessid
不能冲突。下面是一个简单方法:
verto1.connect(...);
verto2.connect({
sessid: verto1.sessid + '-2',
...
});
另外,在实际使用时,注意两个实例使用不同的回调函数,以避免冲突。当然,如果两个连接使用同一个回调函数,在函数内部要注意区分。
详细的Demo参见:webrtc/2xrtc。
一个Verto实现多路通话
同一个Verto实例也支持多路通话,实现方法就是创建多个不同的VertoDialog。
const call_1 = verto.newCall({
tag: "webcam-1",
});
const call_2 = verto.newCall({
tag: "webcam-2",
});
注意在实际使用时不同的VertoDialog要使用不同的tag
以及不同的回调函数以免冲突。如果两个VertoDialog使用同一个回调函数,注意在函数内部对两路不同电话进行区分(可以根据Call-ID
区分)。
详细的Demo参见:webrtc/3xrtc。
通话中刷新页面
在通话中刷新页面时,Verto连接后,会收到一个clientReady
消息,Verto可以自动恢复通话。
注意:在一般使用时,可以不在connect
时提供音视频设备参数,而在newCall
或answer
时再补充。但在刷新自动恢复场景中,需要在connect
阶段就传入音视频参数,否则会由于音视频设备等问题导致没有声音或视频。