文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>实时音视频>视频通话（含 UI）>快速接入>uni-app (uts 插件)

uni-app (uts 插件)

最近更新时间：2025-11-13 15:08:01

我的收藏

本页目录：

本文档将指导您在 uni-app 项目中快速集成 TUICallKit UTS 插件，实现功能完备的视频 / 语音通话功能。
自 2025 年 5 月 1 日起，由于uni-app官方限制，CallKit 原生语言插件已终止迭代​​：
为保障业务持续稳定运行，现提供以下方案：
新用户接入: 推荐直接集成 CallKit UTS 插件。
存量用户使用：可继续使用CallKit 原生语言插件，但如需新功能，建议迁移到 CallKit UTS 插件。
​​CallKit UTS 插件核心优势：​​
支持自定义 UI、深度界面定制。
支持 uni-app 及 uni-app x 项目。
提供插件版本锁定功能，避免因更新导致兼容性问题。


准备工作

环境要求

HBuilderX：HBuilderX 4.64 和 4.65 版本对 UTS 插件打包存在已知兼容性问题，建议使用 4.66 或更高版本。
iOS 系统 ≥ 9.0，需使用支持音视频通话的真机设备进行调试。
Android 系统 ≥ 5.0(API Level 21)，需支持音视频通话的真机设备，并 允许 USB 调试。

开通服务

您需要开通腾讯云服务，以获取应用所需的唯一身份标识和密钥。 请参考 开通服务 文档，获取 SDKAppID 和 SecretKey，这些参数将在后续的步骤中作为必填参数使用。

快速接入

创建项目

若您已经有自己的项目，可忽略此步骤。
打开 HBuilderX 开发工具，点击新建 uni-app 项目，填入项目名称，选择默认模板以及 Vue 版本并创建项目。


导入组件

打开 【官方】腾讯云音视频通话插件 TencentCloud-Call ，单击下载插件并导入HBuilderX，选择需要集成的项目并单击确定。


工程配置

1. 注册通话页面： 在项目的 pages.json 文件中注册通话页面的路径和样式，确保 CallKit 界面能够正常跳转和展示。
{
    "path": "uni_modules/TencentCloud-Call/callkit/callPage",
    "style": {
      "navigationBarTitleText": "",
      "navigationStyle": "custom"
    }
}
2. 单击下载 debug 文件夹，将 debug 目录复制到您项目的根目录下
完成上述步骤后，您的项目工程结构如下：


登录

插件导入完成后，您需要完成登录。登录是使用 CallKit 所有功能的前提，请确保参数配置正确。
1. 全局注册实例： 在应用入口文件 main.js 中，引入 TUICallKit 和 TUIStore ，将其注册到全局变量 uni 上，确保 App 内所有组件共享一个实例。
import { TUICallKit } from "@/uni_modules/TencentCloud-Call/callkit/callServices/services/index";

import { TUIStore } from "@/uni_modules/TencentCloud-Call/callkit/callServices/TUIStore/index";

uni.$TUICallKit = TUICallKit;
uni.$TUIStore = TUIStore;

2. 调用登录接口： 在您需要使用通话功能的页面（例如 pages/index/index.vue），调用 uni.$TUICallKit.login 方法进行登录。
// 引入本地生成 UserSig 的工具（仅供开发调试）
import { genTestUserSig } from '../../debug/GenerateTestUserSig.js';

// 生成用户签名
const { userSig, SDKAppID } = genTestUserSig('denny');

// 登录 
uni.$TUICallKit.login({
    SDKAppID: 123456,  // 替换为您的 SDKAppID
    userID: 'denny',   // 替换为您的用户 ID
    userSig: 'xxx',    // 替换为您生成的 userSig
    success: () => {  
      console.log(`login success`);
    },
    fail: (errCode, errMsg) => {   
      console.error(`login failed, errCode: ${errCode}, errMsg: ${errMsg}`)
    },
})
参数
类型
说明
userID
string
用户的唯一标识符，由您定义，只允许包含大小写英文字母(a-z A-Z)、数字(0-9)及下划线和连词符。
SDKAppID
number
在 Tencent RTC 控制台 创建的音视频应用的唯一标识。
SecretKey
string
在 Tencent RTC 控制台 创建的音视频应用的 SecretKey。
userSig
string
一种安全保护签名，用于对用户进行登录鉴权认证，确认用户是否真实，阻止恶意攻击者盗用您的云服务使用权。
userSig 说明：
开发环境：如果您正在本地跑通 Demo、开发调试，可以采用 debug 文件中的 genTestUserSig 函数生成 userSig。该方法中 SecretKey 很容易被反编译逆向破解，一旦您的密钥泄露，攻击者就可以盗用您的腾讯云流量。
生产环境：强烈建议采用 服务端生成 UserSig 的方式，以避免 SecretKey 泄露导致的安全风险。

设置头像和昵称 (可选)

TUICallKit 支持设置用户的昵称和头像，用于在通话界面展示用户的个性化信息，如果不调用该接口，通话界面将默认显示 userID 及系统默认头像。
uni.$TUICallKit.setSelfInfo({
    nickName: 'Jack',
    avatar:  "http://xxx",
})
参数
类型
说明
nickName
String
目标用户的昵称。
avatar
String
目标用户的头像。

发起通话

登录成功后，即可调用 uni.$TUICallKit.calls 方法向其他用户发起通话。
uni.$TUICallKit.calls({
    userIDList: ['jenny', 'Mike'], // 目标用户 ID 列表，可包含一个或多个用户
    mediaType: 1,            // 媒体类型：1: 语音通话 2: 视频通话，
})
参数
类型
说明
userIdList
List<String>
目标用户的 userId 列表。
mediaType
通话的媒体类型，例如视频通话、语音通话。

接听通话

CallKit 插件实现了完整的接听界面和来电提醒逻辑。当其他用户向当前登录的 userID 发起呼叫时，CallKit 会自动弹出通话界面，无需编写额外的接听逻辑。
如果应用处于后台或离线状态，需要额外的离线唤醒配置，请参考离线唤醒 文档。

运行项目

完成上述步骤后，您已经基于 CallKit UTS 插件，完成了一个完整的音视频通话项目。由于此插件依赖原生的音视频能力，为了确保所有功能可以正常调用和调试，您需要采用传统打包方式，来制作和运行一个自定义调试基座。
1. 制作自定义调试基座，请选择传统打包方式进行打包。

2. 自定义调试基座成功后，使用自定义基座运行项目。

3. 运行项目后，在“发起通话”和“收到通话请求”时，可以看到如下显示效果。
主叫方发起音频通话
被叫方收到音频通话请求







更多功能 (可选)

开启悬浮窗

用户在通话过程中需要切换到应用内其他页面进行多任务操作时，您可开启悬浮窗功能。

1. 调用 enableFloatWindow 方法显示悬浮窗的点击按钮（默认为 false，不显示悬浮窗按钮）。
uni.$TUICallKit.enableFloatWindow(true);
说明：默认为false，通话界面左上角的悬浮窗按钮隐藏，设置为 true 后显示
2. 调用 startFloatWindow/stopFloatWindow 方法开启/关闭悬浮窗。
import { CallEngine } from "@/uni_modules/TencentCloud-Call";
const callEngine = new CallEngine();

// 开启悬浮窗
callEngine.startFloatWindow({
  success: () => {
    console.log(`startFloatWindow success`);
  }
  fail: (errCode, errMsg) => {
    console.log(`startFloatWindow failed, errCode: ${errCode}, errMsg: ${errMsg}`);
   },
  });

// 关闭悬浮窗
callEngine.stopFloatWindow(）

多人通话

主叫方使用 calls 方法发起通话时，若被叫用户列表超过一人，则自动视为多人通话。其他成员可通过 join 方法加入该多人通话。
发起多人通话：使用 calls 方法发起通话时，若被叫用户列表（userIDList）超过一人，则自动视为群组通话。
import { CallEngine } from "@/uni_modules/TencentCloud-Call";

const callEngine = new CallEngine();
const options = {
  userIDList: ['mike', 'tom'],
  callMediaType: 1, // voice call(callMediaType = 1)、video call(callMediaType = 2)
};
callEngine.calls(options);
加入多人通话：可使用 join 方法加入指定的群组通话。
import { CallEngine } from "@/uni_modules/TencentCloud-Call";

const callEngine = new CallEngine();
const options = {
    callId: '1234',
};
callEngine.join(options);

铃声设置

1. 自定义来电铃声：如果您希望替换默认的来电铃声，可以使用以下方法（仅支持传入本地文件地址，需确保文件目录可被应用访问）。
const tempFilePath = './static/rain.mp3'; // Locally stored audio files
let musicFilePath = '';

uni.saveFile({
  tempFilePath: tempFilePath,
  success: (res) => {
    console.warn('保存文件成功 = ', JSON.stringify(res));
    musicFilePath =  res.savedFilePath;
    musicFilePath = plus.io.convertLocalFileSystemURL(musicFilePath);
    
    // Set ringtone
    uni.$TUICallKit.setCallingBell(musicFilePath, (res) => {
      if (res.code === 0) {
        console.log('setCallingBell success');
      } else {
        console.log(`setCallingBell failed, error message = ${res.msg}`);
      }
    });
  }
});
参数
类型
说明
filePath
String
铃声文件的路径
2. 静音模式：如果您希望关闭来电铃声，可以使用以下方法（默认为 false，开启来电铃声）。
uni.$TUICallKit.enableMuteMode(true);

常见问题

登录失败如何排查：检查 SDKAppID、userID、userSig 是否正确，特别是 userSig 是否已过期或参数错误。生产环境建议使用服务端生成的 UserSig。
iOS/Android 运行报错：确保 HBuilderX 版本大于4.45，并在制作了自定义调试基座之后，再运行项目。

交流与反馈

如果您在使用过程中，有什么建议或者意见，可以联系我们，感谢您的反馈。
中国站
目录