即时通信 IM Web（常见问题）

注意：说明：

注意：希望你能抽出几分钟时间，为你自己的需求投上一票，我们将优先开发！

注意：问卷地址：TUICallKit Web 问卷调查。

一、基础环境问题

注意：说明：

注意：以下问题对于 TUICallKit 与 TUICallEngine SDK 同样适用。

二、TUICallEngine 和 TUICallKit 分别是什么？

TUICallEngine SDK 是音视频通话组件的无 UI SDK，如果 TUICallKit 的交互并不满足你的需求，你可以使用这套接口自己封装交互。npm 地址为 @trtc/call-engine-lite-js。

三、如何关闭自动播放弹窗？

使用 TUICallKit 组件，通过如下方式关闭自动播放弹窗。

import { TUICallKitAPI } from '@trtc/calls-uikit-vue';const trtcCloudInstance = TUICallKitAPI?.getTUICallEngineInstance()?.getTRTCCloudInstance();const params = { api: 'enableAutoPlayDialog', params: { enable: 0 },};trtcCloudInstance?.callExperimentalAPI(JSON.stringify(params));

注意：建议：

注意：保留自动播放弹窗，但是需要调整弹窗样式，需要升级到最新的 TUICallKit 版本（V4.4.0+ 支持）。调整的弹窗组件路径：components/common/AutoPlayDialog 下的 vue 文件。

使用 TUICallEngine SDK，通过如下方式关闭自动播放弹窗。

import TUICallEngine from "@trtc/call-engine-lite-js";const tuiCallEngine = TUICallEngine.createInstance({ SDKAppID: 0 });const trtcCloudInstance = tuiCallEngine?.getTRTCCloudInstance();const params = { api: 'enableAutoPlayDialog', params: { enable: 0 },};trtcCloudInstance?.callExperimentalAPI(JSON.stringify(params));

四、Web 端支持哪些浏览器？报错“获取设备权限失败”？

请先确保页面已被授权使用麦克风或摄像头，参见 设备授权说明。

对浏览器的详细支持度，请参见 浏览器兼容信息。

对于上述没有列出的环境，你可以在需要检测的浏览器打开 能力测试 测试是否完整的支持 WebRTC 的功能。

五、为什么本地开发测试能正常使用，但是部署到线上用 IP 访问后无法正常视频/语音通话？

·对网站域名协议的要求

出于对用户安全、隐私等问题的考虑，浏览器限制网页在 HTTPS 协议下才能正常使用这篇档中所对接组件的全部功能。为确保生产环境中的用户能够顺畅体验产品功能，请将你的网站部署在 https:// 协议的域名下。更多请参见 页面访问协议说明。

·对网络环境的要求

在使用 TUICallKit 时，用户可能因防火墙限制导致无法正常进行音视频通话，请参考 应对防火墙策略 将相应端口及域名添加至防火墙白名单中。

六、在接通过程中报："is not included in the current tim's package"？

TUICallKit（含 TUICallEngine SDK）依赖的 tim-js-sdk 版本需要 ≥ 2.21.2。

如果 tim-js-sdk 依赖包版本正确，则可能是 SDKAppID 未购买音视频套餐或套餐包不支持所调用的功能，请访问 音视频通话功能出现了未开通的错误提示。

七、TUICallKit（含 TUICallEngine）是否支持接收离线消息？

不支持接收离线消息。

支持离线消息推送，可以通过 call / groupCall 中的 offlinePushInfo 添加需要推送的消息。

八、TUICallEngine init 未完成，需要在 init 完成后使用此API

未调用 login 接口，所有功能需要先进行登录完成后才能使用，具体参见 TUICallEngine login。

注意：TUICallEngine login 是一个异步接口，避免在 login 还未完成，直接调用 TUICallEngine 的接口。

九、当前通话状态无法使用该 API

API 与通话状态对照表：

十一、如何切换登录的 userId？

先调用destroyed可以完成实例的清理及登出，然后再调用init完成初始化及登录。

十二、TUICallKit Web 支持什么框架？支持 H5 吗？

TUICallKit 适用于 Vue2.7 + Typescript 或者 Vue3 + Typescript 项目，若你采用其他语言或者技术栈，请访问 界面定制指引。

十三、TUICallKit 打包失败？

对于 Vite 项目，你需要在 vite.config.js 中添加 base: "./"。

对于 Vue-CLI 创建的 webpack 项目，你需要在 vue.config.js 中添加 publicPath: "./"。

十四、TUICallKit 报错“获取设备权限失败”？

请先确保页面已被授权使用麦克风或摄像头，参见 设备授权说明。

可以尝试 Github Demo 是否可以正常通话，然后在 设备检测页面 检查是否支持 webrtc。

十五、timeout 字段设置无效原因？

该字段目前在 call / groupcall API 中会被使用到。

目前全平台 TUICallKit 的策略是被叫登录后，仅拉取 30s 内的历史消息。所以被叫登录后无法拉到主叫 30s 前的呼叫信息，从而导致被叫无法拉起邀请页面进行通话。

十六、视频通话切换大小屏出现闪屏现象？

iOS 17 设备和 WebRTC 底层兼容性问题，等待后续修复。

十七、safari 浏览器省电模式出现暂停键？

浏览器层面针对省电模式的视频播放策略，SDK 无法处理。

十八、如何生成 UserSig？

UserSig 是腾讯云为其云服务设计的一种安全保护签名，是一种登录凭证，由 SDKAppID 与 SecretKey 等信息组合加密得到。

·方式一：控制台获取，参考 获取临时 userSig。

·方式二：部署临时生成脚本。

注意：警告：

注意：此方式是在前端代码中配置 SecretKey，该方法中 SecretKey 很容易被反编译逆向破解，一旦你的密钥泄露，攻击者就可以盗用你的腾讯云流量，因此该方法仅适合本地跑通功能调试，生产环境请看方式三。

