# visitor-chat

**Repository Path**: templi/visitor-chat

## Basic Information

- **Project Name**: visitor-chat
- **Description**: 一行代码接入的在线客服访客组件，支持主题定制、访客轨迹追踪、移动端全屏，基于Vue3+TDesign
- **Primary Language**: TypeScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: https://kf.guoway.net
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-10-12
- **Last Updated**: 2026-10-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: 在线客服, 客服系统, webchat, 在线聊天, 网站客服

## README

# Visitor Chat - 访客聊天组件

果唯云客服访客端（v2.1）：一行代码嵌入的聊天窗口 + 访客轨迹追踪 SDK，基于 Vue 3 + TDesign，与 IM System 后端配套。

- 独立仓库：`git@gitee.com:templi/visitor-chat.git`（master / develop）
- 主仓库集成：以 git submodule 挂载于 im-system 的 `visitor-chat/` 路径
- 完整版体验地址：https://kf.guoway.net
- 许可证：MIT License

访客聊天窗口预览：

![访客聊天窗口](docs/visitor-chat.png)

## 架构概览

```
宿主网站
 └─ <script src="chat-widget.js" data-tenant="xxx">   ← 嵌入 SDK（public/chat-widget.js）
     ├─ 气泡按钮 + iframe 聊天窗口                     ← 本仓库 Vue 应用（生产 base=/chat/）
     └─ 访客轨迹追踪（页面浏览 / UTM / 设备 / 停留时长）
```

- SDK 与聊天窗口通过 `postMessage` 协作：`chat-open`（坐席邀请打开窗口）、`chat-collapsed`（窗口收起/展开）、`chat-session-started`（会话建立后绑定轨迹上报）、`chat-page-changed`（SPA 路由变化，供邀请规则匹配）
- 访客身份：UUID v7，持久化于宿主域 `localStorage('_guoway_vid')`，聊天与轨迹共用同一身份

## 技术栈

- **Vue 3** + **Vite 5**
- **TDesign Vue Next**（企业级 UI 组件库）
- **axios**、**markdown-it** + **DOMPurify**（Markdown 渲染与 XSS 防护）、**uuid**
- **WebSocket** 实时通信；构建产物 gzip + brotli 双压缩

## 快速开始

### 安装与开发

```bash
npm install
npm run dev        # http://localhost:3001，自动代理 /api、/uploads、/ws → localhost:8080
```

### 构建与预览

```bash
npm run build      # 产物输出 dist/（生产 base=/chat/）
./start-prod.sh    # 构建后以静态服务预览 dist/（:8081）
```

## 嵌入 SDK 用法

宿主页面引入一行脚本即可获得「气泡 + 聊天窗口 + 轨迹追踪」：

```html
<script src="https://kf.guoway.net/chat/chat-widget.js" data-tenant="租户ID"></script>
```

嵌入宿主网站的实际效果（官网右下角展开的聊天窗口）：

![嵌入宿主网站的效果](docs/vistitor-install-product.png)

### data-* 属性

| 属性 | 默认值 | 说明 |
| --- | --- | --- |
| `data-tenant` | 内置演示租户 | 租户 ID（必填） |
| `data-server` | `https://kf.guoway.net` | 聊天窗口 / API 服务地址 |
| `data-api-host` | 同 `data-server` | 轨迹上报地址 |
| `data-path` | `/chat/index.html` | 聊天页面路径 |
| `data-theme` | `blue` | 主题：`blue`/`red`/`yellow`/`green`/`purple`/`pink` |
| `data-color` | 跟随主题 | 气泡按钮颜色（显式指定后不随 `setTheme` 变化） |
| `data-text` | `💬 在线客服` | 气泡按钮文案 |
| `data-position` | `right` | 位置：`left` / `right` |
| `data-offset` | `20` | 水平边距（px） |
| `data-bottom` | `20` | 垂直边距（px） |
| `data-width` | `420` | 桌面端窗口宽度（px） |
| `data-height` | `560` | 桌面端窗口高度（px） |
| `data-max-height-ratio` | `0.88` | 窗口高度上限（视口高度比例） |
| `data-min-height` | `320` | 桌面端最小高度（px） |
| `data-mobile` | `true` | 移动端全屏模式（`false` 关闭） |
| `data-auto-open` | `false` | 加载后自动打开窗口 |
| `data-auto-open-delay` | `3000` | 自动打开延迟（ms） |
| `data-track` | `true` | 启用访客轨迹追踪（`false` 关闭） |
| `data-track-debug` | `false` | 轨迹追踪调试日志 |

### JS API

脚本加载后立即可用（DOM 初始化前的调用会自动排队）：

```js
ChatWidget.open()          // 打开窗口
ChatWidget.close()         // 关闭窗口
ChatWidget.toggle()        // 切换显隐
ChatWidget.destroy()       // 销毁并清理 DOM
ChatWidget.getConfig()     // 获取当前配置
ChatWidget.getState()      // { open, folded }
ChatWidget.setTheme('red') // 切换主题（窗口按新主题重新加载）
```

