## 介绍

智能客服用户端 Web UIKit。使用此 UIKit，您可以在一天内将智能客服的能力集成到您的 Web 或 Hybrid 项目。极简接入，用 AI 为您的产品增收提效。

## 效果展示

![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027960326/2f5444f4095b11f0990f52540099c741.png)


## 开发环境要求
- Vue ( 全面支持 Vue2 & Vue3 ， 请您在下方接入时选择您所匹配的 Vue 版本接入指引进行接入)

- TypeScript （如果您是 js 项目， 请参见 [常见问题- js 工程如何接入 TUIKit 组件](https://cloud.tencent.com/document/product/269/68493#dbce298f-6d21-4221-86fc-12b0153eaef8) 进行配置 ts 渐进式支持）

- sass（sass-loader 版本 ≤ 10.1.1）

- node（node.js ≥ 16.0.0）

- npm（版本请与 node 版本匹配）


## UIKit 源码集成

### 步骤1：创建项目

支持使用 webpack 或 vite 创建项目工程，配置 Vue3 / Vue2 + TypeScript + sass。以下是几种项目工程搭建示例：



【vue-cli】

> **说明：**
>
> 1. 请确保您的`@vue/cli`版本在 **5.0.0** 以上，您可使用以下示例代码升级`@vue/cli`版本至 v5.0.8。
> 2. 如果您的项目由较低版本的`@vue/cli`创建，集成 UIKit 后运行项目如有报错，请查阅[常见问题](https://cloud.tencent.com/document/product/269/102783#04a7d474-e04a-4765-910f-9bbfe4e3ced9)解决。


使用 vue-cli 方式创建项目， 配置 Vue2 / Vue3 + TypeScript + sass。

如果您尚未安装 vue-cli 或者 vue-cli 版本低于 5.0.0 ，可以在 terminal 或 cmd 中采用如下方式进行安装：


【shell】
``` bash
npm install -g @vue/cli@5.0.8 sass sass-loader@10.1.1
```

通过 vue-cli 创建项目，并选择下图中所选配置项。


【shell】
``` bash
vue create ai-desk-example
```

请务必保证按照如下配置选择：

![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027119864/f2327fbe352211ef9397525400fdb830.png)

创建完成后，切换到项目所在目录：
``` bash
cd ai-desk-example
```

如果您是 vue2 项目，请根据您所使用的 Vue 版本进行以下相应的环境配置， vue3 项目请忽略。



【vue2.7】
``` bash
npm i vue@2.7.9 vue-template-compiler@2.7.9
```

【vue2.6及以下】
``` bash
npm i @vue/composition-api unplugin-vue2-script-setup vue@2.6.14 vue-template-compiler@2.6.14
```

【vite】

> **说明：**
>

> Vite 需要[**Node.js**](https://nodejs.org/en/)** 版本 18+，20+。**当您的包管理器发出警告时，请注意升级您的 Node 版本，详情请参考 [vite 官网](https://cn.vitejs.dev/guide/)。
>


使用 vite 方式创建项目，按照下图选项配置 Vue + TypeScript 。
``` bash
npm create vite@latest
```

![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027960326/94f4888bf42911efa8355254001c06ec.png)


之后切换到项目目录，安装项目依赖：
``` bash
cd ai-desk-example
npm install
```

安装插件所需 sass 环境依赖：
``` bash
npm i -D sass sass-loader
```

清除项目默认的样式，避免样式问题：



【macOS 端】
``` bash
echo -n > src/style.css
```

【Windows 端（PowerShell）​】
``` bash
Clear-Content -Path src/style.css
```

【Windows 端（CMD）】
``` bash
echo. > src\style.css
```

### 步骤2：下载 UI 组件

通过 npm 方式下载 UI 组件，并将 UI 组件复制到自己工程的 src 目录下：



【macOS  端】


【shell】
``` bash
npm i @tencentcloud/ai-desk-customer-vue@latest
```


【shell】
``` bash
mkdir -p ./src/ai-desk-customer-vue && rsync -av --exclude={'node_modules','excluded-list.txt'} ./node_modules/@tencentcloud/ai-desk-customer-vue/ ./src/ai-desk-customer-vue
```

【Windows  端】


【shell】
``` bash
npm i @tencentcloud/ai-desk-customer-vue@latest
```


【shell】
``` bash
xcopy .\node_modules\@tencentcloud\ai-desk-customer-vue .\src\ai-desk-customer-vue /i /e /exclude:.\node_modules\@tencentcloud\ai-desk-customer-vue\excluded-list.txt
```

### 步骤3：引入 UI 组件

##### 在需要展示的页面，引入 UI 的组件即可使用。

##### 例如：在 App.vue 页面中实现以下代码，即可快速搭建客服咨询界面（以下示例代码同时支持 Web 端与 H5 端）：

> **说明：**
>

> 以下示例代码使用了 setup 语法，如果您的项目没有使用 setup 语法，请按照 Vue3/Vue2 的标准方式注册组件。
>




【vue3】
``` javascript
<template>
  <CustomerServiceChat
      :style="{ width: '600px', height: '80vh', margin: '10px auto', boxShadow: '0 11px 20px #ccc' }"
  />
</template>
<script setup lang="ts">
import TUICustomerServer, { CustomerServiceChat } from './ai-desk-customer-vue';
import { onMounted } from "vue";

onMounted(() => {
  const SDKAppID = 0; // Your SDKAppID，即开通了智能客服 Desk 的应用 ID
  const userID = ''; // Your userID，可复用您 app 的账号体系，或随机生成
  const userSig = ''; // Your userSig，接入阶段可控制台生成，生产阶段请务必由服务端生成
  TUICustomerServer.init(SDKAppID, userID, userSig);
});
</script>
<style scoped>
</style>
```

【vue2.7】
``` javascript
<template>
  <div id="app">
    <CustomerServiceChat
        :style="{ width: '600px', height: '80vh', margin: '10px auto', boxShadow: '0 11px 20px #ccc' }"
    />
  </div>
</template>
<script lang="ts" setup>
import TUICustomerServer, { CustomerServiceChat } from './ai-desk-customer-vue';
import vue from './ai-desk-customer-vue/adapter-vue';

const { onMounted } = vue;

onMounted(() => {
  const SDKAppID = 0; // Your SDKAppID
  const userID = ''; // Your userID
  const userSig = ''; // Your userSig
  TUICustomerServer.init(SDKAppID, userID, userSig);
});
</script>
<style lang="scss">
</style>
```

【vue2.6及以下】
``` javascript
<template>
  <div id="app">
    <CustomerServiceChat
        :style="{ width: '600px', height: '80vh', margin: '10px auto', boxShadow: '0 11px 20px #ccc' }"
    />
  </div>
</template>
<script lang="ts" setup>
import TUICustomerServer, { CustomerServiceChat } from './ai-desk-customer-vue';
import vue from './ai-desk-customer-vue/adapter-vue';

const { onMounted } = vue;

onMounted(() => {
  const SDKAppID = 0; // Your SDKAppID
  const userID = ''; // Your userID
  const userSig = ''; // Your userSig
  TUICustomerServer.init(SDKAppID, userID, userSig);
});
</script>
<style lang="scss">
</style>
```
1. 在 `main.ts/main.js `中引入 VueCompositionAPI。

``` javascript
import VueCompositionAPI from "@vue/composition-api";
Vue.use(VueCompositionAPI);
```
2. 在 `vue.config.js `中增加，若没有该文件请新建。

``` javascript
const ScriptSetup = require("unplugin-vue2-script-setup/webpack").default;
module.exports = {
  parallel: false, // disable thread-loader, which is not compactible with this plugin
  configureWebpack: {
    plugins: [
      ScriptSetup({
        /* options */
      }),
    ],
  },
  chainWebpack(config) {
    // disable type check and let `vue-tsc` handles it
    config.plugins.delete("fork-ts-checker");
  },
};
```
3. 在 `src/ai-desk-customer-vue/adapter-vue-web.ts` 文件最后, 替换导出源：

``` javascript
// 初始写法
export * from "vue";
// 替换为
export * from "@vue/composition-api";
```

### 步骤4： 获取 SDKAppID 、userID 、 userSig

设置`App.vue`中的 `SDKAppID`、`userID`、`userSig` 。
- SDKAppID 信息，可在 [即时通信 IM 控制台](https://console.cloud.tencent.com/im) 单击**应用管理** > **创建新应用**，并选择**客服服务 Desk** > **智能客服**， [开通智能客服](https://console.cloud.tencent.com/im/ai-desk) 后获取。

  ![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100031390357/7ac165770ae411f088bd525400e889b2.png)

  ![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100031390357/c5699ccc0ae411f0b3015254001c06ec.png)

- userID 信息，可本地生成一个随机的字符串，例如 test-1234。

- userSig 信息，可单击 [即时通信 IM 控制台 > UserSig生成校验](https://console.cloud.tencent.com/im/tool-usersig)，填写创建的 userID，即可生成 userSig。

  ![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100031390357/dbfdb4ca0ae411f088bd525400e889b2.png)


### 步骤5：启动项目，发起您的第一条客服咨询

执行以下命令启动项目：



【vue-cli】

> **说明：**
>

> 由于 vue-cli 默认开启 webpack 全局 overlay 报错信息提示，为了您有更好的体验，**建议您关闭全局 overlay 报错提示。**
>

> 在 vue.config.js 中添加以下代码
>

>

【webpack4及以上】
> `module.exports = defineConfig({`
> `  devServer: {`
> `    client: {`
> `      overlay: false,`
> `    },`
> `  },`
> `});`

【webpack3】
> `module.exports = {`
> `  devServer: {`
> `    overlay: false,`
> `  },`
> `};`
>

> 在 tsconfig.json 中关闭 ai-desk-customer-vue  的ts检测。
>
> `{`
> `    "exclude": [`
> `      "node_modules",`
> `      "src/ai-desk-customer-vue",`
> `    ]`
> `}`



【shell】
``` bash
npm run serve
```

【vite】


【shell】
``` bash
npm run dev
```

## 高级特性

### 国际化界面语言

从 v1.0.0 起，UIKit 支持以下界面语言：
<table>
<tr>
<td rowspan="1" colSpan="1" >语言代码（userLang）</td>

<td rowspan="1" colSpan="1" >语言</td>
</tr>

<tr>
<td rowspan="1" colSpan="1" >zh_cn</td>

<td rowspan="1" colSpan="1" >简体中文</td>
</tr>

<tr>
<td rowspan="1" colSpan="1" >en</td>

<td rowspan="1" colSpan="1" >英文</td>
</tr>

<tr>
<td rowspan="1" colSpan="1" >zh_tw</td>

<td rowspan="1" colSpan="1" >繁体中文</td>
</tr>

<tr>
<td rowspan="1" colSpan="1" >ja</td>

<td rowspan="1" colSpan="1" >日语</td>
</tr>

<tr>
<td rowspan="1" colSpan="1" >id</td>

<td rowspan="1" colSpan="1" >印尼语</td>
</tr>

<tr>
<td rowspan="1" colSpan="1" >ms</td>

<td rowspan="1" colSpan="1" >马来语</td>
</tr>

<tr>
<td rowspan="1" colSpan="1" >vi</td>

<td rowspan="1" colSpan="1" >越南语</td>
</tr>

<tr>
<td rowspan="1" colSpan="1" >th</td>

<td rowspan="1" colSpan="1" >泰语</td>
</tr>

<tr>
<td rowspan="1" colSpan="1" >fil</td>

<td rowspan="1" colSpan="1" >菲律宾语</td>
</tr>

<tr>
<td rowspan="1" colSpan="1" >ru</td>

<td rowspan="1" colSpan="1" >俄语</td>
</tr>
</table>


如果您的业务需要出海，且用户语言以英语为主，可在引入智能客服时设置`userLang="en"`。如果您不指定`userLang`, UIKit 会使用浏览器设置的语言。
``` javascript
<template>
    <CustomerServiceChat style="height: 100%;"
        userLang="en"
    />
</template>
```

如果您需要支持动态切换用户语言，可使用`TUICustomerServer.changeLanguage`接口，并通过切换 页面/组件 key 的方式，实现语言动态修改与展示。
``` javascript
<template>
    <CustomerServiceChat style="height: 100%;"
        :key="locale"
        :userLang="locale"
    />
</template>
<script setup lang="ts">
import TUICustomerServer, { CustomerServiceChat }  from '../../ai-desk-customer-uniapp';
import { onMounted, ref } from "vue";

const locale = ref('en');

const changeLanguage = (language: string) => {
  TUICustomerServer.changeLanguage(language).then(() => {
    locale.value = language;
  });
}
</script>
<style scoped lang="scss">
</style>
```

### 工具栏快捷 button

如果您想实现输入框上方增加快捷 button，方便用户使用，比如增加“人工客服”，“发送订单消息”等，可在引入智能客服时设置 `toolbarButtonList`。效果如下所示：

![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027960326/b727aeef19cd11f0abe05254005ef0f7.png)

``` javascript
<template>
    <CustomerServiceChat style="height: 100%;"
        :toolbarButtonList="toolbarButtonList"
    />
</template>
<script setup lang="ts">
import TUICustomerServer, { CustomerServiceChat }  from '../../ai-desk-customer-uniapp';
import { ref } from "vue";

const toolbarButtonList = ref([
  { 
    title: '人工客服', 
    renderCondition: () => {
      return true;
    },
    clickEvent: () => {
      // 点击 button 后的回调
      TUICustomerServer.sendTextMessage({
        to: '@customer_service_account',
        conversationType: 'C2C',
        payload: {
          text: '人工客服'
        }
      });
    }
  },
  {
    title: '发送订单',
    renderCondition: () => {
      return true;
    },
    clickEvent: () => {
      // 点击 button 后的回调
      TUICustomerServer.sendCustomMessage({
        to: '@customer_service_account',
        conversationType: 'C2C',
        payload: {
          data: JSON.stringify({
            src: '22',
            customerServicePlugin: 0,
            content: {
              desc: "¥3000/月",
              header: "高级版智能客服",
              pic: "https://cloudcache.tencent-cloud.com/qcloud/portal/kit/images/presale.a4955999.jpeg",
              url: "https://cloud.tencent.com/document/product/269/116070"
            }
          }),
        }
      });
    }
  }
]);
</script>
<style scoped lang="scss">
</style>
```

## 常见问题

##### 什么是 UserSig？如何生成 UserSig？

UserSig 是用户登录即时通信 IM 的密码，其本质是对 UserID 等信息加密后得到的密文。

UserSig 签发方式是将 UserSig 的计算代码集成到您的服务端，并提供面向项目的接口，在需要 UserSig 时由您的项目向业务服务器发起请求获取动态 UserSig。更多详情请参见 [服务端生成 UserSig](https://cloud.tencent.com/document/product/269/32688#GeneratingdynamicUserSig)。

##### js 工程如何接入 TUIKit 组件?

UIKit 仅支持 ts 环境运行，您可以通过渐进式配置 typescript 来使您项目中已有的 js 代码 与 UIKit 中 ts 代码共存。



【vue-cli】

请在您 vue-cli 脚手架创建的工程根目录执行：
``` bash
vue add typescript
```

之后按照如下进行配置项进行选择（为了保证能同时支持原有 js 代码 与 UIKit 中 ts 代码，请您务必严格按照以下五个选项进行配置）![260706614-5e2fc00b-ace5-4843-bef6-c0e234225b5d.png (1514×360)](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027960326/1f8ad8d0f43211ef920e5254005ef0f7.png)

**完成以上步骤后，请重新运行项目！**

【vite】

请在您 vite 创建的工程根目录执行：
``` bash
npm install -D typescript
```

##### 运行报错：Uncaught TypeError: marked__WEBPACK_IMPORTED_MODULE_0_ Marked is not a constructor

如果您运行过程中出现如下错误，说明您当前 Vue CLI 构建的项目环境版本较低，需要降低 uikit 中使用的 marked 版本至 5.1.2。

![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027960326/104ee490098211f0990f52540099c741.png)


请在您项目的 根目录 使用以下脚本降低 marked 版本：
``` bash
npm i marked@5.1.2 --legacy-peer-deps
```

##### 编译报错 node_modules/marked/lib/marked.esm.js: Class private methods are not enabled.

如果您运行过程中出现如下错误，说明您当前使用的 marked 版本过低，请升级 marked 版本至 6.0.0。

![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027960326/32a9c4c9f43111efbda7525400454e06.png)


请在您项目的根目录使用以下脚本升级 marked 版本：
``` bash
npm i marked@6.0.0 --legacy-peer-deps
```

## 交流与反馈

[点此进入 IM 社群](https://zhiliao.qq.com/s/c5GY7HIM62CK)，享有专业工程师的支持，解决您的难题。