双人互动白板

通过阅读本章节,您将快速了解双人互动白板的相关功能,并且能通过本章节中介绍的流程和接口快速搭建一个双人互动白板会话。

双人互动白板也称点对点互动白板,参与互动白板的共有两方,按照发起会话与接收会话区分为主叫与被叫角色。

SDK提供点对点互动白板从发起会话建立会话会话互动结束会话整个过程的能力整个过程的能力,包括呼叫/接收、发送白板数据、结束白板等基础能力接口与异常流程控制与回调。

考虑到白板使用场景与音频使用场景强关联,双人互动白板中包含语音通道(可选)更方便快捷满足简单白板的场景,需要注意的是语音通道全局只能有一个,并且与互动白板和互动直播功能互斥。

双人白板接入流程

sequenceDiagram participant 主叫 participant 被叫 主叫-->被叫:Step1:建立互动白板 主叫->>被叫:主叫发起互动白板请求: whiteboard.call 被叫->>被叫:被叫收到互动白板请求回调: whiteboard.on('beCalling', obj => {}) 被叫->>主叫:被叫响应互动白板请求: whiteboard.response 主叫 ->>主叫:主叫收到被叫互动白板响应回调: whiteboard.on('callerAckSync', obj => {}) 主叫->>主叫: 主叫收到被叫响应通知-接受: whiteboard.on('callAccepted', obj => {}) 主叫->>主叫: 主叫收到被叫响应通知--拒绝: whiteboard.on('callRejected', obj => {}) 主叫->>主叫: 呼叫应答完成, 开启白板会话 被叫->>被叫: 呼叫应答完成, 开启白板会话 主叫-->被叫:Step2:互动白板过程 loop 互动白板 主叫->>被叫: [可选]发送互动白板控制指令: whiteboard.control 被叫->>被叫: [可选]互动白板控制指令回调: whiteboard.on('control', obj => {}) end 主叫-->被叫:Step3:结束互动白板 主叫->>被叫:结束互动白板: whiteboard.hangup 被叫->>主叫:对方结束互动白板回调: whiteboard.on('hangup', obj => {})

主叫发起互动白板请求

const pushConfig = {
  enable: true,
  needBadge: true,
  needPushNick: true,
  pushContent: '',
  custom: '测试自定义数据',
  pushPayload: '',
  sound: ''
}
const sessionConfig = {
    record: false
}
whiteboard.call({
    type: type,
    netcallType: WhiteBoard.CALL_TYPE_AUDIO,
    account: 'testAccount',
    pushConfig: pushConfig,
    sessionConfig: sessionConfig,
    webrtcEnable: true,
}).then(function(obj) {
  // 成功发起呼叫
  console.log('call success', obj)
}).catch(function(err) {
  // 被叫不在线
  if (err.code === 11001) {
    console.log('callee offline', err)
  }
})
// 设置超时计时器
let callTimer = setTimeout(function() {
  if (!whiteboard.callAccepted) {
    console.log('超时未接听, hangup')
    hangup()
  }
}, 1000 * 30)
参数名 类型 说明
type number 白板类型
netcallType number 音视频类型
webrtcEnable bool 音视频是否支持WebRTC方式接入,可选,默认为不开启
account string 对方账号
pushConfig object 推送配置,具体属性见这里
sessionConfig object 白板会话配置,具体属性见这里

SDK 没有呼叫超时时间,开发者可根据自己的业务场景通过定时器设置呼叫超时时间,在被叫超时未接听时调用 结束互动白板 接口挂断该呼叫。

被叫收到互动白板请求回调

// 是否被叫中
let beCalling = false
// 呼叫类型
let type = null
// 被叫信息
let beCalledInfo = null
// 是否正忙
let busy = false
// 开启监听
whiteboard.on('beCalling', function(obj) {
  console.log('on beCalling', obj)
  const channelId = obj.channelId
  // 被叫回应主叫自己已经收到了通话请求
  whiteboard.control({
    channelId,
    command: WebRTC.NETCALL_CONTROL_COMMAND_START_NOTIFY_RECEIVED
  })
  // 只有在没有通话并且没有被叫的时候才记录被叫信息, 否则通知对方忙并拒绝通话
  if (!whiteboard.calling && !beCalling) {
    type = obj.type
    beCalling = true
    beCalledInfo = obj
  } else {
    if (whiteboard.calling) {
      busy = whiteboard.notCurrentChannelId(obj)
    } else if (beCalling) {
      busy = beCalledInfo.channelId !== channelId
    }
    if (busy) {
      whiteboard.control({
        channelId,
        command: WebRTC.NETCALL_CONTROL_COMMAND_BUSY
      })
      // 拒绝通话
      whiteboard.response({
        accepted: false,
        beCalledInfo: obj
      })
    }
  }
})
obj属性 类型 说明
account string 主叫account
type number 主叫发起的通话类型(音频还是视频)
channelId string 该通呼叫通话的唯一id值,开发者可用于判断是否是同一通呼叫

被叫响应互动白板请求

