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 使用 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阶段就传入音视频参数，否则会由于音视频设备等问题导致没有声音或视频。

• 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 服务器设置。

• googAutoGainControl：true|false，是否启用自动增益控制。
• googNoiseSuppression：true|false，是否启用噪声抑制。
• googHighpassFilter：true|false，是否启用高通滤波。

• minWidth：最小宽度，如1280
• minHeight：最小高度，如720
• minFrameRate：最小帧率，如

所有设备默认为'none'，即不启用。设为'any'可以自动选择。

• useCamera：使用哪个摄像头设备，字符串，摄像头设备的 UUID。
• useMic：麦克风。
• useSpeak：扬声器。
• onResCheck：资源检查回调函数，默认值为null。

关于设备参数的详细信息可以参见WebRTC 示例中关于设备的相关说明和代码。

• 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 Media
• Verto.enum.state.active：已应答
• Verto.enum.state.hangup：已挂机
• Verto.enum.state.destroy：资源已释放

连接：

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：事件

略。

呼叫流程如下：

1. 使用 verto.newCall 进行呼叫
2. 在callbacks -> onDialogState 中处理当前通话状态变更 主叫处理
   1. trying 主叫正在呼叫
   2. optional 当服务器有 earlymedia 的时候 early
   3. active 当前呼叫已经接通
   4. hangup 呼叫已经挂断
   5. destroy 清理呼叫相关资源

1. 在callbacks -> onDialogState 中处理当前通话状态变更
   1. ringing 被叫振铃， 当振铃之后需要保存 onDialogState 的 dialog 对象，dialog 对象包含了呼叫相关信息，如主被叫号码等。
      1. ringing 状态代表有电话呼入，可以在这个状态下播放提示音，或者弹出提示框，让用户选择是否接听。
      2. 接听。 调用保存的会话对象接听函数接听通话

         //dialog.params.wantVideo 代表主叫是否是视频通话
         const params = {
         	useCamera: dialog.params.wantVideo ? "any" : "none",
         	useVideo: true, //也可是false，不过就不会发送视频了
         	useMic： "any", //使用的麦克风id 不使用麦克风 设置为 'none' 通过 Verto.audioDevices 获取
         }
         dialog.answer(params)
         

   2. active 当前呼叫已经接通
   3. hangup 呼叫已经挂断
   4. 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 实例也支持多路通话，实现方法就是创建多个不同的 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阶段就传入音视频参数，否则会由于音视频设备等问题导致没有声音或视频。