kefu_cloud/docs/INTEGRATION_GUIDE.md

在线客服 Web 端接入指南

本文档面向接入在线客服的网站开发与运维人员，帮助您在 1 分钟内将客服系统集成至您的企业官网、电商商城、Web 业务系统或单页应用（SPA）中。

---

1. 接入前准备

您只需要向客服系统管理员获取一个专属的 渠道标识（Channel Key）：

参数	说明	示例
服务地址	客服系统统一入口	https://cloud.400cc.cn/
渠道标识（data-id）	您企业专属的渠道密钥	WK_8a3f2e

💡 获取方式：登录客服工作台 -> 左侧菜单「系统设置」 -> 「渠道管理」 -> 复制您渠道的专属代码（其中的 data-id 即为您的 Channel Key）。

---

2. 快速接入（标准网页 / HTML）

只需在您网站 HTML 页面的 </body> 标签前添加一行 JavaScript 代码即可完成接入：

<!-- 在线客服组件 -->
<script 
  src="https://cloud.400cc.cn/widget.js" 
  data-id="WK_8a3f2e" 
  async>
</script>

接入效果

引入脚本后，页面右下角将自动挂载悬浮客服图标：

• 点击展开：弹出响应式聊天窗口（默认 400×600px，移动端浏览器自动适配全屏）。
• 自动提醒：客服回复时，访客端自动显示未读消息红点徽标与声音提示。
• 最小化与恢复：访客可随时收起或重新唤起聊天窗，聊天记录在同一浏览器内自动保留。

---

3. 自定义触发按钮（用您网页中的按钮打开客服）

如果您希望点击网页中现有的导航栏「在线咨询」、商品详情页的「联系客服」按钮来打开对话框，可以使用 SDK 提供的标准 JavaScript API。

3.1 代码示例

<!-- 您的业务按钮 -->
<button type="button" onclick="openKefu()">联系在线客服</button>

<script>
function openKefu() {
  if (window.KefuWidget) {
    window.KefuWidget.open();
  } else {
    alert('客服组件正在加载中，请稍候...');
  }
}
</script>

3.2 JavaScript API 速查

方法 / 属性	说明	示例
window.KefuWidget.open()	打开客服聊天窗口	window.KefuWidget.open()
window.KefuWidget.close()	收起 / 关闭客服聊天窗口	window.KefuWidget.close()
window.KefuWidget.channelKey	获取当前生效的渠道 Key	console.log(window.KefuWidget.channelKey)

---

4. 现代单页应用接入（Vue / React / Next.js）

客服组件原生适配单页应用（SPA）。组件内部会自动侦听浏览器的路由变化（history.pushState、replaceState、popstate 以及页面 <title> 变更），无需您手写任何额外打点，客服端坐席就能实时看到访客当前正浏览哪个页面或商品。

4.1 Vue 3 / Vite 接入

直接在项目根目录的 index.html 引入（推荐）：

<!DOCTYPE html>
<html lang="zh-CN">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>企业官网</title>
  </head>
  <body>
    <div id="app"></div>
    <script type="module" src="/src/main.ts"></script>
    
    <!-- 在线客服挂载 -->
    <script src="https://cloud.400cc.cn/widget.js" data-id="WK_8a3f2e" async></script>
  </body>
</html>

若需在特定组件或登录成功后动态加载：

<script setup>
import { onMounted } from 'vue'

onMounted(() => {
  if (window.__KEFU_WIDGET_LOADED__) return
  const script = document.createElement('script')
  script.src = 'https://cloud.400cc.cn/widget.js'
  script.setAttribute('data-id', 'WK_8a3f2e')
  script.async = true
  document.body.appendChild(script)
})
</script>

4.2 React / Next.js 接入

在根组件或页面布局中引入：

import { useEffect } from 'react'

export function KefuWidget() {
  useEffect(() => {
    if ((window as any).__KEFU_WIDGET_LOADED__) return
    const script = document.createElement('script')
    script.src = 'https://cloud.400cc.cn/widget.js'
    script.setAttribute('data-id', 'WK_8a3f2e')
    script.async = true
    document.body.appendChild(script)
  }, [])

  return null
}

Next.js 推荐写法：

import Script from 'next/script'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="zh-CN">
      <body>
        {children}
        <Script
          src="https://cloud.400cc.cn/widget.js"
          data-id="WK_8a3f2e"
          strategy="lazyOnload"
        />
      </body>
    </html>
  )
}

---

5. 局部内嵌（Iframe 嵌入指定区域）

如果您不希望使用右下角悬浮球，而是希望将客服对话框固定嵌入在网页的某个指定区域、独立页面或自定义抽屉内，可以使用无边框内嵌链接：

内嵌 URL 格式

https://cloud.400cc.cn/widget/embed?channel_key=WK_8a3f2e&embedded=1

HTML 内嵌代码示例

<div style="width: 100%; height: 600px; border-radius: 8px; overflow: hidden; border: 1px solid #e5e7eb;">
  <iframe
    src="https://cloud.400cc.cn/widget/embed?channel_key=WK_8a3f2e&embedded=1"
    style="width: 100%; height: 100%; border: none; display: block;"
    allow="clipboard-write">
  </iframe>
</div>

---

6. 客服系统开箱即用的高级体验

接入后，访客与客服将自动享有以下原生能力（无需接入方额外编码）：

1. 浏览足迹感知：访客在网站上浏览不同页面或商品时，客服端工作台实时展示访客当前的访问 URL 及浏览历史轨迹。
2. 输入中即时感知与线索提取：
   • 访客在输入框输入内容时，坐席端实时显示“正在输入...”。
   • 若访客输入中包含了手机号或微信号，系统会自动识别并提取，即便访客因故提前关闭网页，客服也能及时沉淀意向线索。
3. 断网重连无损同步：由于网络切换、移动端熄屏等导致的连接断开，重新联网后会自动按消息序号拉取补齐期间的所有客服回复，不会遗漏消息。
4. 满意度评价与离线留言：客服结束会话后自动弹出满意度打分弹窗；非工作时间或无坐席在线时自动引导访客提交离线留言。

---

7. 常见问题与排查指南（FAQ）

Q1：页面右下角没有显示客服图标？

1. 打开浏览器控制台（F12 -> Console），检查是否有网络加载拦截报错。
2. 确认 <script> 标签中的 data-id 是否完整准确。
3. 检查您网站是否有更高层级的遮罩元素（客服悬浮球层级为 z-index: 2147483000）。

Q2：点击后提示“渠道不存在或已关闭”？

• 请联系客服系统管理员，在客服后台「系统设置」 -> 「渠道管理」中确认该渠道状态是否处于「已启用」状态。

Q3：网站配置了严格的内容安全策略（CSP），如何放行？

如果您的网站服务器配置了 Content-Security-Policy 响应头，请放行 cloud.400cc.cn：

Content-Security-Policy: 
  script-src 'self' https://cloud.400cc.cn;
  frame-src 'self' https://cloud.400cc.cn;
  connect-src 'self' https://cloud.400cc.cn wss://cloud.400cc.cn;
  img-src 'self' data: blob: https://cloud.400cc.cn;

Q4：手机浏览器上打开，输入框是否会被虚拟键盘遮挡？

• 客服组件已针对 iOS / Android 软键盘弹出做了视口高度（100dvh / window.visualViewport）适配。
• 请确保您网站的 <head> 中包含标准的移动端视口声明：

  <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />