vf/vf_react

Fork 0

Files

zdl 8fe11efcd7 refactor: 清理 Bytedesk 集成文件，移动文档到 docs 目录

2025-11-20 15:07:45 +08:00

22 KiB

Raw Blame History

Bytedesk客服系统 - 前端工程师集成手册

版本: v1.0 最后更新: 2025-01-07 适用项目: vf_react 后端服务器: http://43.143.189.195

📋 目录

1. 集成概述
2. 快速开始（5分钟集成）
3. 详细集成步骤
4. 配置说明
5. 高级功能
6. 样式定制
7. 故障排查
8. 常见问题FAQ
9. 性能优化
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/目录下：

# 在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: 配置环境变量

复制环境变量模板到项目根目录并配置：

# 复制模板
cp src/bytedesk-integration/.env.bytedesk.example .env.local

# 编辑配置文件
vim .env.local

必需配置项（在.env.local中）:

# 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添加以下代码：

// 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: 启动项目测试

# 安装依赖（如果需要）
npm install

# 启动开发服务器
npm start

打开浏览器，您应该在页面右下角看到客服图标（💬）。

3. 详细集成步骤

3.1 文件说明

BytedeskWidget.jsx

React组件，负责加载和管理Bytedesk客服Widget。

主要功能:

动态加载客服脚本（https://www.weiyuai.cn/embed/bytedesk-web.js）
初始化客服Widget
生命周期管理（加载、卸载、清理）
错误处理

Props:

interface BytedeskWidgetProps {
  config: Object;          // 配置对象（必需）
  autoLoad?: boolean;      // 是否自动加载（默认true）
  onLoad?: (bytedesk) => void;    // 加载成功回调
  onError?: (error) => void;      // 加载失败回调
}

bytedesk.config.js

配置文件，包含客服系统的所有配置项。

主要函数:

getBytedeskConfig(): 获取基础配置
getBytedeskConfigWithUser(user): 获取带用户信息的配置
shouldShowCustomerService(pathname): 判断是否在当前页面显示客服

3.2 集成方式选择

根据您的需求，选择合适的集成方式：

方式一: 全局集成（推荐）

适用场景: 所有页面都需要客服功能

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>
  );
}

方式二: 按页面显示

适用场景: 只在特定页面显示客服（如排除登录页、支付页）

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）:

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));
};

方式三: 带用户信息集成

适用场景: 需要将登录用户信息传递给客服端

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>
  );
}

用户信息格式:

const user = {
  id: '12345',              // 用户ID（必需）
  name: '张三',             // 用户名
  email: 'user@example.com', // 邮箱
  mobile: '13800138000',     // 手机号
};

4. 配置说明

4.1 环境变量配置

在.env.local文件中配置（项目根目录）:

# ========== 必需配置 ==========

# 后端服务地址
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中直接修改:

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 多工作组支持

根据页面显示不同工作组的客服：

// 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;  // 默认售后组
};

使用示例:

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 条件性显示

根据用户登录状态或角色显示客服：

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 事件回调

监听客服系统的加载状态：

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 自定义触发按钮

隐藏默认图标，使用自定义按钮：

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 修改主题色

在配置中修改主题色：

// bytedesk.config.js
theme: {
  mode: 'light',
  backgroundColor: '#FF6600',  // 您的品牌色
  textColor: '#ffffff',
},

6.2 修改图标位置

// bytedesk.config.js
placement: 'bottom-left',  // 左下角
marginBottom: 30,           // 距底部30px
marginSide: 30,             // 距左侧30px

6.3 使用自定义图标

使用图片URL替换emoji:

// 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. 检查.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 连接不上后端

检查清单:

# 1. 后端服务是否运行
# 联系后端工程师确认docker容器状态

# 2. 防火墙是否开放
# 确认80端口可访问

# 3. CORS配置
# 后端需要在.env.production中添加您的前端地址:
# BYTEDESK_CORS_ALLOWED_ORIGINS=http://your-frontend-domain.com

7.3 ORG或SID错误

获取正确配置:

登录管理后台: http://43.143.189.195/admin/
导航到"设置" -> "组织信息"，复制组织UID
导航到"客服管理" -> "工作组"，复制工作组ID
更新.env.local文件
重启开发服务器: npm start

7.4 开发环境正常，生产环境异常

检查清单:

# 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 按需加载

只在需要时加载客服系统：

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延迟导入组件：

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 环境变量安全

# ❌ 错误: 不要在代码中硬编码配置
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 敏感信息保护

// ❌ 不要传递敏感信息
const user = {
  id: '12345',
  password: 'user-password',  // 不要传递密码
  creditCard: '1234-5678',    // 不要传递信用卡
};

// ✅ 只传递必要信息
const user = {
  id: '12345',
  name: '张三',
  email: 'user@example.com',
};

10.3 HTTPS使用

生产环境强烈建议使用HTTPS:

# 开发环境
REACT_APP_BYTEDESK_API_URL=http://43.143.189.195

# 生产环境
REACT_APP_BYTEDESK_API_URL=https://kefu.yourdomain.com

10.4 内容安全策略（CSP）

如果您的项目使用CSP，需要允许以下域名：

<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 日志查看

// 在浏览器控制台查看Bytedesk日志
// 日志前缀为 [Bytedesk]

// 示例:
[Bytedesk] 开始加载客服Widget...
[Bytedesk] Widget脚本加载成功
[Bytedesk] 初始化Widget
[Bytedesk] Widget初始化成功

11.3 调试技巧

// 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 完整配置示例

// 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            # 本手册（参考）

祝您集成顺利！

如有任何问题，请随时联系技术支持。

22 KiB Raw Blame History Unescape Escape