场景实践

TRTCCalling API(小程序)

最近更新时间:2021-08-19 11:57:39

组件介绍

TRTCCalling 小程序组件是基于腾讯云实时音视频(TRTC)和腾讯云信令 SDK(TSignalling)组合而成,支持1V1,多人场景下的语音通话。TRTCCalling 是一个开源组件,依赖闭源的信令 SDK(TSignalling)进行状态管理,通过 C2C 通信,完成信令传递。组件可快速服务线上客服,咨询,医疗问诊,跨端实时通话等应用场景。您可前往 【Github】或单击 【ZIP】,下载相关 SDK 及配套的 Demo 源码。

环境要求

  • 微信 App iOS 最低版本要求:7.0.9。
  • 微信 App Android 最低版本要求:7.0.8。
  • 小程序基础库最低版本要求:2.10.0。
  • 由于微信开发者工具不支持原生组件(即 <live-pusher> 和 <live-player> 标签),需要在真机上进行运行体验。
  • 由于小程序测试号不具备 <live-pusher> 和 <live-player> 的使用权限,需要申请常规小程序账号进行开发。
  • 不支持 uniapp 开发环境,请使用原生小程序开发环境。

前提条件

  1. 您已 注册腾讯云 账号,并完成 实名认证
  2. 开通小程序类目与推拉流标签权限(如不开通则无法正常使用)
    出于政策和合规的考虑,微信暂未放开所有小程序对实时音视频功能(即 <live-pusher> 和 <live-player> 标签)的支持:
    • 小程序推拉流标签不支持个人小程序,只支持企业类小程序。
    • 小程序推拉流标签使用权限暂时只开放给有限 类目
    • 符合类目要求的小程序,需要在【微信公众平台】>【开发】>【开发管理】>【接口设置】中自助开通该组件权限,如下图所示:

TRTCCalling API 概览

事件订阅/取消订阅

本组件基于事件分发进行管理,应用层可以根据组件下发的事件进行上层交互的改变。

API 描述
on(eventCode, handler, context) 订阅事件。
off(eventCode, handler) 取消事件订阅。

邀请方函数

邀请方拨打后,会收到该邀请的对端处理结果,详情可在 事件表 查询。

API 描述
call({userID, type}) 发出 C2C 通话邀请。
groupCall({userIDList, type, groupID}) 群组邀请通话(请先 创建 IM 群组)。

被邀请方函数

被邀请方如果超过30s对邀请为做出处理,将会做超时处理。

API 描述
accept() 接受通话邀请。
reject() 拒绝通话邀请。

通用功能函数

