有奖捉虫:办公协同&微信生态&物联网文档专题 HOT

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)