适用场景
Web & H5 平台,独立集成私信聊天(1V1)或者群聊(Group),例如房产中介咨询、电商在线客服、保险远程定损等。
开发环境要求
Vue ( 全面支持 Vue2 & Vue3 , 请您在下方接入时选择您所匹配的 Vue 版本接入指引进行接入)
TypeScript ( 如您是 js 项目, 请跳转至 常见问题-js渐进式接入ts 进行配置 ts 渐进式支持)
sass(sass-loader 版本 ≤ 10.1.1)
node(node.js ≥ 16.0.0)
npm(版本请与 node 版本匹配)
TUIKit 源码集成
步骤1:创建项目
TUIKit 支持使用 webpack 或 vite 创建项目工程,配置 Vue3 / Vue2 + TypeScript + sass。以下是几种项目工程搭建示例:
注意:
请您务必保证您的 @vue/cli 版本在 5.0.0 以上,您可使用以下示例代码升级您的 @vue/cli 版本至 v5.0.8。
使用 vue-cli 方式创建项目, 配置 Vue2 / Vue3 + TypeScript + sass。
如果您尚未安装 vue-cli 或者 vue-cli 版本低于 5.0.0 ,可以在 terminal 或 cmd 中采用如下方式进行安装:
npm install -g @vue/cli@5.0.8 sass sass-loader@10.1.1
通过 vue-cli 创建项目,并选择下图中所选配置项。
vue create chat-example
请务必保证按照如下配置选择:
创建完成后,切换到项目所在目录:cd chat-example
如果您是 vue2 项目,请根据您所使用的 Vue 版本进行以下相应的环境配置, vue3 项目请忽略。
npm i vue@2.7.9 vue-template-compiler@2.7.9
npm i @vue/composition-api unplugin-vue2-script-setup vue@2.6.14 vue-template-compiler@2.6.14
步骤2:下载 TUIKit 组件
npm i @tencentcloud/chat-uikit-vuemkdir -p ./src/TUIKit && rsync -av --exclude={'node_modules','package.json','excluded-list.txt'} ./node_modules/@tencentcloud/chat-uikit-vue/ ./src/TUIKit
npm i @tencentcloud/chat-uikit-vue
xcopy .\\node_modules\\@tencentcloud\\chat-uikit-vue .\\src\\TUIKit /i /e /exclude:.\\node_modules\\@tencentcloud\\chat-uikit-vue\\excluded-list.txt
成功后目录结构如图所示:
步骤3:引入 TUIChat 组件
在
main.ts / main.js
中,引入 TUIKit,并注册到 Vue 项目实例中。import { createApp } from 'vue';import App from './App.vue';import { TUIComponents, TUIChatKit, genTestUserSig } from "./TUIKit";import { TUILogin } from "@tencentcloud/tui-core"; const app = createApp(App);const SDKAppID = 0; // Your SDKAppIDconst secretKey = ""; //Your secretKeyconst userID = ""; // User ID// TUIChatKit add TUIComponentsTUIChatKit.components(TUIComponents, app);// TUIChatKit initTUIChatKit.init();// TUICore loginTUILogin.login({SDKAppID,userID,// UserSig 是用户登录即时通信 IM 的密码,其本质是对 UserID 等信息加密后得到的密文。// 该方法仅适合本地跑通 Demo 和功能调试,详情请参见 https://cloud.tencent.com/document/product/269/32688userSig: genTestUserSig({SDKAppID,secretKey,userID,}).userSig,// 如果您需要发送图片、语音、视频、文件等富媒体消息,请设置为 trueuseUploadPlugin: true,// 本地审核可识别、处理不安全、不适宜的内容,为您的产品体验和业务安全保驾护航// 此功能为增值服务,请参考:https://cloud.tencent.com/document/product/269/79139// 如果您已购买内容审核服务,开启此功能请设置为 trueuseProfanityFilterPlugin: false,framework: "vue3",});app.mount("#app");export { SDKAppID, secretKey };
import Vue from "vue";import App from "./App.vue";import { TUIComponents, TUIChatKit, genTestUserSig } from "./TUIKit";import { TUILogin } from "@tencentcloud/tui-core";const SDKAppID = 0; // Your SDKAppIDconst secretKey = ""; //Your secretKeyconst userID = ""; // User ID// TUIChatKit add TUIComponentsTUIChatKit.components(TUIComponents, Vue);// TUIChatKit initTUIChatKit.init();// TUICore loginTUILogin.login({SDKAppID,userID,// UserSig 是用户登录即时通信 IM 的密码,其本质是对 UserID 等信息加密后得到的密文。// 该方法仅适合本地跑通 Demo 和功能调试,详情请参见 https://cloud.tencent.com/document/product/269/32688userSig: genTestUserSig({SDKAppID,secretKey,userID,}).userSig,// 如果您需要发送图片、语音、视频、文件等富媒体消息,请设置为 trueuseUploadPlugin: true,// 本地审核可识别、处理不安全、不适宜的内容,为您的产品体验和业务安全保驾护航// 此功能为增值服务,请参考:https://cloud.tencent.com/document/product/269/79139// 如果您已购买内容审核服务,开启此功能请设置为 trueuseProfanityFilterPlugin: false,framework: "vue2",});Vue.config.productionTip = false;new Vue({render: (h) => h(App),}).$mount("#app");export { SDKAppID, secretKey };
步骤4: 获取 SDKAppID 、secretKey 与 userID
设置 main.ts / main.js 文件示例代码中的相关参数 SDKAppID、secretKey 以及 userID:
SDKAppID 和 secretKey 等信息,可通过 即时通信 IM 控制台 获取。
userID 信息,可单击 即时通信 IM 控制台 > 账号管理,切换至目标应用所在账号,即可创建账号并获取 userID。
步骤5:请填写 userID / groupID,打开会话进行聊天
说明:
conversationID:会话 ID。会话 ID 组成方式:
C2C${userID}(单聊)
GROUP${groupID}(群聊)
关于群聊:
通过调用 API createGroup 可获取 groupID。
如果是直播群, 需要通过调用 API joinGroup加入群,才可以进行聊天。
进入聊天
通过调用 API switchConversation,传入 conversationID 进入聊天页面。
在需要展示的页面,调用 TUIKit 的组件即可使用。
例如:在 App.vue 页面中,使用 TUIChat、TUICallKit 快速搭建聊天界面(以下示例代码同时支持 Web 端与 H5 端)。
<template><div :class="['TUIKit', isH5 && 'TUIKit-h5']"><div class="TUIKit-main-container"><divv-show="!isH5 || !currentConversationID":class="['navbar', isH5 && 'navbar-h5']"><div class="navbar-button" @click="openChat">打开 1v1 聊天</div><div class="navbar-button" @click="openGroupChat">打开群聊</div></div><TUIChat v-show="!isH5 || currentConversationID"><h1>欢迎使用腾讯云即时通信IM</h1></TUIChat><TUICallKitclass="callkit-container":allowedMinimized="true":allowedFullScreen="false"/></div></div></template><script setup lang="ts">import { ref } from "vue";import { TUIStore, StoreName, TUIConversationService } from "@tencentcloud/chat-uikit-engine";import { TUICallKit } from "@tencentcloud/call-uikit-vue";import { TUIChat } from "./TUIKit";import { isH5 } from "./TUIKit/utils/env";const currentConversationID = ref<string>("");const userID = "";const groupID = "";TUIStore.watch(StoreName.CONV, {currentConversationID: (id: string) => {currentConversationID.value = id;},});function openChat() {// 切换会话进入聊天TUIConversationService.switchConversation(`C2C${userID}`);}function openGroupChat() {// 切换会话进入聊天TUIConversationService.switchConversation(`GROUP${groupID}`);}</script><style scoped lang="scss">@import "./TUIKit/assets/styles/common.scss";@import "./TUIKit/assets/styles/sample.scss";.navbar {box-sizing: border-box;min-width: 285px;flex: 0 0 24%;border-right: 1px solid #f4f5f9;padding: 20px;.navbar-button {padding: 10px 40px;background-color: #006eff;color: #ffffff;font-size: 16px;margin-top: 65px;border-radius: 30px;text-align: center;cursor: pointer;}}.navbar-h5 {flex: 1;border-right: 1px solid #f4f5f9;.navbar-button {cursor: none;}}.chat {flex: 1;}</style>
在需要展示的页面,调用 TUIKit 的组件即可使用。
例如:在 App.vue 页面中,使用 TUIChat、TUICallKit 快速搭建聊天界面(以下示例代码同时支持 Web 端与 H5 端)。
<template><div :class="['TUIKit', isH5 && 'TUIKit-h5']"><div class="TUIKit-main-container"><divv-show="!isH5 || !currentConversationID":class="['navbar', isH5 && 'navbar-h5']"><div class="navbar-button" @click="openChat">打开 1v1 聊天</div><div class="navbar-button" @click="openGroupChat">打开群聊</div></div><TUIChat v-show="!isH5 || currentConversationID"><h1>欢迎使用腾讯云即时通信 IM </h1></TUIChat><TUICallKitclass="callkit-container":allowedMinimized="true":allowedFullScreen="false"/></div></div></template><script lang="ts">import Vue from "vue";import { TUIStore, StoreName, TUIConversationService } from "@tencentcloud/chat-uikit-engine";import { TUICallKit } from "@tencentcloud/call-uikit-vue2";import { TUIChat } from "./TUIKit";import { isH5 } from "./TUIKit/utils/env";export default Vue.extend({name: "App",components: {TUIChat,TUICallKit,},data() {return {isH5: isH5,currentConversationID: "",currentNavbar: "conversation",userID: "", // 请填写对端 userIDgroupID: "", // 请填写会话 groupID};},methods: {// 打开 1v1 聊天openChat() {// 切换会话进入聊天TUIConversationService.switchConversation(`C2C${this.userID}`);},// 打开群聊openGroupChat() {TUIConversationService.switchConversation(`GROUP${this.groupID}`);},},mounted: function () {TUIStore.watch(StoreName.CONV, {currentConversationID: (id: string) => {this.currentConversationID = id;},});},});</script><style scoped lang="scss">@import "./TUIKit/assets/styles/common.scss";@import "./TUIKit/assets/styles/sample.scss";.navbar {box-sizing: border-box;min-width: 285px;flex: 0 0 24%;border-right: 1px solid #f4f5f9;padding: 20px;.navbar-button {padding: 10px 40px;background-color: #006eff;color: #ffffff;font-size: 16px;margin-top: 65px;border-radius: 30px;text-align: center;cursor: pointer;}}.navbar-h5 {flex: 1;border-right: 1px solid #f4f5f9;.navbar-button {cursor: none;}}.chat {flex: 1;}</style>
1. 安装支持 composition-api 以及 script setup 的相关依赖,以及 vue2.6 相关依赖:
npm i @vue/composition-api unplugin-vue2-script-setup vue@2.6.14 vue-template-compiler@2.6.14
2. main.ts 中引入 VueCompositionAPI:
import VueCompositionAPI from "@vue/composition-api";Vue.use(VueCompositionAPI);
3. 在 vue.config.js 中增加,若没有该文件请新建:
const ScriptSetup = require("unplugin-vue2-script-setup/webpack").default;module.exports = {parallel: false, // disable thread-loader, which is not compactible with this pluginconfigureWebpack: {plugins: [ScriptSetup({/* options */}),],},chainWebpack(config) {// disable type check and let `vue-tsc` handles itconfig.plugins.delete("fork-ts-checker");},};
4. 在 src/TUIKit/adapter-vue.ts 文件最后, 替换导出源:
// 初始写法export * from "vue";// 替换为export * from "@vue/composition-api";
5. 在需要展示的页面,调用 TUIKit 的组件即可使用。
例如:在 App.vue 页面中,使用 TUIChat、TUICallKit 快速搭建聊天界面(以下示例代码同时支持 Web 端与 H5 端)。
<template><div :class="['TUIKit', isH5 && 'TUIKit-h5']"><div class="TUIKit-main-container"><divv-show="!isH5 || !currentConversationID":class="['navbar', isH5 && 'navbar-h5']"><div class="navbar-button" @click="openChat">打开 1v1 聊天</div><div class="navbar-button" @click="openGroupChat">打开群聊</div></div><TUIChat v-show="!isH5 || currentConversationID"><h1>欢迎使用腾讯云即时通信IM</h1></TUIChat><TUICallKitclass="callkit-container":allowedMinimized="true":allowedFullScreen="false"/></div></div></template><script lang="ts">import Vue from "vue";import { TUIStore, StoreName, TUIConversationService } from "@tencentcloud/chat-uikit-engine";import { TUICallKit } from "@tencentcloud/call-uikit-vue2.6";import { TUIChat } from "./TUIKit";import { isH5 } from "./TUIKit/utils/env";export default Vue.extend({name: "App",components: {TUIChat,TUICallKit,},data() {return {isH5: isH5,currentConversationID: "",currentNavbar: "conversation",userID: "", // 请填写对端 userIDgroupID: "", // 请填写会话 groupID};},methods: {// 打开 1v1 聊天openChat() {// 切换会话进入聊天TUIConversationService.switchConversation(`C2C${this.userID}`);},// 打开群聊openGroupChat() {TUIConversationService.switchConversation(`GROUP${this.groupID}`);},},mounted: function () {TUIStore.watch(StoreName.CONV, {currentConversationID: (id: string) => {this.currentConversationID = id;},});},});</script><style scoped lang="scss">@import "./TUIKit/assets/styles/common.scss";@import "./TUIKit/assets/styles/sample.scss";.navbar {box-sizing: border-box;min-width: 285px;flex: 0 0 24%;border-right: 1px solid #f4f5f9;padding: 20px;.navbar-button {padding: 10px 40px;background-color: #006eff;color: #ffffff;font-size: 16px;margin-top: 65px;border-radius: 30px;text-align: center;cursor: pointer;}}.navbar-h5 {flex: 1;border-right: 1px solid #f4f5f9;.navbar-button {cursor: none;}}.chat {flex: 1;}</style>
步骤6:启动项目
执行以下命令启动项目:
npm run serve
npm run dev
步骤7:发送您的第一条消息
更多高级特性
客服插件
常见问题
产品服务类问题
1. 音视频通话能力包未开通?音视频通话发起失败?
2. 如何开通消息云端搜索插件?
3. 如何开通在线客服插件?
4. 什么是 UserSig?如何生成 UserSig?
UserSig 是用户登录即时通信 IM 的密码,其本质是对 UserID 等信息加密后得到的密文。
UserSig 签发方式是将 UserSig 的计算代码集成到您的服务端,并提供面向项目的接口,在需要 UserSig 时由您的项目向业务服务器发起请求获取动态 UserSig。更多详情请参见 服务端生成 UserSig。
注意:
本文示例代码采用的获取 UserSig 的方案是在客户端代码中配置 SECRETKEY,该方法中 SECRETKEY 很容易被反编译逆向破解,一旦您的密钥泄露,攻击者就可以盗用您的腾讯云流量,因此该方法仅适合本地跑通功能调试。 正确的 UserSig 签发方式请参见上文。
接入报错类问题
1. 运行时报错:"TypeError: Cannot read properties of undefined (reading "getFriendList")"
若按照上述步骤接入后,运行时出现以下错误,请您务必删除 TUIKit 目录下的 node_modules 目录,以保证 TUIKit 的依赖唯一性,避免 TUIKit 多份依赖造成问题。
2. js 工程如何接入 TUIKit 组件?
TUIKit 仅支持 ts 环境运行,您可以通过渐进式配置 typescript 来使您项目中已有的 js 代码 与 TUIKit 中 ts 代码共存。
请在您 vue-cli 脚手架创建的工程根目录执行:
vue add typescript
之后按照如下进行配置项进行选择(为了保证能同时支持原有 js 代码 与 TUIKit 中 ts 代码,请您务必严格按照以下五个选项进行配置)。
完成以上步骤后,请重新运行项目!
请在您 vite 创建的工程根目录执行:
npm install -D typescript
3. 运行时报错:/chat-example/src/TUIKit/components/TUIChat /message-input/message-input-editor.vue .ts(8,23)TS1005: expected.
出现以上报错信息,是因为您安装的 @vue/cli 版本过低导致,请您务必保证您的 @vue/cli 版本在 5.0.0 及以上。升级方式如下:
npm install -g @vue/cli@5.0.8
4. 运行时报错: Failed to resolve loader: sass-loader
出现以上报错信息,是因为您未安装
sass
环境导致,请执行以下命令进行 sass
环境安装:npm i -D sass sass-loader@10.1.1
5. ESLint 报错:error 'withDefaults' is not defined no-undef? 'defineProps' is not defined no-undef? 以及 ESLint 其他报错?
若 chat-uikit-vue 拷贝到 src 目录汇总与您本地项目代码风格不一致导致报错,可将本组件目录屏蔽,如在项目根目录增加 .eslintignore 文件:
# .eslintignoresrc/TUIKit
6. vue/cli 如何关闭 dev 模式下,webpack 全屏 overlay error 报错信息提示?
可以在您项目根目录的 vue.config.js 中进行关闭:
module.exports = defineConfig({...devServer: {client: {overlay: false,},},});
module.exports = {...devServer: {overlay: false,},};
7. 出现 Component name "XXXX" should always be multi-word 怎么办?
IM TUIKit web 所使用的 ESLint 版本为 v6.7.2 ,对于模块名的驼峰式格式并不进行严格校验。
如果您出现此问题,您可以在 .eslintrc.js 文件中进行如下配置:
module.exports = {...rules: {...'vue/multi-word-component-names': 'warn',},};
8. 出现 ERESOLVE unable to resolve dependency tree 怎么办?
npm install 的时候如果出现 ERESOLVE unable to resolve dependency tree ,表示依赖安装冲突,可采用以下方式进行安装:
npm install --legacy-peer-deps
9. 运行报错如下'vue packages version mismatch',如何解决?
// 如果您是 vue2.7 项目,请在您项目根目录执行npm i vue@2.7.9 vue-template-compiler@2.7.9// 如果您是 vue2.6 项目,请在您项目根目录执行npm i vue@2.6.14 vue-template-compiler@2.6.14
10. vite 项目 npm run build 之后 ts 报错?
原因:package.json script 下 "build": "vue-tsc && vite build" 中的 vue-tsc 命令导致。
解决方案: 删除 vue-tsc 即可。 "build": "vite build"。
技术咨询
相关文档
Vue2 & Vue3 UIKit 相关:
集成音视频通话