tencent cloud

文档反馈

TUICallKit

最后更新时间:2024-05-08 11:39:30

    API 简介

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

    API 概览

    <TUICallKit />: TUICallKit UI 通话组件主体。
    <TUICallKitMini/>:TUICallKit UI 通话悬浮窗,当<TUICallKit :allowedMinimized="true"/>时,<TUICallKitMini/>必须被放置在页面中。
    注意:
    <TUICallKitMini/>UI 通话悬浮窗,≥ v2.3.2 废弃,不再提供该组件
    <TUICallKit /> UI 通话组件主体,实现悬浮窗样式,减少使用复杂度。
    API
    描述
    init
    初始化 TUICallKit。
    call
    发起 1v1 通话
    groupCall
    发起群组通话
    主动加入当前的群组通话中
    设置自定义来电铃音
    设置用户昵称和头像
    开启/关闭来电铃声
    开启/关闭悬浮窗功能
    设置 TUICallKit 组件通话语言
    destroyed
    销毁 TUICallKit

    TUICallKit 属性介绍

    属性概览

    属性
    描述
    类型
    是否必填
    默认值
    支持 vue
    支持 react
    allowedMinimized
    是否允许悬浮窗
    boolean
    false
    allowedFullScreen
    是否允许通话界面全屏
    boolean
    true
    通话界面显示模式
    VideoDisplayMode
    VideoDisplayMode.COVER
    通话分辨率
    VideoResolution
    VideoResolution.RESOLUTION_480P
    beforeCalling
    拨打电话前与收到通话邀请前会执行此函数
    function(type, error)
    -
    afterCalling
    结束通话后会执行此函数
    function()
    -
    
    onMinimized
    
    组件切换最小化状态时会执行此函数,STATUS 值说明
    function(oldStatus, newStatus)
    -
    ×
    
    kickedOut
    
    组件抛出的事件,当前登录用户被踢出登录时会触发该事件,通话也会自动结束
    function()
    -
    ×
    
    statusChanged
    
    组件抛出的事件,当通话状态发生变化时,会触发该事件,通话状态种类详见,STATUS 值说明
    function({oldStatus, newStatus})
    -
    ×
    
    @kicked-out
    
    注意:≥ v2.3.2 废弃
    组件抛出的事件,当前登录用户被踢出登录时会触发该事件,通话也会自动结束
    function()
    -
    ×
    
    @status-changed
    
    注意:≥ v2.3.2 废弃
    组件抛出的事件,当通话状态发生变化时,会触发该事件,通话状态种类详见,STATUS 值说明
    function({oldStatus, newStatus})
    -
    ×

    示例代码

    React
    Vue
    import { TUICallKit, VideoDisplayMode, VideoResolution } from "@tencentcloud/call-uikit-react";
    
    <TUICallKit
    videoDisplayMode={VideoDisplayMode.CONTAIN}
    videoResolution={VideoResolution.RESOLUTION_1080P}
    beforeCalling={handleBeforeCalling}
    afterCalling={handleAfterCalling}
    />
    
    function handleBeforeCalling(type: string, error: any) {
    console.log("[TUICallkit Demo] handleBeforeCalling:", type, error);
    }
    function handleAfterCalling() {
    console.log("[TUICallkit Demo] handleAfterCalling");
    }
    <template>
    <TUICallKit
    :allowedMinimized="true"
    :allowedFullScreen="true"
    :videoDisplayMode="VideoDisplayMode.CONTAIN"
    :videoResolution="VideoResolution.RESOLUTION_1080P"
    :beforeCalling="beforeCalling"
    :afterCalling="afterCalling"
    :onMinimized="onMinimized"
    :kickedOut="handleKickedOut"
    :statusChanged="handleStatusChanged"
    />
    </template>
    <script lang="ts" setup>
    import { TUICallKit, TUICallKitServer, VideoDisplayMode, VideoResolution, STATUS } from "@tencentcloud/call-uikit-vue";
    
    function beforeCalling(type: string, error: any) {
    console.log("[TUICallkit Demo] beforeCalling:", type, error);
    }
    function afterCalling() {
    console.log("[TUICallkit Demo] afterCalling");
    }
    function onMinimized(oldStatus: string, newStatus: string) {
    console.log("[TUICallkit Demo] onMinimized: " + oldStatus + " -> " + newStatus);
    }
    function kickedOut() {
    console.log("[TUICallkit Demo] kickedOut");
    }
    function statusChanged(args: { oldStatus: string; newStatus: string; }) {
    const { oldStatus, newStatus } = args;
    if (newStatus === STATUS.CALLING_C2C_VIDEO) {
    console.log(`[TUICallkit Demo] statusChanged: ${oldStatus} -> ${newStatus}`);
    }
    }
    </script>

    TUICallKitServer API 详情

    import { TUICallKitServer } from "@tencentcloud/call-uikit-react";
    // Replace it with the call-uikit npm package you are currently using

    init

    初始化 TUICallKit,必须在 call, groupCall 之前进行。
    try {
    await TUICallKitServer.init({ SDKAppID, userID, userSig });
    // If you already have a tim instance in your project, you need to pass it in here
    // await TUICallKitServer.init({ tim, SDKAppID, userID, userSig});
    alert("[TUICallKit] Initialization succeeds.");
    } catch (error: any) {
    alert(`[TUICallKit] Initialization failed. Reason: ${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
    });
    } catch (error: any) {
    alert(`[TUICallKit] Call failed. Reason: ${error}`);
    }
    参数如下表所示:
    参数
    类型
    是否必填
    含义
    userID
    String
    目标用户的 userId
    type
    通话的媒体类型,参数值说明参考 TUICallType 通话类型
    兼容旧版本:语音通话(type = 1)、视频通话(type = 2)
    roomID
    Number
    数字房间号,范围 [1, 2147483647]
    timeout
    Number
    通话的超时时间,0 为不超时, 单位 s(秒)(选填) - 默认 30s
    被叫需要在 30s 内处于登录状态,timeout 值才会有效,具体参考 timeout 字段设置无效
    userData
    String
    扩展字段: 用于在邀请信令中增加扩展信息
    Object
    自定义离线消息推送(选填)-- 需 tsignaling 版本 >= 0.8.0

    groupCall

    发起群组通话。
    try {
    await TUICallKitServer.groupCall({
    userIDList: ['jack', 'tom'],
    groupID: "xxx",
    type: TUICallType.VIDEO_CALL
    });
    } catch (error: any) {
    alert(`[TUICallKit] Failed to call the groupCall API. Reason:${error}`);
    }
    参数如下表所示:
    参数
    类型
    是否必填
    含义
    userIDList
    Array<String>
    邀请列表成员列表
    type
    通话的媒体类型,参数值说明参考TUICallType 通话类型
    兼容旧版本:语音通话(type = 1)、视频通话(type = 2)
    groupID
    String
    通话群组 ID,groupID 的创建可参考 chat-createGroup API
    roomID
    Number
    数字房间号,范围 [1, 2147483647]
    timeout
    Number
    通话的超时时间,0 为不超时, 单位 s(秒)(选填) - 默认 30s
    被叫需要在 30s 内处于登录状态,timeout 值才会有效,具体参考 timeout 字段设置无效
    userData
    String
    扩展字段:用于在邀请信令中增加扩展信息
    Object
    自定义离线消息推送(选填)(tsignaling 版本 >= 0.8.0)

    setLanguage

    设置 TUICallKit 组件通话语言。
    默认语言为浏览器的语言。
    TUICallKitServer.setLanguage("zh-cn"); // "en" | "zh-cn"
    参数如下表所示:
    参数
    类型
    是否必填
    含义
    lang
    String
    语言类型enzh-cn

    setSelfInfo

    注意:
    Vue ≥ v2.2.0 支持。通话中使用该接口修改用户信息,UI 不会立即更新,需要等到下次通话才能看到变化。
    设置当前用户昵称和头像。
    try {
    await TUICallKitServer.setSelfInfo({ nickName: "xxx", avatar: "http://xxx" });
    } catch (error: any) {
    alert(`[TUICallKit] Failed to call the setSelfInfo API. Reason: ${error}`);
    }
    参数如下表所示:
    参数
    类型
    是否必填
    含义
    nickName
    String
    用户昵称
    avatar
    String
    用户头像地址

    setCallingBell

    注意:Vue ≥ v3.0.0 支持
    自定义用户的来电铃音。
    仅限传入本地 MP3 格式的文件地址,需要确保该文件目录是应用可以访问的。
    使用 ES6 import 方式引入铃声文件。
    try {
    await TUICallKitServer.setCallingBell(filePath?: string)
    } catch (error: any) {
    alert(`[TUICallKit] Failed to call the setCallingBell API. Reason: ${error}`);
    }

    enableFloatWindow

    注意:
    Vue ≥ v3.1.0 支持
    开启/关闭悬浮窗功能。
    默认为false,通话界面左上角的悬浮窗按钮隐藏,设置为 true 后显示。
    try {
    await TUICallKitServer.enableFloatWindow(enable: Boolean)
    } catch (error: any) {
    alert(`[TUICallKit] Failed to call the enableFloatWindow API. Reason: ${error}`);
    }

    enableMuteMode

    注意:Vue ≥ v3.1.2 支持
    开启/关闭来电铃声。
    开启后,收到通话请求时,不会播放来电铃声。
    try {
    await TUICallKitServer.enableMuteMode(enable: boolean)
    } catch (error: any) {
    alert(`[TUICallKit] Failed to call the enableMuteMode API. Reason: ${error}`);
    }

    joinInGroupCall

    注意:Vue ≥ v3.1.2 支持
    加入群组中已有的音视频通话。
    说明:
    加入群组中已有的音视频通话前,需要提前创建或加入IM 群组,并且群组中已有用户在通话中,如果已经创建,请忽略。
    群组的创建详见: IM 群组管理 ,或者您也可以直接使用 IM TUIKit,一站式集成聊天、通话等场景。
    try {
    const params = {
    type: TUICallType.VIDEO_CALL,
    groupID: "xxx",
    roomID: 0,
    };
    await TUICallKitServer.joinInGroupCall(params);
    } catch (error: any) {
    alert(`[TUICallKit] Failed to call the enableMuteMode API. Reason: ${error}`);
    }
    参数列表:
    参数
    类型
    是否必填
    含义
    type
    通话的媒体类型,例如视频通话、语音通话
    groupID
    string
    此次群组通话的群 ID
    roomID
    number
    此次通话的音视频房间 ID

    destroyed

    销毁 TUICallKit 实例。
    该方法不会自动退出tim,需要手动退出tim.logout();
    try {
    await TUICallKitServer.destroyed();
    } catch (error: any) {
    alert(`[TUICallKit] Failed to call the destroyed API. Reason: ${error}`);
    }

    TUICallKit 类型定义

    videoDisplayMode

    画面显示模式 videoDisplayMode 属性有三个值:
    VideoDisplayMode.CONTAIN
    VideoDisplayMode.COVER
    VideoDisplayMode.FILL,默认值是VideoDisplayMode.COVER
    属性
    描述
    videoDisplayMode
    VideoDisplayMode.CONTAIN
    优先保证视频内容全部显示。
    视频尺寸等比缩放,直至视频窗口的一边与视窗边框对齐。
    如果视频尺寸与显示视窗尺寸不一致,在保持长宽比的前提下,将视频进行缩放后填满视窗,缩放后的视频四周会有一圈黑边。
    VideoDisplayMode.COVER
    优先保证视窗被填满。
    视频尺寸等比缩放,直至整个视窗被视频填满。
    如果视频长宽与显示窗口不同,则视频流会按照显示视窗的比例进行周边裁剪或图像拉伸后填满视窗。
    VideoDisplayMode.FILL
    保证视窗被填满的同时保证视频内容全部显示,但是不保证视频尺寸比例不变。
    视频的宽高会被拉伸至和视窗尺寸一致。

    videoResolution

    分辨率 videoResolution 有三个值:
    VideoResolution.RESOLUTION_480P
    VideoResolution.RESOLUTION_720P
    VideoResolution.RESOLUTION_1080P,默认值是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 尽可能匹配设定值。

    STATUS

    属性值
    描述
    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
    正在群组视频通话

    TUICallType

    TUICallType 类型
    描述
    TUICallType.AUDIO_CALL
    语音通话
    TUICallType.VIDEO_CALL
    视频通话

    offlinePushInfo

    参数
    类型
    是否必填
    含义
    offlinePushInfo.title
    String
    离线推送标题(选填)
    offlinePushInfo.description
    String
    离线推送内容(选填)
    offlinePushInfo.androidOPPOChannelID
    String
    离线推送设置 OPPO 手机 8.0 系统及以上的渠道 ID(选填)
    offlinePushInfo.extension
    String
    离线推送透传内容(选填)(tsignaling 版本 >= 0.9.0)
    联系我们

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

    技术支持

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

    7x24 电话支持