## 页面模式与 URL 参数

聊天窗口可脱离 SDK 独立访问（iframe / 新窗口），支持参数：

| 参数 | 说明 |
| --- | --- |
| `tenant_id` | 租户 ID（必填，缺失时页面提示） |
| `server` | 服务地址（API 基地址优先取它，其次 `VITE_API_BASE`，最后 fallback `https://kf.guoway.net`） |
| `visitor_id` | 访客 ID（SDK 注入，跨域共享轨迹身份） |
| `page_url` | 宿主页面路径（供「指定页面触发」的邀请规则匹配） |
| `theme` | 主题：`blue`/`red`/`yellow`/`green`/`purple`/`pink` |
| `channel` | 消息渠道标记：`web`（默认）/ `wechat` / `miniprogram` |
| `full` | `1` 全屏模式：窗口居中放大并展示右侧企业信息栏 |

全屏模式（`full=1`）效果，右侧为企业信息栏：

![全屏模式](docs/visitor-chat-full.png)

## 配置

`.env`（开发）/ `.env.production`（生产构建）：

| 变量 | 说明 | 默认值 |
| --- | --- | --- |
| `VITE_API_BASE` | API 基础地址 | 开发 `http://localhost:8080`；生产留空（运行时由 `?server=` 或 fallback 决定） |
| `VITE_TENANT_CODE` | 租户代码 | `demo` |

## 主题定制

内置 6 套主题色板（默认品牌蓝 `#165ed3`），通过 CSS 变量注入实现：

- `--vb-primary` 系列：自有组件（头部、访客气泡、侧栏）使用
- `--td-brand-color-1..10`：TDesign 品牌色板，按钮/加载等组件自动跟随

新增主题：在 `src/utils/theme.js` 的 `THEMES` 中加一行色值即可，同时同步维护 `public/chat-widget.js` 的 `THEME_COLORS`（气泡按钮色随主题切换依赖它）。

紫色主题（`purple`）效果示例：

![紫色主题效果](docs/verify-sdk-demo-theme.png)

## 功能特性

- ✅ 实时会话：WebSocket 同域连接（`/ws`，经 nginx 代理），服务发现 + 24h 缓存、心跳、自动重连
- ✅ 消息类型：文本、表情、图片、视频、文件（≤50MB）、Markdown（markdown-it 渲染 + DOMPurify 净化）
- ✅ 机器人 FAQ 关键词提示（仅在机器人接待时展示，点击直达发送）
- ✅ 主动邀请：坐席邀请 + 规则触发（页面匹配 / 停留时长），以对话内消息形式展示
- ✅ 满意度评价：5 星 + 评语（可跳过）
- ✅ 转人工 / 离线留言表单
- ✅ 消息声音提醒（可开关）
- ✅ 折叠视图与全屏模式（全屏带企业信息侧栏）
- ✅ 网络断开提示
- ✅ 移动端全屏自适应（视觉视口 + 运行时 viewport meta 注入，兼容夸克 / 微信内置浏览器）

## 访客轨迹追踪

`data-track` 默认开启，SDK 自动采集：

- 页面浏览（含标题、路径、referrer）、UTM 来源、设备 / 浏览器 / OS
- 停留时长：30 秒心跳 + 离开时 `sendBeacon` 兜底上报
- SPA 路由监听（pushState / replaceState / popstate / hashchange）
- 会话建立后自动绑定聊天会话 ID，供客服工作台「实时访客」列表与在线状态联动

上报接口：`POST /api/v1/tracker/page_view`

## 服务端接口

| 接口 | 方法 | 说明 |
| --- | --- | --- |
| `/api/v1/visitor/login` | POST | 访客登录（获取 Token 与租户信息） |
| `/api/v1/visitor/tenant-info` | GET | 企业信息 / 在线坐席数 |
| `/api/v1/visitor/messages` | POST | 发送消息（文本 / 文件，经 WebSocket 通道） |
| `/api/v1/service-discovery` | GET | WebSocket 地址服务发现 |
| `/upload` | POST | 文件上传（≤50MB） |
| `/api/v1/tracker/page_view` | POST | 访客轨迹上报 |
| `/ws` | WS | 实时消息通道 |

## 项目结构

```
visitor-chat/
├── public/
│   ├── chat-widget.js      # 嵌入 SDK（气泡 + iframe + 轨迹追踪）
│   └── sdk-demo.html       # SDK 接入演示页
├── src/
│   ├── App.vue             # 聊天窗口主组件（装配各功能的 composable）
│   ├── components/         # 头部 / 消息列表 / 输入区 / 满意度弹窗 / 留言表单 / 折叠视图 / 企业侧栏
│   ├── composables/        # 认证 / WebSocket / 上传 / FAQ / 邀请规则 / 声音 / 会话状态
│   └── utils/              # 主题 / Markdown 渲染 / 格式化 / WS 配置
├── index.html              # 入口页（生产 base=/chat/）
├── vite.config.js
├── start-prod.sh
└── package.json
```

## 许可证

MIT License © guoway.net