API 描述
login() 初始化信令 SDK,执行后才能正常进行信令收发。
logout() 登出信令 SDK,执行后不再能收发信令。
hangup() 结束当前通话。
setMicMute(isMute) 设置麦克风状态。
  • 当 isMute 取值为 true:关闭麦克风。
  • 当 isMute 取值为 false:打开麦克风。
  • setHandsFree(isHandsFree) 设置声音播放状态。
  • 当 isHandsFree 取值为 true:外放模式。
  • 当 isHandsFree 取值为 false: 听筒模式。
  • 属性表

    <TRTCCalling> 属性

    属性 类型 默认值 必填 说明
    id String 绑定TRTCCalling的dom ID,可通过this.selectComponent(ID)获取实例
    config Object TRTCCalling初始化配置
    backgroundMute Boolean false 进入后台时是否保持音频通话,true保持、false挂断

    config 参数

    参数 类型 必填 说明
    sdkAppID Number 开通实时音视频服务创建应用后分配的 SDKAppID
    userID String 用户 ID,可以由您的帐号体系指定。
    userSig String 身份签名(即相当于登录密码),由 userID 计算得出,具体计算方法请参见 如何计算 UserSig
    type Number 指定通话类型。1:语音通话,2:视频通话。

    示例代码:

    // index.wxml
    <TRTCCalling id="TRTCCalling-room" config="{{config}}" backgroundMute="{{false}}"></TRTCCalling>

    // videocall.js
    trtcConfig = {
    sdkAppID: 0, // 开通实时音视频服务创建应用后分配的 SDKAppID
    userID: 'test_user_001', // 用户 ID,可以由您的帐号系统指定
    userSig: 'xxxxxxxxxxxx', // 身份签名,相当于登录密码的作用
    type: 1, // 通话模式
    }

    组件方法

    selectComponent()

    您可以通过小程序提供的 this.selectComponent() 方法获取组件实例。

    let TRTCCallingContext = this.selectComponent('#TRTCCalling-room')
    TRTCCallingContext.login()

    login()

    登入接口,会建议在页面 onLoad 阶段调用。

    TRTCCallingContext.login()

    logout()

    登出信令 SDK,执行后不再能收发信令。

    TRTCCallingContext.logout()

    on(eventCode, handler, context)

    用于监听组件派发的事件,详细事件请参见 事件表

    TRTCCallingContext.on(EVENT.INVITED, () => {
      // todo
    })

    off(eventCode, handler)

    用于取消事件监听。

    TRTCCallingContext.off(EVENT.INVITED)

    call({userID, type})

    进行某个 user 进行呼叫。

    参数 含义
    userID 希望呼叫用户的 userID。
    type 通话类型,type = 1:语音通话,type = 2:视频通话。

    let userID = 'test'
    let type = 2
    TRTCCallingContext.call({userID, type})

    groupCall({userIDList, type, groupID})

    在调用该接口前需要使用 IM 创建群组,并将 groupID 作为参数传入。

    参数 类型 含义
    userIDList Arrary 拨打的用户列表。
    type Number type 为通话类型,1:语音通话,2:视频通话。
    groupID String IM 群组的 groupID。

    TRTCCallingContext.groupCall({userIDList, type, groupID})

    accept()

    当收到邀请后,调用该接口将接受当前的邀请。

    说明:

    当上一个 invitation 未处理完成时,组件会默认占线,之后的邀请都会回复忙线。

    TRTCCallingContext.on(EVENT.INVITED, () => {
    TRTCCallingContext.accept()
    })

    reject()

    当收到邀请后,调用该接口将拒绝当前收到的邀请。

    TRTCCallingContext.on(EVENT.INVITED, () => {
    TRTCCallingContext.reject()
    })

    hangup()

    结束当前通话。

    TRTCCallingContext.hangup()

    setMicMute(isMute)

    设置麦克风状态。

    参数 含义
    isMute true:关闭麦克风,false:打开麦克风。

    TRTCCallingContext.setMicMute(true) // 开启麦克风

    setHandsFree(isHandsFree)

    设置声音播放状态。

    参数 含义
    isHandsFree true:外放模式,false:听筒模式。

    TRTCCallingContext.setHandsFree(true) // 开启外放模式

    事件表

    获取 EVENT 事件。

    const TRTCCallingContext = this.selectComponent('#TRTCCalling-room')
    const EVENT = trtcRoomContext.EVENT // 以下事件均在此EVENT对象下

    邀请方事件

    REJECT

    邀请方发出的邀请被拒绝。

    参数 类型 含义
    invitee String 被邀请人。
    inviteID String 邀请 ID。
    reason String 拒绝理由。

    NO_RESP

    邀请方发出的邀请无人响应(对方不在线)

    参数 类型 含义
    inviteID String 邀请ID。
    timeoutUserList Array 超时用户列表。

    CALLING_TIMEOUT

    邀请方发出的邀请无人响应(在线未接受邀请)

    参数 类型 含义
    inviteID String 邀请ID。
    timeoutUserList Array 超时用户列表。
    groupID String 群组ID。
    sponsor String 邀请者。

    LINE_BUSY

    被邀请方正在通话中,忙线。

    参数 类型 含义
    invitee String 被邀请人。
    inviteID String 邀请 ID。
    reason String 拒绝理由。

    CALLING_CANCEL

    接受的邀请被取消。

    参数 类型 含义
    invitee String 被邀请人。
    inviteID String 邀请 ID。

    被邀请方事件

    INVITED

    收到邀请通知。

    参数 类型 含义
    sponsor String 邀请人。
    isFromGroup Boolean 是否是群通话。
    inviteID String 邀请ID。
    inviteData Object callType: 通话类型,
    roomID: 房间号。

    CALLING_CANCEL

    接受的邀请被取消。

    参数 类型 含义
    invitee String 被邀请人。
    inviteID String 邀请 ID。

    通用事件

    USER_ENTER

    用户进房。

    参数 类型 含义
    userID String 加入的用户。

    USER_LEAVE

    用户退出房间。

    参数 类型 含义
    userID String 离开的用户。

    CALL_END

    本次通话结束。

    参数 类型 含义
    call_end String 通话结束事件。

    USER_VOICE_VOLUME

    本地和远端用户的音量回调。

    参数 类型 含义
    userID String 通话人。
    volume Number 音量。

    HANG_UP

    挂断电话。

    异常捕获

    通过监听 EVENT 里的 ERROR 字段,对组件抛出的错误进行处理。

    let EVENT = trtcRoomContext.EVENT
    trtcRoomContext.on(EVENT.ERROR,(event)=>{
    console.log(event.data)
    })

    常见问题

    为什么拨打不通,或者被踢下线?

    组件暂不支持多实例登入,不支持离线推送信令功能,请您确认账号登入的唯一性。

    • 多实例:一个 userID 重复登入,或在不同端登入,将会引起信令的混乱。
    • 离线推送:实例在线才能接收消息,实例离线时接收到的信令不会在上线后重新推送。
    目录