TUICallKit

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 组件实例

<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)、连词符(-)和下划线(_)。
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+ 支持
范围:
长度限制为64个字节。支持的字符集范围如下(共89个字符):
小写和大写英文字母。(a-zA-Z);
数字(0-9);
空格!#$%&()+-:;<=.>?@[]^_{}|~,
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+ 支持
范围:
长度限制为64个字节。支持的字符集范围如下(共89个字符):
小写和大写英文字母。(a-zA-Z);
数字(0-9);
空格!#$%&()+-:;<=.>?@[]^_{}|~,
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+ 支持。
说明:
加入群组中已有的音视频通话前,需要提前创建或加入IM 群组,并且群组中已有用户在通话中,如果已经创建,请忽略。
群组的创建详见: IM 群组管理 ,或者您也可以直接使用 IM 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}`);
}

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 推送消息分类(已弃用的接口,VIVO 推送服务将在 2023 年 4 月 3 日优化消息分类规则。建议使用 setAndroidVIVOCategory 设置消息类别)。0:运营消息,1:系统消息。默认值为 1。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
远端用户在大窗显示