即时通信 IM uni-app（客户端）（快速接入）

注意：说明：

注意：自 2025 年 5 月 1 日起，由于 uni-app 限制，CallKit 原生语言插件已终止迭代，为保障业务持续稳定运行，现提供 CallKit UTS 插件方案。

注意：CallKit UTS 插件核心优势：

一、环境要求

注意：说明：

注意：HBuilderX 4.64 和 4.65 版本对 UTS 插件打包存在已知兼容性问题，建议使用 4.66 或更高版本。

·HBuilderX：HBuilderX 是 uni-app 的集成开发环境（IDE），我们需要用它来导入、配置和运行我们的 Demo。

·2个移动设备： Android 5.0 以上的设备 / iOS 13.0 及以上设备。

二、开通服务

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

三、步骤 1：下载 TUICallKit 源码

Vue3Vue2uni-app x 项目

1. 克隆项目源码。

git clone https://github.com/Tencent-RTC/TUIKit_uni-app.git

2. 导入 atomic-x 组件。

·将源码中 TUIKit_uni-app/App/uni_modules 目录下的 tuikit-atomic-x 文件夹，完整拷贝到你项目根目录下的 uni_modules 文件夹中。

·将源码中 TUIKit_uni-app/App/components 下的文件，完整地拷贝到你项目的 components 文件夹中。

·将源码中 TUIKit_uni-app/App/static 目录下的文件，完整拷贝到你项目根目录下的同名文件夹下。

·将源码中 TUIKit_uni-app/App/debug 文件夹拷贝到你项目的根目录下，这个目录提供可以方便你在客户端快速生成的 UserSig 的快捷函数。

3. 合并 App.vue 配置。

TUIKit_uni-app/App/App.vue 文件中包含通话能力的初始化逻辑，因此你需要将 TUIKit_uni-app/App/App.vue 文件和你项目下的 App.vue 文件进行合并。

注意：不要直接覆盖 App.vue 文件！ 打开源码中的 TUIKit_uni-app/App/App.vue， 将其 <script> 部分的 ts 内容追加到你自己项目的 App.vue 的 <script> 标签内。

