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.CONTAIN、VideoDisplayMode.COVER、VideoDisplayMode.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_480P、VideoResolution.RESOLUTION_720P、RESOLUTION_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
<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
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 | |
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();