tencent cloud

文档反馈

TUICallKit

最后更新时间:2023-06-30 16:17:14

    API 简介

    TUICallKit API 是音视频通话组件的含 UI 接口,使用 TUICallKit API,您可以通过简单接口快速实现一个类微信的音视频通话场景,更详细的接入步骤,详见:快速接入 TUICallKit

    API 概览

    <TUICallKit/>:UI 通话组件主体
    <TUICallKitMini/>:UI 通话悬浮窗,若 <TUICallKit :allowedMinimized="true"/> 时,则 <TUICallKitMini/> 必须被放置在页面中
    TUICallKitServer: 通话实例,成员函数:
    init 初始化 TUICallKit
    call 发起 1v1 通话
    groupCall 发起群组通话
    setLanguage 修改语言
    destroyed 销毁 TUICallKit

    <TUICallKit/> API 详情

    属性

    参数
    说明
    类型
    是否必填
    默认值
    allowedMinimized
    是否允许最小化,最小化按钮会隐藏
    boolean
    false
    allowedFullScreen
    是否允许全屏,全屏按钮会隐藏
    boolean
    true
    videoDisplayMode
    画面显示模式
    VideoDisplayMode
    VideoDisplayMode.COVER
    videoResolution
    通话分辨率
    VideoResolution
    VideoResolution.RESOLUTION_480P
    beforeCalling
    拨打电话前与收到通话邀请前会执行此函数
    function(type, error)
    -
    afterCalling
    结束通话后会执行此函数
    function()
    -
    onMinimized
    组件切换最小化状态时会执行此函数
    function(oldStatus, newStatus)
    -
    @kicked-out
    组件抛出的事件,当前登录用户被踢出登录是会触发该事件,通话也会自动结束
    @kicked-out="handleKickedOut"
    -
    @status-changed
    组件抛出的事件,当通话状态发生变化时,会触发该事件,通话状态种类详见下方备注
    @status-changed="handleStatusChanged"
    -
    参数备注:
    1. 画面显示模式 videoDisplayMode 有三个值:VideoDisplayMode.CONTAINVideoDisplayMode.COVERVideoDisplayMode.FILL,默认值是 VideoDisplayMode.COVER
    VideoDisplayMode.CONTAIN 优先保证视频内容全部显示。视频尺寸等比缩放,直至视频窗口的一边与视窗边框对齐。如果视频尺寸与显示视窗尺寸不一致,在保持长宽比的前提下,将视频进行缩放后填满视窗,缩放后的视频四周会有一圈黑边。
    VideoDisplayMode.COVER 优先保证视窗被填满。视频尺寸等比缩放,直至整个视窗被视频填满。如果视频长宽与显示窗口不同,则视频流会按照显示视窗的比例进行周边裁剪或图像拉伸后填满视窗。
    VideoDisplayMode.FILL 保证视窗被填满的同时保证视频内容全部显示,但是不保证视频尺寸比例不变。视频的宽高会被拉伸至和视窗尺寸一致。
    2. 分辨率 videoResolution 有三个值:VideoResolution.RESOLUTION_480PVideoResolution.RESOLUTION_720PRESOLUTION_1080P.FILL,默认值是 VideoResolution.RESOLUTION_480P
    视频 Profile
    分辨率(宽 × 高)
    帧率(fps)
    码率(kbps)
    480p
    640 × 480
    15
    900
    720p
    1280 × 720
    15
    1500
    1080p
    1920 × 1080
    15
    2000
    iOS 13 & 14 不支持编码高于 720P 的视频,建议在这两个系统版本限制最高采集 720P。参考 iOS Safari 已知问题 case 12
    Firefox 不支持自定义视频帧率(默认为 30fps)。
    受系统性能占用,摄像头采集能力和浏览器限制等因素的影响,视频分辨率,帧率,码率的实际值不一定能够完全匹配设定值,在这种情况下,浏览器会自动调整 Profile 尽可能匹配设定值。
    3. @status-changed 可以抛出通话组件内部的状态,handleStatusChanged({ oldStatus, newStatus }) 接收新状态和旧状态,使用方法参照下方示例代码,其中状态有以下几种:
    import { STATUS } from "@tencentcloud/call-uikit-vue";
    常量
    含义
    STATUS.IDLE
    闲置状态
    STATUS.BE_INVITED
    收到通话邀请
    STATUS.DIALING_C2C
    正在 1v1 呼叫
    STATUS.DIALING_GROUP
    正在群组呼叫
    STATUS.CALLING_C2C_AUDIO
    正在 1v1 语音通话
    STATUS.CALLING_C2C_VIDEO
    正在 1v1 视频通话
    STATUS.CALLING_GROUP_AUDIO
    正在群组语音通话
    STATUS.CALLING_GROUP_VIDEO
    正在群组视频通话

    示例代码

    <TUICallKit
    :allowedMinimized="true"
    :allowedFullScreen="true"
    :videoDisplayMode="VideoDisplayMode.CONTAIN"
    :videoResolution="VideoResolution.RESOLUTION_1080P"
    :beforeCalling="beforeCalling"
    :afterCalling="afterCalling"
    :onMinimized="onMinimized"
    @kicked-out="handleKickedOut"
    @status-changed="handleStatusChanged"
    />
    <TUICallKitMini />
    ```
    
    ```javascript
    import { TUICallKit, TUICallKitMini, TUICallKitServer, VideoDisplayMode, VideoResolution, STATUS } from "@tencentcloud/call-uikit-vue"; // vue2 要换成 '@tencentcloud/call-uikit-vue2'
    
    /**
    * beforeCalling
    * @param { string } type 值为 "invited" | "call" | "groupCall", 可用于区分是来电还是拨打
    * @param { number } error.code 错误码
    * @param { string } error.type 错误类型
    * @param { string } error.code 错误信息
    */
    function beforeCalling(type, error) {
    console.log("通话前 会执行此函数,类型: ", type, error);
    }
    
    function afterCalling() {
    console.log("通话后 会执行此函数");
    }
    
    /**
    * onMinimized
    * @param { boolean } oldStatus
    * @param { boolean } newStatus
    */
    function onMinimized(oldStatus, newStatus) {
    if (newStatus === true) {
    console.log("TUICallKit 进入最小化状态");
    } else {
    console.log("TUICallKit 退出最小化状态");
    }
    }
    
    function handleKickedOut() {
    console.error("The user has been kicked out");
    }
    
    function handleStatusChanged(args: { oldStatus: string; newStatus: string; }) {
    const { oldStatus, newStatus } = args;
    if (newStatus === STATUS.CALLING_C2C_VIDEO) {
    console.log(`[Call Demo] 正在进行 1v1 视频通话,状态变更 ${oldStatus} -> ${newStatus}`);
    }
    }

    TUICallKitServer API 详情

    引入 TUICallKitServer

    vue3
    vue2
    import { TUICallKitServer } from "@tencentcloud/call-uikit-vue";
    import { TUICallKitServer } from "@tencentcloud/call-uikit-vue2";

    init

    初始化 TUICallKit,需在 call, groupCall 之前进行。
    try {
    await TUICallKitServer.init({ SDKAppID, userID, userSig });
    // await TUICallKitServer.init({ tim, SDKAppID, userID, userSig}); // 如果工程中已有 tim 实例,需在此处传入
    alert("初始化完成");
    } catch (error: any) {
    alert(`初始化失败,原因:${error}`);
    }
    参数如下表所示:
    参数
    类型
    是否必填
    含义
    SDKAppID
    Number
    云通信应用的 SDKAppID
    userID
    String
    当前用户的 ID,字符串类型,只允许包含英文字母(a-z 和 A-Z)、数字(0-9)、连词符(-)和下划线(_)
    userSig
    String
    腾讯云设计的一种安全保护签名,获取方式请参考 如何计算 UserSig
    tim
    Any
    tim 参数适用于业务中已存在 TIM 实例,为保证 TIM 实例唯一性

    call

    拨打电话(1v1通话)。
    try {
    await TUICallKitServer.call({ userID: callUserID, type: TUICallType.VIDEO_CALL }); // 1v1 通话
    } catch (error: any) {
    alert(`拨打失败,原因:${error}`);
    }
    参数如下表所示:
    参数
    类型
    是否必填
    含义
    userID
    String
    目标用户的 userId
    type
    Number
    通话的媒体类型,语音通话(type = 1)、视频通话(type = 2)
    timeout
    Number
    通话的超时时间,0 为不超时, 单位 s(秒)(选填) - 默认 30s
    Object
    自定义离线消息推送(选填)-- 需 tsignaling 版本 >= 0.8.0
    
    其中对于 offlinePushInfo
    参数
    类型
    是否必填
    含义
    offlinePushInfo.title
    String
    离线推送标题(选填)
    offlinePushInfo.description
    String
    离线推送内容(选填)
    offlinePushInfo.androidOPPOChannelID
    String
    离线推送设置 OPPO 手机 8.0 系统及以上的渠道 ID(选填)
    offlinePushInfo.extension
    String
    离线推送透传内容(选填)(tsignaling 版本 >= 0.9.0)

    groupCall

    发起群组通话。
    try {
    await TUICallKitServer.groupCall({ userIDList: ['jack', 'tom'], groupID: "xxx", type: TUICallType.VIDEO_CALL }); // 群组通话
    } catch (error: any) {
    alert(`拨打失败,原因:${error}`);
    }
    参数如下表所示:
    参数
    类型
    是否必填
    含义
    userIDList
    Array<String>
    邀请列表成员列表
    type
    Number
    通话的媒体类型,语音通话(type = 1)、视频通话(type = 2)
    groupID
    String
    呼叫群组ID
    timeout
    Number
    通话的超时时间,0 为不超时, 单位 s(秒)(选填) - 默认 30s
    offlinePushInfo
    Object
    自定义离线消息推送(选填)-- 需 tsignaling 版本 >= 0.8.0
    其中对于 offlinePushInfo,与 call 接口中一致。

    setLanguage

    设置语言。
    TUICallKitServer.setLanguage("zh-cn"); // "en" | "zh-cn"
    参数如下表所示:
    参数
    类型
    是否必填
    含义
    lang
    String
    语言类型 enzh-cn

    destroyed

    销毁 TUICallKit。
    注意:此方法不会自动退出 tim,需要手动退出 tim.logout();
    try {
    await TUICallKitServer.destroyed();
    } catch (error: any) {
    alert(`销毁实例失败,原因:${error}`);
    }
    
    联系我们

    联系我们,为您的业务提供专属服务。

    技术支持

    如果你想寻求进一步的帮助,通过工单与我们进行联络。我们提供7x24的工单服务。

    7x24 电话支持