213 lines
7.5 KiB
Markdown
213 lines
7.5 KiB
Markdown
# 在线客服 Web 端接入指南
|
||
|
||
本文档面向接入在线客服的网站开发与运维人员，帮助您在 1 分钟内将客服系统集成至您的企业官网、电商商城、Web 业务系统或单页应用（SPA）中。
|
||
|
||
---
|
||
|
||
## 1. 接入前准备
|
||
|
||
您只需要向客服系统管理员获取一个专属的 **渠道标识（Channel Key）**：
|
||
|
||
| 参数 | 说明 | 示例 |
|
||
| :--- | :--- | :--- |
|
||
| **服务地址** | 客服系统统一入口 | `https://cloud.400cc.cn/` |
|
||
| **渠道标识（data-id）** | 您企业专属的渠道密钥 | `WK_8a3f2e` |
|
||
|
||
> 💡 **获取方式**：登录客服工作台 -> 左侧菜单「系统设置」 -> 「渠道管理」 -> 复制您渠道的专属代码（其中的 `data-id` 即为您的 Channel Key）。
|
||
|
||
---
|
||
|
||
## 2. 快速接入（标准网页 / HTML）
|
||
|
||
只需在您网站 HTML 页面的 `</body>` 标签前添加一行 JavaScript 代码即可完成接入：
|
||
|
||
```html
|
||
<!-- 在线客服组件 -->
|
||
<script
|
||
src="https://cloud.400cc.cn/widget.js"
|
||
data-id="WK_8a3f2e"
|
||
async>
|
||
</script>
|
||
```
|
||
|
||
### 接入效果
|
||
引入脚本后，页面右下角将自动挂载悬浮客服图标：
|
||
* **点击展开**：弹出响应式聊天窗口（默认 400×600px，移动端浏览器自动适配全屏）。
|
||
* **自动提醒**：客服回复时，访客端自动显示未读消息红点徽标与声音提示。
|
||
* **最小化与恢复**：访客可随时收起或重新唤起聊天窗，聊天记录在同一浏览器内自动保留。
|
||
|
||
---
|
||
|
||
## 3. 自定义触发按钮（用您网页中的按钮打开客服）
|
||
|
||
如果您希望点击网页中现有的导航栏「在线咨询」、商品详情页的「联系客服」按钮来打开对话框，可以使用 SDK 提供的标准 JavaScript API。
|
||
|
||
### 3.1 代码示例
|
||
```html
|
||
<!-- 您的业务按钮 -->
|
||
<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` 引入（推荐）：
|
||
```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>
|
||
```
|
||
|
||
若需在特定组件或登录成功后动态加载：
|
||
```vue
|
||
<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 接入
|
||
在根组件或页面布局中引入：
|
||
```tsx
|
||
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 推荐写法：
|
||
```tsx
|
||
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 格式
|
||
```text
|
||
https://cloud.400cc.cn/widget/embed?channel_key=WK_8a3f2e&embedded=1
|
||
```
|
||
|
||
### HTML 内嵌代码示例
|
||
```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`：
|
||
```http
|
||
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>` 中包含标准的移动端视口声明：
|
||
```html
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />
|
||
```
|