本文将介绍如何快速接入 TUICallKit 组件。您可以在 10 分钟内完成以下关键步骤，最终获得一个功能完备的音视频通话界面。
语音通话 | 视频通话 |
 |  |
准备工作
环境要求
微信 App iOS 最低版本要求：8.0.40。
微信 App Android 最低版本要求：8.0.40。
小程序基础库最低版本要求：2.10.0。
注意：
由于小程序测试号不具备 <live-pusher> 和 <live-player> 的使用权限，请使用企业小程序账号申请相关权限进行开发。
由于微信开发者工具不支持原生组件（即 <live-pusher> 和 <live-player> 标签），需要在真机上进行运行体验。
不支持企业微信小程序。
开通服务
开通企业类小程序
在小程序控制台开启实时音视频接口
小程序推拉流标签使用权限暂时只开放给有限类目，具体支持类目参见该地址。
符合类目要求的小程序，需要在 微信公众平台 > 开发 > 开发管理 > 接口设置中自助开通该组件权限。
登录小程序控制台更新隐私保护政策，勾选麦克风、摄像头。
在小程序控制台配置域名
将以下域名添加到 socket 合法域名：
域名 | 说明 | 是否必须 |
wss://${SDKAppID}w4c.my-imcloud.com | v3.4.6起，SDK 支持独立域名，可更好地保障服务稳定性。 例如您的 SDKAppID 是 1400xxxxxx，则独立域名为： wss://1400xxxxxxw4c.my-imcloud.com | 必须 |
wss://wss.im.qcloud.com | Web IM 业务域名 | 必须 |
wss://wss.tim.qq.com | Web IM 业务域名 | 必须 |
wss://wssv6.im.qcloud.com | Web IM 业务域名 | 必须 |
将以下域名添加到 request 合法域名：
域名 | 说明 | 是否必须 |
https://web.sdk.qcloud.com | Web IM 业务域名 | 必须 |
https://boce-cdn.my-imcloud.com | Web IM 业务域名 | 必须 |
https://api.im.qcloud.com | Web IM 业务域名 | 必须 |
https://events.im.qcloud.com | Web IM 业务域名 | 必须 |
https://webim.tim.qq.com | Web IM 业务域名 | 必须 |
https://wss.im.qcloud.com | Web IM 业务域名 | 必须 |
https://wss.tim.qq.com | Web IM 业务域名 | 必须 |
将以下域名添加到 uploadFile 合法域名：
域名 | 说明 | 是否必须 |
https://${SDKAppID}-cn.rich.my-imcloud.com | 从 2024年9月10日起，新增应用默认分配 COS 独立域名。 例如您的 SDKAppID 是 1400xxxxxx，则 COS 独立域名为： https://1400xxxxxx-cn.rich.my-imcloud.com | 必须 |
https://cn.rich.my-imcloud.com | 文件上传域名 | 必须 |
https://cn.imrich.qcloud.com | 文件上传域名 | 必须 |
https://cos.ap-shanghai.myqcloud.com | 文件上传域名 | 必须 |
https://cos.ap-shanghai.tencentcos.cn | 文件上传域名 | 必须 |
https://cos.ap-guangzhou.myqcloud.com | 文件上传域名 | 必须 |
将以下域名添加到 downloadFile 合法域名：
域名 | 说明 | 是否必须 |
https://${SDKAppID}-cn.rich.my-imcloud.com | 从 2024年9月10日起，新增应用默认分配 COS 独立域名。 例如您的 SDKAppID 是 1400xxxxxx，则 COS 独立域名为： https://1400xxxxxx-cn.rich.my-imcloud.com | 必须 |
https://cn.rich.my-imcloud.com | 文件下载域名 | 必须 |
https://cn.imrich.qcloud.com | 文件下载域名 | 必须 |
https://cos.ap-shanghai.myqcloud.com | 文件下载域名 | 必须 |
https://cos.ap-shanghai.tencentcos.cn | 文件下载域名 | 必须 |
https://cos.ap-guangzhou.myqcloud.com | 文件下载域名 | 必须 |
快速接入
步骤1：创建小程序项目（可选）
注意：
TUICallKit 组件支持 HBuilderX 和 CLI 脚手架两种集成方式。
1. 在 HBuilder 中创建小程序项目。
2. 在终端输入
npm init -y，创建 package.json 文件。npm init -y
1. 全局安装 vue-cli：
npm install -g @vue/cli
2. 通过 CLI 创建项目：
npx degit dcloudio/uni-preset-vue#vite chat-example
npx degit dcloudio/uni-preset-vue#vite-ts chat-example
推荐选择 TypeScript 模板创建项目。
vue create -p dcloudio/uni-preset-vue chat-example
3. 创建完成后，切换到项目所在目录：
cd chat-example
步骤2：下载 TUICallKit 组件
1. 下载组件。
npm i @trtc/calls-uikit-wx-uniapp
npm i @trtc/calls-uikit-wx-uniapp unplugin-vue2-script-setup @vue/composition-api
2. 拷贝源码。
mkdir -p ./TUICallKit && cp -r node_modules/@trtc/calls-uikit-wx-uniapp/TUICallKit/* ./TUICallKit/
xcopy node_modules\\@trtc\\calls-uikit-wx-uniapp\\TUICallKit .\\TUICallKit /i /e
mkdir -p ./TUICallKit && cp -r node_modules/@trtc/calls-uikit-wx-uniapp/TUICallKit/* ./src/TUICallKit
xcopy node_modules\\@trtc\\calls-uikit-wx-uniapp\\TUICallKit .\\src\\TUICallKit /i /e
步骤3：工程配置
1. 配置页面路由
在
pages.json 文件注册全局监听页面。在原有代码中追加如下配置。{"path": "TUICallKit/components/CallView/CallView","style": {"navigationBarTitleText": "uni-app"}},{"path": "TUICallKit/plugin/groupCall/components/GroupCallView","style": {"navigationBarTitleText": "uni-app"}}
2. 修改 vue.config.js 文件（Vue3 项目请忽略）
修改 vue.config.js 文件，进行
unplugin-vue2-script-setup 插件的使用，若没有 vue.config.js 文件请新建。const ScriptSetup = require('unplugin-vue2-script-setup/webpack').default;module.exports = {parallel: false,configureWebpack: {plugins: [ScriptSetup({}),],resolve: {// Prevent webpack from following pnpm symlinks to their real .pnpm store// paths. UniApp's compiler uses the resolved path to generate component// references in the output JSON. Without this, it produces unresolvable// paths like `node-modules/.pnpm/@tencentcloud+trtc-component-uniapp@.../...`.symlinks: false,},},chainWebpack(config) {config.plugins.delete('fork-ts-checker');},};
3. 修改 main.js 文件（Vue3 项目请忽略）
修改 main.js 文件，进行
@vue/composition-api 插件的使用。import vueComposition from "@vue/composition-api"Vue.use(vueComposition)
步骤4：登录组件
说明：
如果您的应用要求用户启动后必须立即登录，建议将登录初始化代码放置在应用入口组件（例如 App.vue）的 onLaunch 生命周期钩子中。
如果您的应用有一个明确的登录按钮，则这段代码应作为该按钮的 onClick 或 @click 事件的处理函数。
import { useLoginState } from '../../TUICallKit/states/LoginState';const { login } = useLoginState();const loginHandler = async () => {const userID = 'denny'; // 请替换为您的 UserIDconst SDKAppID = 1400000001; // 请替换为开通服务控制台的 SDKAppIDawait login({userId: userID,userSig: 'xxxxxxxxxxx', // 您可以在控制台中计算一个 UserSig 并填在这个位置sdkAppId: SDKAppID,});wx.$globalCallPagePath = 'TUICallKit/components/CallView/CallView'; // 配置全局监听页面路径};
登录接口参数说明
参数 | 类型 | 说明 |
SDKAppID | Number | |
userID | String | 当前用户的唯一 ID，仅包含英文字母、数字、连字符和下划线。 |
userSig | String | 用于腾讯云鉴权的票据。请注意： 开发环境：您可以采用本地 GenerateTestUserSig.genTestSig 函数生成 UserSig 或者通过 UserSig 辅助工具 生成临时的 UserSig。生产环境：为了防止密钥泄露，请务必采用服务端生成 UserSig 的方式。详细信息请参见 服务端生成 UserSig。 |
步骤5：发起通话
拨打方可以通过调用 calls 函数，并指定通话类型和被叫方的 userID，来发起语音或视频通话。
calls 接口同时支持一对一通话和多人通话。当 userIDList 中包含一个 userID 时，为一对一通话；当 userIDList 包含多个 userID 时，则为多人通话。import { useCallListState } from '../../TUICallKit/states/CallListState';const { calls } = useCallListState();const callHandler = async () => {await calls({userIDList: ['mike'], // 请输入被呼叫用户的 userID（需确保该用户已完成一次登录），当前仅支持一对一通话type: 2, // 通话类型：1: 语音通话 2: 视频通话});};
步骤6：接听通话
接听端完成登录后，拨打端发起通话，接收端就可以收到通话邀请，同时伴随铃声。
1. 以编译开发模式的微信小程序为例（编译至其他平台请参考 package.json 文件中 scripts 脚本配置）：
npm run build:mp-weixin
2. 编译成功后，启动微信开发者工具导入到
dist/build/mp-weixin 目录。注意：
第一次使用小程序通话，需要获取摄像头和麦克风权限。
更多功能
设置昵称和头像
try {await TUICallKitAPI.setSelfInfo({nickName: "jack",avatar: "http://xxx",});} catch (error: any) {alert(`[TUICallKit] Failed to call the setSelfInfo API. Reason: ${error}`);}
注意：
因为用户隐私限制，非好友之间的通话，被叫的昵称和头像更新可能会有延迟，一次通话成功后就会顺利更新。
铃声设置
您可通过以下方式设置默认铃声、来电静音模式。
设置默认铃声：通过 setCallingBell 接口设置被叫端收到的来电铃声。
注意：
传入本地铃声文件应为相对当前小程序项目的绝对路径。
try {await TUICallKitAPI.setCallingBell('/static/ring.mp3'); // 相对当前小程序项目的绝对路径} catch (error: any) {alert(`[TUICallKit] setCallingBell API failed. Reason: ${error}`);}
来电静音模式：您可以通过 enableMuteMode 设置静音模式。
try {await TUICallKitAPI.enableMuteMode(enable: boolean);} catch (error: any) {alert(`[TUICallKit] enableMuteMode API failed. Reason: ${error}`);}
组件体积速查与插件裁剪指南
TUICallkit 组件接入后以下的功能模块是全量集成的，您可以按需进行裁剪。功能模块 | 自身大小 | 备注 |
核心通话引擎（必选） | 375 KB | |
1v1 单人通话功能（必选） | 111 KB | - |
铃声插件（可裁剪） | 23 KB | 移除铃声插件方式： 删除项目中的这行注册代码(在项目中搜索如下代码即可)： this.registerPlugin(useRingPlugin()) |
多人通话插件（可裁剪） | 27 KB | 移除多人通话插件方式： 删除注册代码(在项目中搜索如下代码即可)： this.registerPlugin(useGroupCallPlugin());在 pages.json 中删除多人通话页面注册（path 含 GroupCallView 的项）。 |
自定义您的 UI
替换图标按钮
您可以直接修改
TUICallKit/Components/assets 文件夹下的图标组件，以确保整个应用中的图标色调风格保持一致，请在替换时保持图标文件的名字不变。注意：
v3.2.2+ 支持。
序号 | 资源路径 |
1 | /TUICallKit/Components/assets/button/mobile/minimize.svg |
2 | /TUICallKit/Components/assets/button/hangup.svg |
3 | /TUICallKit/Components/assets/button/accept.svg |
4 | /TUICallKit/Components/assets/button/microphone-open.svg |
5 | /TUICallKit/Components/assets/button/speaker-open.svg |
6 | /TUICallKit/Components/assets/button/camera-close.svg |
7 | /TUICallKit/Components/assets/button/switchCamera.svg |
隐藏按钮
注意：
v3.2.9+ 支持。
以隐藏摄像头按钮为例。
// 替换成 TUICallKit 源码中的地址import { TUICallKitAPI, FeatureButton } from "../../TUICallKit/index";TUICallKitAPI.hideFeatureButton(FeatureButton.Camera);
自定义通话背景图
通话背景图会在语音通话或者视频通话关闭摄像头后出现，通过调用 setLocalViewBackgroundImage 修改本地用户通话界面背景图，setRemoteViewBackgroundImage 修改远端用户通话界面背景图。
注意：
v3.2.9+ 支持。
import { TUICallKitAPI } from "../../TUICallKit/index";TUICallKitAPI.setLocalViewBackgroundImage('http://xxx.png');TUICallKitAPI.setRemoteViewBackgroundImage('remoteUserId', 'http://xxx.png');
常见问题
Vue2 iOS 小程序播放铃声没有声音？
Vue2 的铃声播放只支持线上地址，可以在
TUICallKit/plugin/ring/index.ts 中，将本地的相对路径地址改为您的铃声线上地址。Vue2 & Vue3 缺少 sass 预处理器报错：Preprocessor dependency "sass" not found. Did you install it?
请按照以下步骤操作：
npm install sass --save-dev
Vue2 & Vue3 装饰器报错： Transforming JavaScript decorators to the configured target environment is not supported yet
可在 tsconfig.json 中添加相关配置，示例：
{"compilerOptions": {"experimentalDecorators": true}}
Vue2 项目报错 TS 编译器类型检查错误
main.js 中引入组合式 API。import VueCompositionAPI from "@vue/composition-api";Vue.use(VueCompositionAPI);
安装
unplugin-vue2-script-setup 依赖。npm i unplugin-vue2-script-setup
新建或修改项目根目录的
vue.config.js 文件。const ScriptSetup = require('unplugin-vue2-script-setup/webpack').default;module.exports = {parallel: false,configureWebpack: {plugins: [ScriptSetup({}),],},chainWebpack(config) {config.plugins.delete('fork-ts-checker'); // disable type check and let `vue-tsc` handles it},};
如何适配通过 CLI 创建 Vue2 的 JS 项目？
按照本文的步骤集成后，需要在项目的根目录下执行：
vue add typescript
按照如下配置项进行选择（为了保证能同时支持原有 js 代码 与 TUICallKit 中 ts 代码，请您务必严格按照以下五个选项进行配置），安装完成后检查
App.vue 文件代码并重新编译。