// 接听
beCalling = false
const sessionConfig = {
    record: false
}
whiteboard.response({
  accepted: true,
  beCalledInfo: beCalledInfo,
  sessionConfig: sessionConfig
}).catch(function(err) {
  reject()
  console.log('接听失败', err)
})

// 拒绝
// 可以先通知对方自己忙, 拒绝的时候需要回传在 `beCalling` 事件里面接收到的对象
const beCalledInfo = beCalledInfo
whiteboard.control({
  channelId: beCalledInfo.channelId,
  command: WebRTC.NETCALL_CONTROL_COMMAND_BUSY
})
whiteboard.response({
  accepted: false,
  beCalledInfo
})
beCalledInfo = null
beCalling = false
上面用到的参数名 类型 说明
accepted bool 回应类型,接听、拒绝
beCalledInfo object 呼叫信息,必传,该值可以在 beCalling 回调事件中获取)
sessionConfig object 通话配置内容,具体信息请参考上面的主叫发起通话时的参数注解,具体属性见这里
channelId string 该通呼叫通话的唯一id值
command number 通话控制命令

主叫收到被叫互动白板响应回调

// 被叫拒绝的通知
whiteboard.on('callRejected', function(obj) {
  console.log('on callRejected', obj)
  // 取消呼叫倒计时
  clearCallTimer()
  // 挂断
  hangup()
  // 做清理工作
  resetWhenHangup()
})

// 被叫接受的通知
whiteboard.on('callAccepted', function(obj) {
  // 缓存呼叫类型,后面开启音视频连接需要用到
  type = obj.type
  console.log('on callAccepted', obj)
  // 取消呼叫倒计时
  clearCallTimer()
  // 可以开启音视频连接操作。。。
})

obj 为呼叫应答的回调通知对象

obj属性 类型 说明
account string 被叫账号
type number 音视频呼叫类型:音频、视频

呼入的通话已经被该帐号其他端处理回调

whiteboard.on('callerAckSync', function(obj) {
  console.log('其他端已经做了处理', obj)
})

obj 为其他端已处理的回调对象

obj属性 类型 说明
timetag string 时间戳
channelId string 当前通话的唯一id值
type number 通话类型:音频、视频
accepted bool 其他端做出的应答:接受、拒绝
fromClientType string 从什么类型的终端做出的应答:IOS、Android等

通话建立结果回调

// 被叫接受的通知
whiteboard.on('callAccepted', function(obj) {
  console.log('on callAccepted', obj)
  // 取消呼叫倒计时
  clearCallTimer()
  // 可以开启白板会话操作。。。
})

开启白板会话

whiteboard.startSession()
    .then(function(obj){
        console.log('session Started', obj)
        if(whiteboard.sessionMode === 'p2p'){
            console.log('45s倒计时等待对方加入房间,若倒计时结束对方未加入房间,自动断开连接')
        }
        console.log('session Started', obj)
    })
    .catch(function(err) {
        console.log('session start failed', err)
        whiteboard.stopSession()
    })

发送数据

obj参数属性 类型 说明
data string 待发送数据

接收数据

会话过程控制

发送互动白板控制指令

互动白板控制指令用于方便双方沟通信息,可以选择性使用。该指令通道使用云信 IM 消息通道,而不是互动白板数据通道。

常见指令如下

// 告诉发送方自己已经收到请求了(用于通知发送方开始播放提示音)
var param = {
  channelId: 1511182568418,
  command: WhiteBoard.CONTROL_COMMAND_START_NOTIFY_RECEIVED
}
whiteboard.control(param)
param参数属性 类型 说明
channelId number 当前会话的唯一id值
command number 会话控制指令具体值请参照这里

收到互动白板控制指令回调

whiteboard.on('control', function(obj) {
  // 如果不是当前通话的指令, 直接丢掉
  if (whiteboard.notCurrentChannelId(obj)) {
    return
  }
  console.log('on control', obj)
})
obj参数属性 类型 说明
channelId number 当前会话的唯一id值
command number 会话控制指令具体值请参照这里

结束白板流程

sequenceDiagram 主叫->>被叫: 结束通话: whiteboard.hangup 被叫->>被叫: 收到对方结束通话回调: whiteboard.on('hangup', obj => {}) 被叫->>被叫: 通话断开,请手动做清理工作 被叫->>被叫: 话单通知 主叫->>主叫: 通话断开,请手动做清理工作 主叫->>主叫: 话单通知

结束互动白板

whiteboard.hangup()

对方结束互动白板回调

whiteboard.on('hangup', function(obj) {
  console.log('on hangup', obj)
  // 判断需要挂断的通话是否是当前正在进行中的通话
  if (!beCalledInfo || beCalledInfo.channelId === obj.channelId) {
    // 清理工作
    resetWhenHangup()
  }
})

obj 收到的挂断通知对象

obj属性 类型 说明
timetag string 时间戳
channelId string 当前通话的唯一id值
account string 对方账号
type number 挂断类型:0 为正常挂断,-1位异常挂断(超时等)