Menu

TUICallKit

Last updated: 2023-09-19 16:02:50Download PDF
TUICallKit is an audio/video call component that includes UI elements. You can use its APIs to quickly implement an audio/video call application similar to WeChat. For directions on integration, see Integrating TUICallKit.

Overview

<TUICallKit/>: The call component.
<TUICallKitMini/>: The floating call window. If <TUICallKit/>allowedMinimized is true, <TUICallKitMini/> is required.
TUICallKitServer: The call instance, which has the following APIs:
init: Initializes TUICallKit.
call: Makes a one-to-one call.
groupCall: Makes a group call.
setLanguage: Set component language.
setSelfInfo: Set the user nickname and avatar.
setCallingBell: Set custom ringtone for incoming calls.
destroyed: Terminates TUICallKit.

<TUICallKit/> API details

Attributes

Parameter
Description
Type
Required
Default Value
allowedMinimized
Whether to allow window minimization. If this is true, TUICallKitMini is required. If this is false, the minimize button will be hidden.
boolean
No
false
allowedFullScreen
Whether to allow full screen. If this is false, the full screen button will be hidden.
boolean
No
true
videoDisplayMode
Screen display mode
VideoDisplayMode
No
VideoDisplayMode.COVER
videoResolution
Call resolution
VideoResolution
No
VideoResolution.RESOLUTION_480P
beforeCalling
This is executed when the user makes or receives a call.
function(type, error)
No
-
afterCalling
This is executed after a call ends.
function()
No
-
onMinimized
This is executed when the component is minimized.
function(oldStatus, newStatus)
No
-
kickedOut
The callback is triggered when the currently logged-in user is kicked out of the session, and the call will automatically end.
Notes:
Supported in version 2.3.2 and above.

function()
No
-
statusChanged
The callback is triggered when there is a change in the call status. Please refer to the notes below for the detailed list of call status types.
Notes:
Supported in version 2.3.2 and above.

function({oldStatus, newStatus})
No
-
@kicked-out
The event thrown by the component will be triggered when the currently logged in user is kicked out of the login, and the call will be automatically ended
@kicked-out="handleKickedOut"
No
-
@status-changed
The event thrown by the component will be triggered when the call status changes, see note below for details of the call status
@status-changed="handleStatusChanged"
No
-
Remarks on parameters:
1. The screen display mode videoDisplayMode has three values:VideoDisplayMode.CONTAINVideoDisplayMode.COVERVideoDisplayMode.FILL,default is VideoDisplayMode.COVER.
VideoDisplayMode.CONTAIN Prioritize to ensure that the video content is displayed in its entirety. Scale the video size isometrically until one side of the video window is aligned with the viewport border. If the video size does not match the size of the display window, the video will be scaled to fill the window while maintaining the aspect ratio, and the scaled video will have a black border around it.
VideoDisplayMode.COVER Prioritize to ensure that the viewport is filled. The video is scaled equally in size until the entire viewport is filled with video. If the video is different in length and width from the display window, the video stream will fill the window with a peripheral crop or image stretch in the same proportion as the display window.
VideoDisplayMode.FILL Ensures that the viewport is filled and the video content is displayed in its entirety, but does not guarantee that the video size remains proportional. The width and height of the video will be stretched to match the size of the viewport.
2. videoResolution has three values:VideoResolution.RESOLUTION_480PVideoResolution.RESOLUTION_720PRESOLUTION_1080P.FILL,default is VideoResolution.RESOLUTION_480P.
video Profile
resolution(width × height)
Frame Rate(fps)
Code Rate(kbps)
480p
640 × 480
15
900
720p
1280 × 720
15
1500
1080p
1920 × 1080
15
2000
Firefox:No support for custom video frame rates(default is 30fps)。
iOS 13 and 14 do not support encoding videos higher than 720P. It is recommended to limit the maximum capture resolution to 720P on these two system versions. Please refer to the known issue case 12 in iOS Safari for more information.
The actual values of video resolution, frame rate and bit rate may not always match the set values due to system performance, camera capture capability and browser limitations, in which case the browser will automatically adjust the Profile to match the set values as closely as possible.
3. @status-changed The state inside the call component can be thrown, handleStatusChanged({ oldStatus, newStatus }) receive the new state and the old state, the use of reference to the following sample code, where the state has the following kinds of:
import { STATUS } from "@tencentcloud/call-uikit-vue";
Constants
Physical meaning
STATUS.IDLE
Idle status
STATUS.BE_INVITED
Receive a call invitation
STATUS.DIALING_C2C
Calling one-to-one
STATUS.DIALING_GROUP
Group call in progress
STATUS.CALLING_C2C_AUDIO
Ongoing one-to-one audio calls
STATUS.CALLING_C2C_VIDEO
Ongoing one-to-one video calls
STATUS.CALLING_GROUP_AUDIO
Group audio call in progress
STATUS.CALLING_GROUP_VIDEO
Group video call in progress

Sample Code

