919 lines
22 KiB
Markdown
919 lines
22 KiB
Markdown
# Bytedesk客服系统 - 前端工程师集成手册
|
||
|
||
**版本**: v1.0
|
||
**最后更新**: 2025-01-07
|
||
**适用项目**: vf_react
|
||
**后端服务器**: http://43.143.189.195
|
||
|
||
---
|
||
|
||
## 📋 目录
|
||
|
||
- [1. 集成概述](#1-集成概述)
|
||
- [2. 快速开始（5分钟集成）](#2-快速开始5分钟集成)
|
||
- [3. 详细集成步骤](#3-详细集成步骤)
|
||
- [4. 配置说明](#4-配置说明)
|
||
- [5. 高级功能](#5-高级功能)
|
||
- [6. 样式定制](#6-样式定制)
|
||
- [7. 故障排查](#7-故障排查)
|
||
- [8. 常见问题FAQ](#8-常见问题faq)
|
||
- [9. 性能优化](#9-性能优化)
|
||
- [10. 安全注意事项](#10-安全注意事项)
|
||
|
||
---
|
||
|
||
## 1. 集成概述
|
||
|
||
### 1.1 什么是Bytedesk客服系统？
|
||
|
||
Bytedesk是一个开源的在线客服系统，为您的网站提供实时客户服务功能。本手册将指导您将Bytedesk客服Widget集成到vf_react项目中。
|
||
|
||
### 1.2 集成架构
|
||
|
||
```
|
||
┌────────────────────────────────────────────────────────────┐
|
||
│ vf_react前端项目 │
|
||
│ ┌────────────────────────────────────────────────────┐ │
|
||
│ │ App.jsx │ │
|
||
│ │ ┌──────────────────────────────────────────────┐ │ │
|
||
│ │ │ BytedeskWidget组件 │ │ │
|
||
│ │ │ - 动态加载客服脚本 │ │ │
|
||
│ │ │ - 显示悬浮客服图标 │ │ │
|
||
│ │ │ - 处理用户交互 │ │ │
|
||
│ │ └──────────────────────────────────────────────┘ │ │
|
||
│ └────────────────────────────────────────────────────┘ │
|
||
└────────────────────────────────────────────────────────────┘
|
||
│
|
||
│ HTTP/WebSocket
|
||
↓
|
||
┌────────────────────────────────────────────────────────────┐
|
||
│ Bytedesk后端服务 (43.143.189.195) │
|
||
│ - API接口: :9003 │
|
||
│ - WebSocket: :9885 │
|
||
│ - Nginx反向代理: :80 │
|
||
└────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 1.3 集成特点
|
||
|
||
- ✅ **零侵入**: 不修改vf_react原有代码逻辑
|
||
- ✅ **即插即用**: 复制文件 + 修改配置即可使用
|
||
- ✅ **样式隔离**: 使用Shadow DOM，不影响全局样式
|
||
- ✅ **异步加载**: 不阻塞页面渲染
|
||
- ✅ **跨页面**: 在所有页面显示客服图标
|
||
- ✅ **响应式**: 自动适配移动端和PC端
|
||
|
||
---
|
||
|
||
## 2. 快速开始（5分钟集成）
|
||
|
||
### 步骤1: 复制集成文件
|
||
|
||
将`bytedesk-integration`文件夹复制到vf_react项目的`src/`目录下：
|
||
|
||
```bash
|
||
# 在vf_react项目根目录执行
|
||
cd D:\【Git】\vf_react
|
||
cp -r bytedesk-integration src/
|
||
```
|
||
|
||
文件结构：
|
||
```
|
||
vf_react/
|
||
├── src/
|
||
│ ├── bytedesk-integration/ # 客服集成文件夹
|
||
│ │ ├── components/
|
||
│ │ │ └── BytedeskWidget.jsx # 客服Widget组件
|
||
│ │ ├── config/
|
||
│ │ │ └── bytedesk.config.js # 配置文件
|
||
│ │ ├── App.jsx.example # 集成示例代码
|
||
│ │ ├── .env.bytedesk.example # 环境变量示例
|
||
│ │ └── 前端工程师集成手册.md # 本手册
|
||
│ ├── App.jsx # 您的主App文件
|
||
│ └── ...
|
||
└── package.json
|
||
```
|
||
|
||
### 步骤2: 配置环境变量
|
||
|
||
复制环境变量模板到项目根目录并配置：
|
||
|
||
```bash
|
||
# 复制模板
|
||
cp src/bytedesk-integration/.env.bytedesk.example .env.local
|
||
|
||
# 编辑配置文件
|
||
vim .env.local
|
||
```
|
||
|
||
**必需配置项**（在.env.local中）:
|
||
```bash
|
||
# Bytedesk服务器地址
|
||
REACT_APP_BYTEDESK_API_URL=http://43.143.189.195
|
||
|
||
# 组织ID（由管理员提供）
|
||
REACT_APP_BYTEDESK_ORG=df_org_uid
|
||
|
||
# 工作组ID（由管理员提供）
|
||
REACT_APP_BYTEDESK_SID=df_wg_aftersales
|
||
```
|
||
|
||
> **注意**: ORG和SID需要从管理员处获取，或登录后台http://43.143.189.195/admin/查看。
|
||
|
||
### 步骤3: 集成到App.jsx
|
||
|
||
打开`src/App.jsx`，参考`App.jsx.example`添加以下代码：
|
||
|
||
```jsx
|
||
// 1. 导入组件和配置（在文件顶部添加）
|
||
import BytedeskWidget from './bytedesk-integration/components/BytedeskWidget';
|
||
import { getBytedeskConfig } from './bytedesk-integration/config/bytedesk.config';
|
||
|
||
function App() {
|
||
// 2. 获取配置
|
||
const bytedeskConfig = getBytedeskConfig();
|
||
|
||
return (
|
||
<div className="App">
|
||
{/* 您的原有代码保持不变 */}
|
||
|
||
{/* 3. 添加客服Widget（在return的JSX最后添加） */}
|
||
<BytedeskWidget
|
||
config={bytedeskConfig}
|
||
autoLoad={true}
|
||
/>
|
||
</div>
|
||
);
|
||
}
|
||
|
||
export default App;
|
||
```
|
||
|
||
### 步骤4: 启动项目测试
|
||
|
||
```bash
|
||
# 安装依赖（如果需要）
|
||
npm install
|
||
|
||
# 启动开发服务器
|
||
npm start
|
||
```
|
||
|
||
打开浏览器，您应该在页面右下角看到客服图标（💬）。
|
||
|
||
---
|
||
|
||
## 3. 详细集成步骤
|
||
|
||
### 3.1 文件说明
|
||
|
||
#### BytedeskWidget.jsx
|
||
React组件，负责加载和管理Bytedesk客服Widget。
|
||
|
||
**主要功能**:
|
||
- 动态加载客服脚本（https://www.weiyuai.cn/embed/bytedesk-web.js）
|
||
- 初始化客服Widget
|
||
- 生命周期管理（加载、卸载、清理）
|
||
- 错误处理
|
||
|
||
**Props**:
|
||
```typescript
|
||
interface BytedeskWidgetProps {
|
||
config: Object; // 配置对象（必需）
|
||
autoLoad?: boolean; // 是否自动加载（默认true）
|
||
onLoad?: (bytedesk) => void; // 加载成功回调
|
||
onError?: (error) => void; // 加载失败回调
|
||
}
|
||
```
|
||
|
||
#### bytedesk.config.js
|
||
配置文件，包含客服系统的所有配置项。
|
||
|
||
**主要函数**:
|
||
- `getBytedeskConfig()`: 获取基础配置
|
||
- `getBytedeskConfigWithUser(user)`: 获取带用户信息的配置
|
||
- `shouldShowCustomerService(pathname)`: 判断是否在当前页面显示客服
|
||
|
||
### 3.2 集成方式选择
|
||
|
||
根据您的需求，选择合适的集成方式：
|
||
|
||
#### 方式一: 全局集成（推荐）
|
||
|
||
**适用场景**: 所有页面都需要客服功能
|
||
|
||
```jsx
|
||
import BytedeskWidget from './bytedesk-integration/components/BytedeskWidget';
|
||
import { getBytedeskConfig } from './bytedesk-integration/config/bytedesk.config';
|
||
|
||
function App() {
|
||
const bytedeskConfig = getBytedeskConfig();
|
||
|
||
return (
|
||
<div className="App">
|
||
{/* 您的页面内容 */}
|
||
|
||
<BytedeskWidget config={bytedeskConfig} autoLoad={true} />
|
||
</div>
|
||
);
|
||
}
|
||
```
|
||
|
||
#### 方式二: 按页面显示
|
||
|
||
**适用场景**: 只在特定页面显示客服（如排除登录页、支付页）
|
||
|
||
```jsx
|
||
import { useLocation } from 'react-router-dom';
|
||
import BytedeskWidget from './bytedesk-integration/components/BytedeskWidget';
|
||
import { getBytedeskConfig, shouldShowCustomerService } from './bytedesk-integration/config/bytedesk.config';
|
||
|
||
function App() {
|
||
const location = useLocation();
|
||
const bytedeskConfig = getBytedeskConfig();
|
||
const showBytedesk = shouldShowCustomerService(location.pathname);
|
||
|
||
return (
|
||
<div className="App">
|
||
{/* 您的页面内容 */}
|
||
|
||
{showBytedesk && (
|
||
<BytedeskWidget config={bytedeskConfig} autoLoad={true} />
|
||
)}
|
||
</div>
|
||
);
|
||
}
|
||
```
|
||
|
||
自定义页面规则（修改`bytedesk.config.js`）:
|
||
|
||
```javascript
|
||
export const shouldShowCustomerService = (pathname) => {
|
||
// 在以下页面显示客服
|
||
const allowedPages = [
|
||
'/',
|
||
'/home',
|
||
'/products',
|
||
'/pricing',
|
||
];
|
||
|
||
// 在以下页面隐藏客服
|
||
const blockedPages = [
|
||
'/login',
|
||
'/register',
|
||
'/payment',
|
||
];
|
||
|
||
if (blockedPages.some(page => pathname.startsWith(page))) {
|
||
return false;
|
||
}
|
||
|
||
return allowedPages.some(page => pathname.startsWith(page));
|
||
};
|
||
```
|
||
|
||
#### 方式三: 带用户信息集成
|
||
|
||
**适用场景**: 需要将登录用户信息传递给客服端
|
||
|
||
```jsx
|
||
import { useContext } from 'react';
|
||
import BytedeskWidget from './bytedesk-integration/components/BytedeskWidget';
|
||
import { getBytedeskConfigWithUser } from './bytedesk-integration/config/bytedesk.config';
|
||
import { AuthContext } from './contexts/AuthContext';
|
||
|
||
function App() {
|
||
const { user } = useContext(AuthContext);
|
||
const bytedeskConfig = getBytedeskConfigWithUser(user);
|
||
|
||
return (
|
||
<div className="App">
|
||
{/* 您的页面内容 */}
|
||
|
||
<BytedeskWidget config={bytedeskConfig} autoLoad={true} />
|
||
</div>
|
||
);
|
||
}
|
||
```
|
||
|
||
用户信息格式:
|
||
```javascript
|
||
const user = {
|
||
id: '12345', // 用户ID（必需）
|
||
name: '张三', // 用户名
|
||
email: 'user@example.com', // 邮箱
|
||
mobile: '13800138000', // 手机号
|
||
};
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 配置说明
|
||
|
||
### 4.1 环境变量配置
|
||
|
||
在`.env.local`文件中配置（项目根目录）:
|
||
|
||
```bash
|
||
# ========== 必需配置 ==========
|
||
|
||
# 后端服务地址
|
||
REACT_APP_BYTEDESK_API_URL=http://43.143.189.195
|
||
|
||
# 组织ID
|
||
REACT_APP_BYTEDESK_ORG=df_org_uid
|
||
|
||
# 工作组ID
|
||
REACT_APP_BYTEDESK_SID=df_wg_aftersales
|
||
|
||
# ========== 可选配置 ==========
|
||
|
||
# 客服类型 (2=人工客服, 1=机器人)
|
||
REACT_APP_BYTEDESK_TYPE=2
|
||
|
||
# 语言 (zh-cn, en, ja, ko)
|
||
REACT_APP_BYTEDESK_LOCALE=zh-cn
|
||
|
||
# 图标位置 (bottom-right, bottom-left, top-right, top-left)
|
||
REACT_APP_BYTEDESK_PLACEMENT=bottom-right
|
||
|
||
# 图标边距（像素）
|
||
REACT_APP_BYTEDESK_MARGIN_BOTTOM=20
|
||
REACT_APP_BYTEDESK_MARGIN_SIDE=20
|
||
|
||
# 主题模式 (system, light, dark)
|
||
REACT_APP_BYTEDESK_THEME_MODE=system
|
||
|
||
# 主题色
|
||
REACT_APP_BYTEDESK_THEME_COLOR=#0066FF
|
||
|
||
# 自动弹出（不推荐）
|
||
REACT_APP_BYTEDESK_AUTO_POPUP=false
|
||
```
|
||
|
||
### 4.2 代码配置
|
||
|
||
在`bytedesk.config.js`中直接修改:
|
||
|
||
```javascript
|
||
export const bytedeskConfig = {
|
||
// API服务地址
|
||
apiUrl: 'http://43.143.189.195',
|
||
htmlUrl: 'http://43.143.189.195/chat/',
|
||
|
||
// 客服图标位置
|
||
placement: 'bottom-right',
|
||
|
||
// 边距设置
|
||
marginBottom: 20,
|
||
marginSide: 20,
|
||
|
||
// 自动弹出
|
||
autoPopup: false,
|
||
|
||
// 语言设置
|
||
locale: 'zh-cn',
|
||
|
||
// 客服图标配置
|
||
bubbleConfig: {
|
||
show: true,
|
||
icon: '💬', // 可以使用emoji或图片URL
|
||
title: '在线客服',
|
||
subtitle: '点击咨询',
|
||
},
|
||
|
||
// 主题配置
|
||
theme: {
|
||
mode: 'system', // light | dark | system
|
||
backgroundColor: '#0066FF',
|
||
textColor: '#ffffff',
|
||
},
|
||
|
||
// 聊天配置
|
||
chatConfig: {
|
||
org: 'df_org_uid',
|
||
t: '2', // 2=人工客服, 1=机器人
|
||
sid: 'df_wg_aftersales',
|
||
},
|
||
};
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 高级功能
|
||
|
||
### 5.1 多工作组支持
|
||
|
||
根据页面显示不同工作组的客服：
|
||
|
||
```javascript
|
||
// bytedesk.config.js
|
||
export const getBytedeskConfigByPath = (pathname) => {
|
||
const config = getBytedeskConfig();
|
||
|
||
// 根据路径选择工作组
|
||
if (pathname.startsWith('/sales')) {
|
||
return {
|
||
...config,
|
||
chatConfig: {
|
||
...config.chatConfig,
|
||
sid: 'df_wg_sales', // 销售组
|
||
},
|
||
};
|
||
} else if (pathname.startsWith('/support')) {
|
||
return {
|
||
...config,
|
||
chatConfig: {
|
||
...config.chatConfig,
|
||
sid: 'df_wg_support', // 技术支持组
|
||
},
|
||
};
|
||
}
|
||
|
||
return config; // 默认售后组
|
||
};
|
||
```
|
||
|
||
使用示例:
|
||
```jsx
|
||
import { useLocation } from 'react-router-dom';
|
||
import { getBytedeskConfigByPath } from './bytedesk-integration/config/bytedesk.config';
|
||
|
||
function App() {
|
||
const location = useLocation();
|
||
const bytedeskConfig = getBytedeskConfigByPath(location.pathname);
|
||
|
||
return (
|
||
<div className="App">
|
||
<BytedeskWidget config={bytedeskConfig} autoLoad={true} />
|
||
</div>
|
||
);
|
||
}
|
||
```
|
||
|
||
### 5.2 条件性显示
|
||
|
||
根据用户登录状态或角色显示客服：
|
||
|
||
```jsx
|
||
function App() {
|
||
const { user } = useContext(AuthContext);
|
||
const bytedeskConfig = getBytedeskConfig();
|
||
|
||
// 只为普通用户显示客服（管理员不显示）
|
||
const showBytedesk = user && user.role === 'customer';
|
||
|
||
return (
|
||
<div className="App">
|
||
{showBytedesk && (
|
||
<BytedeskWidget config={bytedeskConfig} autoLoad={true} />
|
||
)}
|
||
</div>
|
||
);
|
||
}
|
||
```
|
||
|
||
### 5.3 事件回调
|
||
|
||
监听客服系统的加载状态：
|
||
|
||
```jsx
|
||
function App() {
|
||
const bytedeskConfig = getBytedeskConfig();
|
||
|
||
const handleLoad = (bytedesk) => {
|
||
console.log('客服系统加载成功', bytedesk);
|
||
// 可以在这里执行自定义逻辑
|
||
// 例如: 发送统计事件
|
||
};
|
||
|
||
const handleError = (error) => {
|
||
console.error('客服系统加载失败', error);
|
||
// 可以在这里显示降级方案
|
||
// 例如: 显示备用联系方式
|
||
};
|
||
|
||
return (
|
||
<div className="App">
|
||
<BytedeskWidget
|
||
config={bytedeskConfig}
|
||
autoLoad={true}
|
||
onLoad={handleLoad}
|
||
onError={handleError}
|
||
/>
|
||
</div>
|
||
);
|
||
}
|
||
```
|
||
|
||
### 5.4 自定义触发按钮
|
||
|
||
隐藏默认图标，使用自定义按钮：
|
||
|
||
```jsx
|
||
import { useState } from 'react';
|
||
|
||
function App() {
|
||
const [showBytedesk, setShowBytedesk] = useState(false);
|
||
|
||
// 隐藏默认图标
|
||
const bytedeskConfig = {
|
||
...getBytedeskConfig(),
|
||
bubbleConfig: {
|
||
show: false, // 隐藏默认图标
|
||
},
|
||
};
|
||
|
||
return (
|
||
<div className="App">
|
||
{/* 自定义按钮 */}
|
||
<button
|
||
onClick={() => setShowBytedesk(true)}
|
||
className="custom-service-btn"
|
||
>
|
||
联系客服
|
||
</button>
|
||
|
||
{showBytedesk && (
|
||
<BytedeskWidget config={bytedeskConfig} autoLoad={true} />
|
||
)}
|
||
</div>
|
||
);
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 样式定制
|
||
|
||
### 6.1 修改主题色
|
||
|
||
在配置中修改主题色：
|
||
|
||
```javascript
|
||
// bytedesk.config.js
|
||
theme: {
|
||
mode: 'light',
|
||
backgroundColor: '#FF6600', // 您的品牌色
|
||
textColor: '#ffffff',
|
||
},
|
||
```
|
||
|
||
### 6.2 修改图标位置
|
||
|
||
```javascript
|
||
// bytedesk.config.js
|
||
placement: 'bottom-left', // 左下角
|
||
marginBottom: 30, // 距底部30px
|
||
marginSide: 30, // 距左侧30px
|
||
```
|
||
|
||
### 6.3 使用自定义图标
|
||
|
||
使用图片URL替换emoji:
|
||
|
||
```javascript
|
||
// bytedesk.config.js
|
||
bubbleConfig: {
|
||
show: true,
|
||
icon: 'https://yourdomain.com/images/service-icon.png',
|
||
title: '在线客服',
|
||
subtitle: '点击咨询',
|
||
},
|
||
```
|
||
|
||
### 6.4 样式不冲突
|
||
|
||
Bytedesk Widget使用Shadow DOM技术，样式完全隔离，不会影响您的全局CSS。
|
||
|
||
---
|
||
|
||
## 7. 故障排查
|
||
|
||
### 7.1 客服图标不显示
|
||
|
||
**可能原因**:
|
||
1. 环境变量未配置
|
||
2. 配置文件路径错误
|
||
3. 后端服务未启动
|
||
4. 脚本加载失败
|
||
|
||
**解决方案**:
|
||
```bash
|
||
# 1. 检查.env.local文件是否存在
|
||
ls -la .env.local
|
||
|
||
# 2. 检查环境变量是否加载
|
||
console.log(process.env.REACT_APP_BYTEDESK_API_URL);
|
||
|
||
# 3. 检查后端服务状态
|
||
curl http://43.143.189.195/api/health
|
||
|
||
# 4. 查看浏览器控制台错误
|
||
# 打开浏览器开发者工具 -> Console标签页
|
||
```
|
||
|
||
### 7.2 连接不上后端
|
||
|
||
**检查清单**:
|
||
```bash
|
||
# 1. 后端服务是否运行
|
||
# 联系后端工程师确认docker容器状态
|
||
|
||
# 2. 防火墙是否开放
|
||
# 确认80端口可访问
|
||
|
||
# 3. CORS配置
|
||
# 后端需要在.env.production中添加您的前端地址:
|
||
# BYTEDESK_CORS_ALLOWED_ORIGINS=http://your-frontend-domain.com
|
||
```
|
||
|
||
### 7.3 ORG或SID错误
|
||
|
||
**获取正确配置**:
|
||
1. 登录管理后台: http://43.143.189.195/admin/
|
||
2. 导航到"设置" -> "组织信息"，复制`组织UID`
|
||
3. 导航到"客服管理" -> "工作组"，复制`工作组ID`
|
||
4. 更新`.env.local`文件
|
||
5. 重启开发服务器: `npm start`
|
||
|
||
### 7.4 开发环境正常，生产环境异常
|
||
|
||
**检查清单**:
|
||
```bash
|
||
# 1. 确认生产环境的环境变量
|
||
# 查看构建时的配置
|
||
|
||
# 2. 检查CORS配置
|
||
# 后端需要添加生产域名到CORS白名单
|
||
|
||
# 3. 检查HTTPS/HTTP
|
||
# 如果前端使用HTTPS，后端也应使用HTTPS
|
||
|
||
# 4. 查看生产环境日志
|
||
npm run build
|
||
# 检查构建产物中的配置
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 常见问题FAQ
|
||
|
||
### Q1: 客服系统会影响页面性能吗？
|
||
|
||
**A**: 不会。客服脚本采用异步加载，不会阻塞页面渲染。Widget总大小约50KB（gzip后），首次加载后会被浏览器缓存。
|
||
|
||
### Q2: 可以在移动端使用吗？
|
||
|
||
**A**: 可以。Bytedesk Widget完全响应式，自动适配移动端和PC端。
|
||
|
||
### Q3: 是否支持离线消息？
|
||
|
||
**A**: 支持。用户在客服离线时发送的消息会被保存，客服上线后可以查看。
|
||
|
||
### Q4: 可以集成到React Native吗？
|
||
|
||
**A**: BytedeskWidget是为Web设计的。React Native需要使用Bytedesk的原生SDK（另外提供）。
|
||
|
||
### Q5: 如何隐藏特定页面的客服？
|
||
|
||
**A**: 使用`shouldShowCustomerService`函数（见3.2节"方式二"）。
|
||
|
||
### Q6: 可以同时配置多个工作组吗？
|
||
|
||
**A**: 可以。参考5.1节"多工作组支持"。
|
||
|
||
### Q7: 用户信息是否安全？
|
||
|
||
**A**: 是的。所有通信使用WebSocket加密传输，用户信息不会被第三方获取。建议生产环境使用HTTPS。
|
||
|
||
### Q8: 是否需要付费？
|
||
|
||
**A**: Bytedesk社区版（当前使用）完全免费，License有效期至2040年12月31日。
|
||
|
||
---
|
||
|
||
## 9. 性能优化
|
||
|
||
### 9.1 按需加载
|
||
|
||
只在需要时加载客服系统：
|
||
|
||
```jsx
|
||
import { useState, useEffect } from 'react';
|
||
|
||
function App() {
|
||
const [loadBytedesk, setLoadBytedesk] = useState(false);
|
||
|
||
// 延迟5秒加载（页面渲染完成后）
|
||
useEffect(() => {
|
||
const timer = setTimeout(() => {
|
||
setLoadBytedesk(true);
|
||
}, 5000);
|
||
|
||
return () => clearTimeout(timer);
|
||
}, []);
|
||
|
||
return (
|
||
<div className="App">
|
||
{/* 您的页面内容 */}
|
||
|
||
{loadBytedesk && (
|
||
<BytedeskWidget config={getBytedeskConfig()} autoLoad={true} />
|
||
)}
|
||
</div>
|
||
);
|
||
}
|
||
```
|
||
|
||
### 9.2 Lazy Import
|
||
|
||
使用React.lazy延迟导入组件：
|
||
|
||
```jsx
|
||
import { lazy, Suspense } from 'react';
|
||
|
||
const BytedeskWidget = lazy(() => import('./bytedesk-integration/components/BytedeskWidget'));
|
||
|
||
function App() {
|
||
return (
|
||
<div className="App">
|
||
{/* 您的页面内容 */}
|
||
|
||
<Suspense fallback={null}>
|
||
<BytedeskWidget config={getBytedeskConfig()} autoLoad={true} />
|
||
</Suspense>
|
||
</div>
|
||
);
|
||
}
|
||
```
|
||
|
||
### 9.3 缓存优化
|
||
|
||
客服脚本会自动被浏览器缓存，无需额外配置。
|
||
|
||
---
|
||
|
||
## 10. 安全注意事项
|
||
|
||
### 10.1 环境变量安全
|
||
|
||
```bash
|
||
# ❌ 错误: 不要在代码中硬编码配置
|
||
const config = {
|
||
apiUrl: 'http://43.143.189.195',
|
||
org: 'df_org_uid',
|
||
};
|
||
|
||
# ✅ 正确: 使用环境变量
|
||
const config = {
|
||
apiUrl: process.env.REACT_APP_BYTEDESK_API_URL,
|
||
org: process.env.REACT_APP_BYTEDESK_ORG,
|
||
};
|
||
```
|
||
|
||
### 10.2 敏感信息保护
|
||
|
||
```javascript
|
||
// ❌ 不要传递敏感信息
|
||
const user = {
|
||
id: '12345',
|
||
password: 'user-password', // 不要传递密码
|
||
creditCard: '1234-5678', // 不要传递信用卡
|
||
};
|
||
|
||
// ✅ 只传递必要信息
|
||
const user = {
|
||
id: '12345',
|
||
name: '张三',
|
||
email: 'user@example.com',
|
||
};
|
||
```
|
||
|
||
### 10.3 HTTPS使用
|
||
|
||
生产环境强烈建议使用HTTPS:
|
||
|
||
```bash
|
||
# 开发环境
|
||
REACT_APP_BYTEDESK_API_URL=http://43.143.189.195
|
||
|
||
# 生产环境
|
||
REACT_APP_BYTEDESK_API_URL=https://kefu.yourdomain.com
|
||
```
|
||
|
||
### 10.4 内容安全策略（CSP）
|
||
|
||
如果您的项目使用CSP，需要允许以下域名：
|
||
|
||
```html
|
||
<meta http-equiv="Content-Security-Policy" content="
|
||
default-src 'self';
|
||
script-src 'self' https://www.weiyuai.cn;
|
||
connect-src 'self' http://43.143.189.195;
|
||
img-src 'self' data: http://43.143.189.195;
|
||
"/>
|
||
```
|
||
|
||
---
|
||
|
||
## 11. 获取帮助
|
||
|
||
### 11.1 联系方式
|
||
|
||
- **技术支持**: 访问 http://43.143.189.195/chat/ 在线咨询
|
||
- **管理员**: 联系您的项目管理员获取ORG和SID
|
||
- **后端工程师**: 联系后端团队确认服务器状态
|
||
|
||
### 11.2 日志查看
|
||
|
||
```javascript
|
||
// 在浏览器控制台查看Bytedesk日志
|
||
// 日志前缀为 [Bytedesk]
|
||
|
||
// 示例:
|
||
[Bytedesk] 开始加载客服Widget...
|
||
[Bytedesk] Widget脚本加载成功
|
||
[Bytedesk] 初始化Widget
|
||
[Bytedesk] Widget初始化成功
|
||
```
|
||
|
||
### 11.3 调试技巧
|
||
|
||
```javascript
|
||
// 1. 检查配置是否正确
|
||
console.log('Bytedesk配置:', getBytedeskConfig());
|
||
|
||
// 2. 检查环境变量
|
||
console.log('API URL:', process.env.REACT_APP_BYTEDESK_API_URL);
|
||
console.log('ORG:', process.env.REACT_APP_BYTEDESK_ORG);
|
||
console.log('SID:', process.env.REACT_APP_BYTEDESK_SID);
|
||
|
||
// 3. 检查Widget是否加载
|
||
console.log('BytedeskWeb对象:', window.BytedeskWeb);
|
||
```
|
||
|
||
---
|
||
|
||
## 12. 版本历史
|
||
|
||
| 版本 | 日期 | 更新内容 |
|
||
|------|------|---------|
|
||
| v1.0 | 2025-01-07 | 初始版本，支持基础集成功能 |
|
||
|
||
---
|
||
|
||
## 13. 附录
|
||
|
||
### 13.1 完整配置示例
|
||
|
||
```javascript
|
||
// bytedesk.config.js - 完整配置
|
||
export const bytedeskConfig = {
|
||
apiUrl: 'http://43.143.189.195',
|
||
htmlUrl: 'http://43.143.189.195/chat/',
|
||
placement: 'bottom-right',
|
||
marginBottom: 20,
|
||
marginSide: 20,
|
||
autoPopup: false,
|
||
locale: 'zh-cn',
|
||
bubbleConfig: {
|
||
show: true,
|
||
icon: '💬',
|
||
title: '在线客服',
|
||
subtitle: '点击咨询',
|
||
},
|
||
theme: {
|
||
mode: 'system',
|
||
backgroundColor: '#0066FF',
|
||
textColor: '#ffffff',
|
||
},
|
||
chatConfig: {
|
||
org: 'df_org_uid',
|
||
t: '2',
|
||
sid: 'df_wg_aftersales',
|
||
},
|
||
};
|
||
```
|
||
|
||
### 13.2 文件清单
|
||
|
||
集成所需的所有文件：
|
||
|
||
```
|
||
bytedesk-integration/
|
||
├── components/
|
||
│ └── BytedeskWidget.jsx # React组件（必需）
|
||
├── config/
|
||
│ └── bytedesk.config.js # 配置文件（必需）
|
||
├── App.jsx.example # 集成示例（参考）
|
||
├── .env.bytedesk.example # 环境变量示例（参考）
|
||
└── 前端工程师集成手册.md # 本手册（参考）
|
||
```
|
||
|
||
---
|
||
|
||
**祝您集成顺利！**
|
||
|
||
如有任何问题，请随时联系技术支持。
|