tencent cloud

文档反馈

TUICallKit

最后更新时间:2024-08-09 22:25:01

    API 简介

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

    API 概览

    TUICallKit 是音视频通话组件的含 UI 组件,您可以通过该组件快速实现一个类微信的音视频通话场景。
    <TUICallKit/>:UI 通话组件主体。
    TUICallKitServer 是通话实例,提供的 API 接口如下。
    API
    描述
    init
    初始化 TUICallKit 组件实例
    call
    发起 1v1 通话,支持自定义房间号、通话邀请超时时间,离线推送内容等
    groupCall
    发起群组通话,支持自定义房间号、通话邀请超时时间,离线推送内容等
    主动加入当前的群组通话中,v3.1.2+ 支持
    设置自定义来电铃音,v3.0.0+ 支持
    设置用户昵称和头像,v2.2.0+ 支持
    开启/关闭来电铃声,v3.1.2+ 支持
    开启/关闭悬浮窗功能,v3.1.0+ 支持
    开启/关闭模糊背景的功能按钮,v3.2.4+ 支持
    设置 TUICallKit 组件通话语言
    隐藏按钮,v3.2.9+ 支持
    设置本地用户通话界面背景图,v3.2.9+ 支持
    设置远端用户通话界面背景图,v3.2.9+ 支持
    设置通话界面布局模式,v3.3.0+ 支持
    设置摄像头是否默认打开,v3.3.0+ 支持
    destroyed
    销毁 TUICallKit 组件实例
    获取 TUICallEngine 实例,v2.4.3+ 支持

    <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})
    -
    ×

    示例代码

    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。
    注意:
    需完成 init 初始化,才能使用 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});
    console.log("[TUICallKit] Initialization succeeds.");
    } catch (error: any) {
    console.error(`[TUICallKit] Initialization failed. Reason: ${error}`);
    }
    参数如下表所示:
    参数
    类型
    是否必填
    含义
    SDKAppID
    Number
    应用的 SDKAppID,您可以在实时音视频控制台中找到您的 SDKAppID。具体详见 开通服务
    userID
    String
    即用户名,只允许包含英文字母(a-z 和 A-Z)、数字(0-9)、连词符(-)和下划线(_)。
    注意:不支持同一个 userID 在两台不同的设备上同时进入同一个房间通话,否则会相互干扰。
    userSig
    String
    使用 SDKSecretKey 对 SDKAppID、UserID 等信息进行加密,就可以得到 userSig。 它是一个鉴权用的票据,用于腾讯云识别当前用户是否能够使用 TRTC 的服务,获取方式请参考 如何计算 UserSig
    tim
    TencentCloudChat
    tim 是 TencentCloudChat SDK 的实例

    call

    拨打 1v1 通话,支持自定义房间号、通话邀请超时时间,离线推送内容等。
    import { TUICallKitServer, TUICallType } from '@tencentcloud/call-uikit-react';
    try {
    await TUICallKitServer.call({
    userID: 'mike', // username being called
    type: TUICallType.VIDEO_CALL,
    });
    } catch (error: any) {
    console.error(`[TUICallKit] Call failed. Reason: ${error}`);
    }
    参数如下表所示:
    参数
    类型
    是否必填
    含义
    userID
    String
    被呼叫用户的用户名
    type
    通话的媒体类型,参数值说明参考 TUICallType 通话类型
    roomID
    Number
    数字房间号,范围 [1, 2147483647]
    strRoomID
    String
    字符串房间号。v3.3.1+ 支持
    1. roomID 与 strRoomID 是互斥的,若您选用 strRoomID,则 roomID 需要填写为 0。若两者都填,SDK 将优先选用 roomID。
    2. 不要混用 roomID 和 strRoomID,因为它们之间是不互通的,比如数字 123 和字符串 "123" 是两个完全不同的房间。
    timeout
    Number
    通话超时时间,默认:30s,单位:秒。timeout = 0,设置为不超时
    userData
    String
    发起通话时自定义扩展字段,被呼叫用户在 ON_CALL_RECEIVED 事件中有该参数
    Object
    自定义离线消息推送参数

    groupCall

    发起群组通话,支持自定义房间号、通话邀请超时时间,离线推送内容等。
    import { TUICallKitServer, TUICallType } from '@tencentcloud/call-uikit-react';
    try {
    await TUICallKitServer.groupCall({
    userIDList: ['jack', 'tom'],
    groupID: 'xxx',
    type: TUICallType.VIDEO_CALL
    });
    } catch (error: any) {
    console.error(`[TUICallKit] Failed to call the groupCall API. Reason:${error}`);
    }
    参数如下表所示:
    参数
    类型
    是否必填
    含义
    userIDList
    Array<String>
    被呼叫的用户列表
    type
    通话的媒体类型,参数值说明参考TUICallType 通话类型
    groupID
    String
    此次群组通话的群 ID,groupID 的创建可参考 chat-createGroup API
    roomID
    Number
    数字房间号,范围 [1, 2147483647]
    strRoomID
    String
    字符串房间号。v3.3.1+ 支持
    1. roomID 与 strRoomID 是互斥的,若您选用 strRoomID,则 roomID 需要填写为 0。若两者都填,SDK 将优先选用 roomID。
    2. 不要混用 roomID 和 strRoomID,因为它们之间是不互通的,比如数字 123 和字符串 "123" 是两个完全不同的房间。
    timeout
    Number
    通话超时时间,默认:30s,单位:秒。timeout = 0,设置为不超时
    userData
    String
    发起通话时自定义扩展字段,被呼叫用户在 ON_CALL_RECEIVED 事件中有该参数
    Object
    自定义离线消息推送参数

    setLanguage

    设置语言,目前支持:中文、英文、日文。
    TUICallKitServer.setLanguage("zh-cn"); // "en" | "zh-cn" | "ja_JP"
    参数如下表所示:
    参数
    类型
    是否必填
    含义
    lang
    String
    语言类型 enzh-cnja_JP

    setSelfInfo

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

    setCallingBell

    注意:
    v3.0.0+ 支持。
    自定义用户的来电铃音。
    仅限传入本地 MP3 格式的文件地址,需要确保该文件目录是应用可以访问的。
    使用 import 方式引入铃声文件。
    如需恢复默认铃声,filePath 传空即可。
    import filePath from '../assets/phone_ringing.mp3';
    try {
    await TUICallKitServer.setCallingBell(filePath)
    } catch (error: any) {
    console.error(`[TUICallKit] Failed to call the setCallingBell API. Reason: ${error}`);
    }
    参数如下表所示:
    参数
    类型
    是否必填
    含义
    filePath
    String
    铃声文件地址

    enableFloatWindow

    开启/关闭悬浮窗功能。默认为false,通话界面左上角的悬浮窗按钮隐藏,设置为 true 后显示。
    注意:
    v3.1.0+ 支持。
    try {
    const enable = true;
    await TUICallKitServer.enableFloatWindow(enable);
    } catch (error: any) {
    console.error(`[TUICallKit] Failed to call the enableFloatWindow API. Reason: ${error}`);
    }
    参数如下表所示:
    参数
    类型
    是否必填
    含义
    enable
    Boolean
    开启/关闭悬浮窗功能

    enableMuteMode

    开启/关闭来电铃声。开启后,收到通话请求时,不会播放来电铃声。
    注意:
    v3.1.2+ 支持
    try {
    const enable = true;
    await TUICallKitServer.enableMuteMode(enable);
    } catch (error: any) {
    console.error(`[TUICallKit] Failed to call the enableMuteMode API. Reason: ${error}`);
    }
    参数如下表所示:
    参数
    类型
    是否必填
    含义
    enable
    Boolean
    开启/关闭来电铃声。默认 false。

    joinInGroupCall

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

    enableVirtualBackground

    开启/关闭模糊背景功能。如果想设置图片背景模糊参见 Web。通过调用接口,您可以在 UI 上显示模糊背景的功能按钮,点击按钮可直接启用模糊背景功能。
    注意:
    v3.2.4+ 支持。
    import { TUICallKitServer } from "@tencentcloud/call-uikit-react";
    const enable = true;
    TUICallKitServer.enableVirtualBackground(enable);
    参数列表:
    参数
    类型
    是否必填
    含义
    enable
    boolean
    enable = true 显示模糊背景按钮
    enable = false 不显示模糊背景按钮

    hideFeatureButton

    隐藏功能按钮,目前仅支持 摄像头,麦克风和切换前后置按钮。
    注意:
    v3.2.9+ 支持
    TUICallKitServer.hideFeatureButton(buttonName: FeatureButton);
    参数列表:
    参数
    类型
    是否必填
    含义
    buttonName
    按钮名称

    setLocalViewBackgroundImage

    设置本地用户通话背景。
    注意:
    v3.2.9+ 支持
    TUICallKitServer.setLocalViewBackgroundImage(url: string);
    参数列表:
    参数
    类型
    是否必填
    含义
    url
    string
    图片地址(支持本地路径和网络地址)

    setRemoteViewBackgroundImage

    设置远端用户通话背景。
    注意:
    v3.2.9+ 支持
    TUICallKitServer.setRemoteViewBackgroundImage(userId: string, url: string);
    参数列表:
    参数
    类型
    是否必填
    含义
    userId
    string
    远端用户 userId,设置为 '*' 表示对所有远端用户生效
    url
    string
    图片地址(支持本地路径和网络地址)

    setLayoutMode

    设置通话界面布局模式。
    注意:
    v3.3.0+ 支持。
    Vue
    React
    import { TUICallKitServer, LayoutMode } from "@tencentcloud/call-uikit-vue";
    TUICallKitServer.setLayoutMode(LayoutMode.LocalInLargeView);
    import { TUICallKitServer, LayoutMode } from "@tencentcloud/call-uikit-react";
    TUICallKitServer.setLayoutMode(LayoutMode.LocalInLargeView);
    参数列表:
    参数
    类型
    是否必填
    含义
    layoutMode
    用户流的布局模式

    setCameraDefaultState

    设置摄像头是否默认打开。
    注意:
    v3.3.0+ 支持。
    TUICallKitServer.setCameraDefaultState(true);
    参数列表:
    参数
    类型
    是否必填
    含义
    isOpen
    boolean
    是否开启摄像头

    destroyed

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

    getTUICallEngineInstance

    获取 getTUICallEngineInstance 实例。
    注意:
    v2.4.3+ 支持
    TUICallKitServer.getTUICallEngineInstance();

    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 属性值
    描述
    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
    离线推送透传内容,可以用于设置 Android Notification 模式VoIP 模式默认:Notification 模式,会是系统的通知;VoIP 模式是需要传字段。
    offlinePushInfo.ignoreIOSBadge
    Boolean
    离线推送忽略 badge 计数(仅对 iOS 生效), 如果设置为 true,在 iOS 接收端,这条消息不会使 APP 的应用图标未读计数增加
    v3.3.0+ 支持
    offlinePushInfo.iOSSound
    String
    离线推送声音设置(仅对 iOS 生效)。v3.3.0+ 支持
    offlinePushInfo.androidSound
    String
    离线推送声音设置(仅对 Android 生效)。v3.3.0+ 支持
    offlinePushInfo.androidVIVOClassification
    Number
    VIVO 推送消息分类。v3.3.0+ 支持
    offlinePushInfo.androidXiaoMiChannelID
    String
    小米手机 8.0 系统及以上的渠道 ID。v3.3.0+ 支持
    offlinePushInfo.androidFCMChannelID
    String
    FCM 通道手机 8.0 系统及以上的渠道 ID。v3.3.0+ 支持
    offlinePushInfo.androidHuaWeiCategory
    String
    华为推送消息分类。v3.3.0+ 支持
    offlinePushInfo.isDisablePush
    Boolean
    是否关闭推送(默认开启推送)。v3.3.0+ 支持
    offlinePushInfo.iOSPushType
    Number
    iOS 离线推送类型。0-普通推送;1-VoIP推送。默认:0。v3.3.0+ 支持

    Android Notification 模式

    const extension = {
    timPushFeatures: {
    fcmPushType: 0, // 0, VoIP; 1, notification
    }
    };
    offlinePushInfo.extension = JSON.stringify(extension);

    Android VoIP 模式

    const extension = {
    timPushFeatures: {
    fcmPushType: 0, // 0, data; 1, notification
    fcmNotificationType: 1, // 0, TIMPush implementation; 1, business implementation after transparent transmission
    }
    };
    offlinePushInfo.extension = JSON.stringify(extension);

    FeatureButton

    FeatureButton 类型
    描述
    FeatureButton.Camera
    摄像头按钮
    FeatureButton.Microphone
    麦克风按钮
    FeatureButton.SwitchCamera
    切换前后置摄像头按钮
    FeatureButton.InviteUser
    邀请他人按钮

    LayoutMode

    LayoutMode 类型
    描述
    LayoutMode.LocalInLargeView
    本地用户在大窗显示
    LayoutMode.RemoteInLargeView
    远端用户在大窗显示
    联系我们

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

    技术支持

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

    7x24 电话支持