1. 安装 TUIKit 插件。进入【】腾讯云聊天+通话+直播响应式 SDK。点击【下载插件并导入 HBuilderX】，将插件导入你的项目中。2. 导入 atomic-x 组件。2.1 转化兼容模式：仅 Vue2 项目，Vue3 项目可忽略。说明：该脚本用于将插件源码中 Vue3 的 Composition API 写法自动转换为 Vue2 的 Options API 写法，以确保在 Vue2 项目中正常运行。node ./uni_modules/tuikit-atomic-x/scripts/switch-to-compatible-mode.js2.2 拷贝静态资源：将 ⁠uni_modules/tuikit-atomic-x/quickstart/ ⁠下的 ⁠⁠static/*⁠ 拷贝到项目 static 目录下。Mac 端Windows 端cp -r uni_modules/tuikit-atomic-x/quickstart/static/* static/xcopy /E /I /Y "uni_modules\\tuikit-atomic-x\\quickstart\\static\\*" "static\\"3. 合并 App.vue 配置。通话能力的初始化需要在应用唤醒的时候进行，因此需要你将以下代码和你项目中的 App.vue 中的逻辑进行合并处理。import { initCallService } from '@/uni_modules/tuikit-atomic-x/server/callService'; export default { onLaunch: function() { initCallService() console.log('App Launch') }, onShow: function() { console.log('App Show') }, onHide: function() { console.log('App Hide') }}

1. 安装 TUIKit 插件。进入【】腾讯云聊天+通话+直播响应式 SDK。点击【下载插件并导入 HBuilderX】，将插件导入你的项目中。2. 导入 atomic-x 组件。2.1 转换 uniappx 模式：仅 uni-app x 项目，uni-app 项目可忽略。说明：该脚本用于将插件中 nvue 组件转化为 uvue 组件。 node ./uni_modules/tuikit-atomic-x/scripts/switch-to-uniappx-mode.js2.2 拷贝 TUIKit 页面及静态资源：将 ⁠uni_modules/tuikit-atomic-x/quickstart/⁠ 下的 ⁠pages/*⁠ 拷贝到项目 page⁠目录，⁠static/*⁠ 拷贝到项目 static 目录下。Mac 端Windows 端cp -r uni_modules/tuikit-atomic-x/quickstart/static/* static/ && cp -r uni_modules/tuikit-atomic-x/quickstart/pages/* pages/xcopy /E /I /Y "uni_modules\\tuikit-atomic-x\\quickstart\\static\\*" "static\\" && xcopy /E /I /Y "uni_modules\\tuikit-atomic-x\\quickstart\\pages\\*" "pages\\"

四、步骤 2：工程配置

uni-app 项目uni-app x 项目

1. 配置 manifest.json。

打开你项目的 manifest.json 文件，在 app-plus > distribute 节点下，确保添加了以下必要的权限：

·Android 平台（Android 节点）：在 permissions 数组中，请确保包含以下权限：

"<uses-permission android:name=\\"android.permission.CAMERA\\"/>","<uses-permission android:name=\\"android.permission.RECORD_AUDIO\\" />","<uses-permission android:name=\\"android.permission.INTERNET\\"/>","<uses-permission android:name=\\"android.permission.ACCESS_NETWORK_STATE\\"/>","<uses-permission android:name=\\"android.permission.WRITE_EXTERNAL_STORAGE\\"/>","<uses-permission android:name=\\"android.permission.SYSTEM_ALERT_WINDOW\\"/>","<uses-permission android:name=\\"android.permission.VIBRATE\\"/>"

·iOS 平台（iOS 节点）：在 privacyDescription 对象中，请确保包含以下描述：

"NSCameraUsageDescription" : "应用需要访问你的相机以进行通话","NSMicrophoneUsageDescription" : "应用需要访问你的麦克风以进行通话"

在 UIBackgroundModes 数组中，添加 audio 以支持后台播放音频。

"UIBackgroundModes" : [ "audio" ]

2. 制作自定义基座。

注意：说明：

注意：由于 TUICallKit 包含原生代码（UTS 插件），你必须制作自定义调试基座才能在真机上运行。

2.1 在 HBuilderX 顶部菜单选择运行 > 运行到手机或模拟器 > 制作自定义调试基座。

2.2 制作成功后，再次选择运行 > 运行到手机或模拟器，在弹窗中勾选使用自定义调试基座后运行到你的手机。

具体操作指引参见 跑通 Demo 的步骤3。

配置 Android 相关权限。点击 manifest.json> 点击安卓 App 配置 > 权限配置中配置如下权限。如下：<uses-permission android:name="android.permission.RECORD_AUDIO" /><uses-permission android:name="android.permission.INTERNET" /><uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" /><uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW"/><uses-permission android:name="android.permission.VIBRATE"/>

五、步骤 3：完成登录

集成完成后，你需要完成登录。在你项目中需要使用到通话能力的地方进行登录，这是使用 TUICallKit 的关键步骤，因为只有在登录成功后才能正常使用 TUICallKit 的各项功能，故请你耐心检查相关参数是否配置正确：

Vue3Vue2uni-app x 项目import { onMounted } from 'vue';import { useLoginState } from "@/uni_modules/tuikit-atomic-x/state/LoginState";const { login } = useLoginState();onMounted(() => { login({ sdkAppID: 1400000001, // 请替换为开通服务控制台的 SDKAppID userID: "denny", // 请替换为你的 UserID userSig: "xxxxxxxxxxx", // 你可以在控制台中计算一个 UserSig 并填在这个位置 });});<script>import { useLoginState } from '@/uni_modules/tuikit-atomic-x/state/LoginState'export default { data() { var loginStore = useLoginState() return { loginStore: loginStore, userId: '', userSig: '' } }, methods: { handleLogin: function () { if (!this.userId || !this.userSig) return var self = this this.loginStore.login({ sdkAppID: 1400000001, // 你的 SDKAppID userID: this.userId, userSig: this.userSig, }) } }}</script>import { useLoginState } from '@/uni_modules/tuikit-atomic-x/state/LoginState';const { login } = useLoginState();const sdkAppId = 0; // SDKAppIDconst userId = ref(''); // userIDconst userSig = ''; // userSig// 登录login({ sdkAppID: sdkAppId, userID: userId.value, userSig: userSig, success: () => { }, fail: (code: number, msg: string) => { uni.showToast({ title: msg || '登录失败', icon: 'none' }) }})

登录接口参数说明

六、步骤 4：注册通话页面

现在，你需要在 pages.json 文件中告诉你的应用，这个新页面是存在的。

打开你项目根目录下的 pages.json 文件，在 "pages" 数组中，添加以下对象来注册通话页。

{ "pages": [ // … 你项目已有的其他页面配置 { "path": "uni_modules/tuikit-atomic-x/pages/call", "style": { "navigationBarTitleText": "", "disableSwipeBack": true, // 禁止右滑返回，防止直播中误操作退出 "app-plus": { "titleNView": false // 隐藏原生导航栏，使用页面内的自定义导航 } } } ] // … 其他配置}

七、步骤5：跳转通话页面

在你需要发起通话的地方（具体由你的业务决定，在其点击事件里执行），你需要先调用 calls 函数。在该函数成功执行的 success 回调中，再通过 uni.navigateTo 跳转到通话页面，以确保通话状态已正确建立。

Vue3Vue2uniapp-x 项目import { useCallState } from '@/uni_modules/tuikit-atomic-x/state/CallState';import { useDeviceState } from "@/uni_modules/tuikit-atomic-x/state/DeviceState";const { calls } = useCallState()const { openLocalCamera, openLocalMicrophone } = useDeviceState();// 示例：在一个按钮的点击事件中function startCall() { // 跳转到通话页 calls({ participantIds: ['xxx'], mediaType: 1, // 1 是视频通话, 0 是语音通话 success: () => { openLocalCamera({isFront: true}) openLocalMicrophone() uni.navigateTo({ url: '/uni_modules/tuikit-atomic-x/pages/call?layoutTemplate=Float' }) }, fail: (error) => { console.log('calls fail:', error) } });}<script>import { useCallState, CallMediaType } from '@/uni_modules/tuikit-atomic-x/state/CallState'import { useDeviceState } from '@/uni_modules/tuikit-atomic-x/state/DeviceState'export default { data() { var callStore = useCallState() var deviceStore = useDeviceState() return { callStore: callStore, deviceStore: deviceStore, // 要呼叫的用户 ID participantId: 'xxx' } }, methods: { startCall: function () { var self = this // 发起通话 this.callStore.calls({ participantIds: [this.participantId], // 被呼叫者用户 ID 数组 mediaType: CallMediaType.Video, // 1 是视频通话, 0 是语音通话 success: function () { console.log('发起通话成功') // 打开本地摄像头 self.deviceStore.openLocalCamera({ isFront: true, // 使用前置摄像头 success: function () { console.log('摄像头打开成功') }, fail: function (errCode, errMsg) { console.log('摄像头打开失败:', errMsg) } }) // 打开本地麦克风 self.deviceStore.openLocalMicrophone({ success: function () { console.log('麦克风打开成功') }, fail: function (errCode, errMsg) { console.log('麦克风打开失败:', errMsg) } }) // 跳转到通话页面 uni.navigateTo({ url: '/uni_modules/tuikit-atomic-x/pages/call?layoutTemplate=Float' }) }, fail: function (error) { console.log('发起通话失败:', error) } }) } }}</script><script setup lang="uts">import { ref } from 'vue'import { useCallState, MEDIA_TYPE_VIDEO, type CallsOptions } from '@/uni_modules/tuikit-atomic-x/state/CallState'import { useDeviceState } from '@/uni_modules/tuikit-atomic-x/state/DeviceState'const callState = useCallState()const deviceState = useDeviceState()const targetUserID = ref<string>('')const makeCall = (): void => { // 开启摄像头和麦克风 deviceState.openLocalCamera({ isFront: true }) deviceState.openLocalMicrophone(null) // 发起通话 const opts: CallsOptions = { participantIds: [targetUserID.value], mediaType: MEDIA_TYPE_VIDEO } callState.calls(opts)}</script>

注意：说明：

注意：在 tuikit-atomic-x/server/callService 文件中进行了默认处理被叫端收到呼叫的逻辑，若你需要自定义，可以修改该文件中的 "onCallReceived" 事件对应的处理逻辑。

八、调用接口没有反应？

请检查你是否制作了自定义基座并且使用自定义基座运行项目。

九、如何禁止系统侧滑返回上一个页面的行为？

iOS 端可以通过设置页面上的 disableSwipeBack 属性进行禁止。详情参考 uni-app 产品文档。

Android 端可以通过 onBackPress 拦截系统侧滑和物理返回，示例代码如下

注意：使用该方式进行系统侧滑和物理返回的拦截的前提是该页面使用的是 自定义导航栏。

<script setup> import { onBackPress } from '@dcloudio/uni-app' // 拦截系统侧滑和物理返回键，防止通话中误退出 onBackPress((option) => { if (option.from === 'backbutton') { return true; // 返回 true 阻止默认回退行为 } });</script>

十、交流与反馈

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