为方便初期调试，userSig 可临时使用 GenerateTestUserSig-es.js 中 genTestUserSig(params) 函数来计算 ，例如：

import { genTestUserSig } from "@trtc/calls-uikit-vue/debug/GenerateTestUserSig-es.js";const { userSig } = genTestUserSig({ userID: "Alice", SDKAppID: 0, SecretKey: "YOUT_SECRETKEY" });

·方式三：正式环境使用。

正确的 UserSig 签发方式是将 UserSig 的计算代码集成到你的服务端，并提供面向项目的接口，在需要 UserSig 时由你的项目向业务服务器发起请求获取动态 UserSig。更多详情请参见 服务端生成 UserSig。

十九、如何创建 userID？

·通过 userID 与 UserSig 登录过一次，会默认创建该用户。

·通过 即时通信 IM 控制台 进行创建和获取，单击目标应用卡片，进入应用的账号管理页面，也可创建账号并获取 userID。

20、如何解决源码拷贝可能导致的报错？

如果你在使用 TUICallKit 组件时遇到了报错，请不要担心，大多数情况下这是由于 ESLint 和 TSConfig 配置不一致造成的。你可以查阅文档，按照要求正确配置即可。如果你需要帮助，请随时联系我们，我们将确保你能够成功地使用此组件。以下是几个常见的问题：

ESLint 报错TypeScript 报错若 TUICallKit 与你项目的代码风格不一致导致报错，可将本组件目录屏蔽，如在项目根目录增加 .eslintignore 文件，如：# .eslintignoresrc/components/TUICallKit如遇 Cannot find module '../package.json'报错，是因为 TUICallKit 内引用了 JSON 文件，可在tsconfig.json中添加相关配置。其他 TSConfig 问题请参见 TSConfig Reference。{ "compilerOptions": { "resolveJsonModule": true }}

22、步骤1：下载 TUICallKit 组件源码及相关插件

Vue3Vue2.7Vue2.6npm install @trtc/calls-uikit-vuenpm install @trtc/calls-uikit-vue2npm install @trtc/calls-uikit-vue2.6 @vue/composition-api 源码集成需要安装 unplugin-vue2-script-setup 插件。npm i -D unplugin-vue2-script-setup修改构建工具配置文件。Vue CliviteWebpack// vue.config.jsconst ScriptSetup = require('unplugin-vue2-script-setup/webpack').defaultmodule.exports = { parallel: false, // disable thread-loader, which is not compactible with this plugin configureWebpack: { plugins: [ ScriptSetup({ /* options */ }), ], },}// vite.config.tsimport { defineConfig } from 'vite'import { createVuePlugin as Vue2 } from 'vite-plugin-vue2'import ScriptSetup from 'unplugin-vue2-script-setup/vite'export default defineConfig({ plugins: [ Vue2(), ScriptSetup({ /* options */ }), ],})// webpack.config.jsconst ScriptSetup = require('unplugin-vue2-script-setup/webpack').defaultmodule.exports = { /* … */ plugins: [ ScriptSetup({ /* options */ }), ]}

23、步骤2：源码集成 TUICallKit 组件包

将源码拷贝到自己的项目中，以拷贝到src/components/目录为例：

macOS + Vue3macOS + Vue2Windows + Vue3Windows + Vue2mkdir -p ./src/components/TUICallKit && cp -r ./node_modules/@trtc/calls-uikit-vue/* ./src/components/TUICallKitmkdir -p ./src/components/TUICallKit && cp -r ./node_modules/@trtc/calls-uikit-vue2/* ./src/components/TUICallKitxcopy .\\node_modules\\@trtc\\calls-uikit-vue .\\src\\components\\TUICallKit /i /excopy .\\node_modules\\@trtc\\calls-uikit-vue2 .\\src\\components\\TUICallKit /i /e

24、步骤3：修改 TUICallKit 引入路径

修改 TUICallKit 引入路径为本地文件引入。

注意：此方法可能与你的 ESLint、TypeScript 配置冲突，若出现报错，可参见 解决源码拷贝导致的报错。

import { TUICallKit, TUICallKitAPI } from "./components/TUICallKit/src/index";

接下来请参见上面的步骤及说明，使用 TUICallKit 组件提供的功能。

26、错误提示“The package you purchased does not support this ability”？

由于你当前应用的音视频通话能力包过期或未开通，请参见 开通服务，领取或者开通音视频通话能力，进而继续使用 TUICallKit 组件。

27、如何购买套餐？

请参考购买链接 音视频通话 SDK 价格总览，如有其他问题，请点击页面右侧，进行售前套餐咨询。

29、内网的环境下如何使用 callkit？

1. 通过 getTRTCCloudInstance 获取 TRTCCloud 实例。

注意：v3.1.3+ 支持。

const trtcCloud = TUICallKitAPI.getTUICallEngineInstance().getTRTCCloudInstance();

2. 通过 TRTCCloud 实例调用 callExperimentalAPI 完成代理服务器的设置（注意：需要在通话前调用）。具体如下：

trtcCloud.callExperimentalAPI(JSON.stringify({ api: 'setNetworkProxy', params: { websocketProxy: 'wss://proxy.example.com/ws/', turnServer: [{ url: '14.3.3.3:3478', username: 'turn', credential: 'turn', }], iceTransportPolicy: 'relay', },}));

注意：TRTC 应对防火墙受限参见 设置代理服务器。

31、如何关闭美颜？

·Web 端默认无美颜。

·小程序端调用 setBeautyLevel API，传入参数为0时，会关闭默认美颜。

TUICallKitAPI.getTUICallEngineInstance().setBeautyLevel(0);