<templeate/> Label content
<script/> Label content
<TUICallKit
:allowedMinimized="true"
:allowedFullScreen="true"
:videoDisplayMode="VideoDisplayMode.CONTAIN"
:videoResolution="VideoResolution.RESOLUTION_1080P"
:beforeCalling="beforeCalling"
:afterCalling="afterCalling"
:onMinimized="onMinimized"
:kickedOut="handleKickedOut"
:statusChanged="handleStatusChanged"
/>
<TUICallKitMini />
import { TUICallKit, TUICallKitMini, TUICallKitServer, VideoDisplayMode, VideoResolution, STATUS } from "@tencentcloud/call-uikit-vue";

function beforeCalling(type, error) {
console.log(type, error);
}
function afterCalling() {
// do something
}
function onMinimized(oldStatus, newStatus) {
if (newStatus === true) {
console.log("TUICallKit enter minimized state");
} else {
console.log("TUICallKit exit minimized state");
}
}
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] state change: ${oldStatus} -> ${newStatus}`);
}
}

TUICallKitServer API details

import TUICallKitServer

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

init

This API is used to initialize TUICallKit. It must be called before call and groupCall.
try {
await TUICallKitServer.init({ SDKAppID, userID, userSig });
// await TUICallKitServer.init({ tim, SDKAppID, userID, userSig});
alert("init finished");
} catch (error: any) {
alert(`init failed, reason is:${error}`);
}
The parameters are described below:
Parameter
Type
Required
Description
SDKAppID
Number
Yes
The SDKAppID of the IM application.
userID
String
Yes
The ID of the current user, which is a string that can contain only letters (a-z and A-Z), numbers (0-9), hyphens (-), and underscores (_).
userSig
String
Yes
Tencent Cloud's proprietary security signature. For how to obtain it, see UserSig.
TIM instance
Any
No
If you already have TIM instances, you can use this parameter to guarantee the uniqueness of a TIM instance.

call

This API is used to make a one-to-one call.
import { TUICallKitServer } from "./components/TUICallKit/Web";
TUICallKitServer.call({
userID: 'jack',
type: 1,
});
The parameters are described below:
Parameter
Type
Required
Description
userID
String
Yes
The ID of the user to call.
type
Number
Yes
The call type. 1: Audio call; 2: Video call.
timeout
Number
No
The timeout period (seconds). 0 indicates the call will not time out. The default value is 30.
offlinePushInfo
Object
No
The custom offline push message. This is valid only if your tsignaling version is 0.8.0 or later.
offlinePushInfo
Parameter
Type
Required
Description
offlinePushInfo.title
String
No
The message title.
offlinePushInfo.description
String
No
The message content.
offlinePushInfo.androidOPPOChannelID
String
No
The channel ID for the offline push message on OPPO phones in v8.0 or later.
offlinePushInfo.extension
String
No
The pass-through content. This is valid only if your tsignaling version is 0.9.0 or later.

groupCall

This API is used to make a group call.
import { TUICallKitServer } from "./components/TUICallKit/Web";
TUICallKitServer.groupCall({
userIDList: ['jack', 'tom'],
groupID: 'xxx',
type: 1,
});
The parameters are described below:
Parameter
Type
Required
Description
userIDList
Array
Yes
The IDs of the users to call.
type
Number
Yes
The call type. 1: Audio call; 2: Video call.
groupID
String
Yes
The group ID.
timeout
Number
No
The timeout period (seconds). 0 indicates the call will not time out. The default value is 30.
offlinePushInfo
Object
No
The custom offline push message. This is valid only if your tsignaling version is 0.8.0 or later.
For the parameters of offlinePushInfo, see above.

setLanguage

Set language。
TUICallKitServer.setLanguage("zh-cn"); // "en" | "zh-cn"
The parameters are described below:
Parameter
Type
Required
Description
lang
String
Yes
language: en or zh-cn

setSelfInfo

Note:
≥v2.2.0 Support
Set the user nickname and avatar.
try {
await TUICallKitServer.setSelfInfo({ nickName: "xxx", avatar: "http://xxx" });
} catch (error: any) {
alert(`Description Failed to update the user name nickname profile picture:${error}`);
}
The parameters are as shown in the table.
Parameters
Type
Required
Meaning
nickName
String
Yes
User nickname
avatar
String
Yes
User avatar URL

setCallingBell

Note:
≥v3.0.0 Support
Set custom ringtone for incoming calls.
Only local file addresses are allowed here, and make sure the file directory is accessible by the application.
The ringtone file passed in must be in MP3 format.
To restore the default ringtone, pass an empty value for the filePath parameter.
The ringtone media file must be placed in the public directory for the passed-in creation.
try {
await TUICallKitServer.setCallingBell(filePath?: string)
} catch (error: any) {
alert(`Failed to modify the ringtone :${error}`);
}

destroyed

This API is used to terminate TUICallKit.
import { TUICallKitServer } from "./components/TUICallKit/Web";
TUICallKitServer.destroyed();