# HESUPIPE AI 客服挂件 — 官网嵌入指南

给官网管理员的接入说明。不需要写代码，只需要复制粘贴一段代码。
全程约 10 分钟。

---

## 1. 嵌入代码（直接复制粘贴）

在正式开始前，请先向开发确认一件事：**客服系统部署后的域名是什么**（例如 `ai.hesupipe.com`）。
下面代码里的 `https://ai.hesupipe.com` 请替换成实际域名。

```html
<!-- HESUPIPE AI 客服挂件 开始 -->
<script
    src="https://ai.hesupipe.com/static/widget.js"
    data-position="bottom-right"
    data-color="#066fc0"
    data-title="HESUPIPE Support"
    data-whatsapp="https://wa.me/+8615937108317"
    data-email="mailto:hesu@hesuu.com"
    data-auto-invite="true"
></script>
<!-- HESUPIPE AI 客服挂件 结束 -->
```

粘贴后刷新官网任意页面，右下角应出现蓝色 "Chat with us" 胶囊按钮，即嵌入成功。

> **本地/测试环境预览**：部署前想先看效果，把 `src` 换成本地服务地址
> `http://localhost:8017/static/widget.js`（需本地启动服务）。

---

## 2. 贴到哪里（WordPress 三种主流方式，任选其一）

### 方式 A：自定义 HTML 小工具（最简单，推荐）

1. WordPress 后台 → **外观 → 小工具**
2. 找到 **自定义 HTML** 小工具，添加到 **Footer（页脚）** 区域
3. 把上面的嵌入代码整段粘贴进内容框
4. 保存，刷新官网前台页面验证

### 方式 B：主题设置里的"页脚脚本"输入框

很多商业主题自带代码注入功能：

1. **外观 → 自定义**（或 主题设置），找类似 **Footer Scripts / 页脚代码 / 跟踪代码** 的输入框
2. 把嵌入代码整段粘贴进去
3. 保存发布

> 如果主题同时有"页眉脚本"和"页脚脚本"，选**页脚**（页面加载更快）。

### 方式 C：直接编辑页脚模板 footer.php（懂一点主题编辑时用）

1. **外观 → 主题文件编辑器** → 右侧选择 **Footer (footer.php)**
2. 找到 `</body>` 标签，把嵌入代码粘贴到 `</body>` 的**上一行**
3. 点"更新文件"

> **注意**：直接改主题文件时，主题更新后改动会被覆盖。建议在**子主题（Child Theme）**里改，
> 或改用方式 A/B。

---

## 3. 可调配置说明

以下配置全部写在 `<script>` 标签上（即上面代码里 `data-xxx` 的部分），改属性值即可。
**所有配置都可省略**——省略时用默认值，默认值就是 HESUPIPE 官方配置。

| 属性 | 作用 | 可选值 / 默认值 |
|---|---|---|
| `data-position` | 挂件在页面上的位置 | `bottom-right`（默认，右下）/ `bottom-left` / `top-right` / `top-left` |
| `data-color` | 主题色（16 进制色值） | 默认 `#066fc0`（HESUPIPE 品牌蓝）。改一个色值，按钮、面板、邀请卡整套颜色自动跟着变 |
| `data-title` | 聊天窗口顶部的标题 | 默认 `HESUPIPE Support` |
| `data-whatsapp` | 挂件内 WhatsApp 按钮的跳转链接 | 默认 `https://wa.me/+8615937108317` |
| `data-email` | 挂件内 Email 按钮的跳转链接 | 默认 `mailto:hesu@hesuu.com` |
| `data-auto-invite` | 是否在访客停留约 5 秒后自动弹出邀请卡片 | 默认 `true`（弹出）。不想要自动弹卡改为 `"false"` |
| `data-theme` | 聊天窗口明暗风格 | 默认 `light`；可选 `dark` |
| `data-auto-open` | 页面打开时是否自动展开聊天窗口 | 默认 `false`（不展开）。一般不建议设 `true`，会打扰访客 |
| `data-mobile` | 移动端专用样式（圆形按钮+文字标签） | 默认 `false`。移动端页面可设 `"true"` |
| `data-avatar` | 客服头像图片地址 | 默认使用系统自带的 HESUPIPE 客服头像 |

**最常改的三个**：位置（`data-position`）、主题色（`data-color`）、WhatsApp 号（`data-whatsapp`）。

---

## 4. 主题色说明

- 默认主题色已经是 **HESUPIPE 品牌蓝 `#066fc0`**，**正常情况什么都不用配**。
- 只有当官网改版换品牌色时，才需要在 `<script>` 标签上加（或修改）`data-color` 属性，
  例如换成绿色：`data-color="#0a7d4f"`。
- 色值必须是 `#` 开头的 6 位 16 进制（如 `#066fc0`）。填错时挂件会自动退回品牌蓝并在
  浏览器控制台提示，不会显示成怪颜色。

---

## 5. 隐私政策（GDPR）配套要求

挂件的聊天窗口底部和自动邀请卡上，都会显示一行固定提示：

> By chatting, you agree to our privacy policy.

其中 "privacy policy" 链接指向 **https://hesupipe.com/privacy-policy/**。

上线前请确认：

- [x] 该隐私政策页面**真实存在且可访问**（2026-09 已验证可打开，为 HESU Technologies
  完整隐私政策页）；
- [ ] 页面内容涵盖"聊天记录用于客户联络"的说明（如现有政策未覆盖，请让法务/业务侧补充）；
- [ ] 若日后隐私政策 URL 变更（如换域名、换路径），**需通知开发修改挂件代码**——
  该链接写死在 `static/widget.js` 中，改链接不是改配置就能完成的。

---

## 6. 常见问题

**Q：贴上去没反应？**
检查 `<script>` 的 `src` 域名是否写对（必须是客服系统实际部署的域名，浏览器直接打开
`https://你的域名/static/widget.js` 应能看到一串代码）。再检查代码是否被 WordPress
编辑器自动加了转义或换行破坏。

**Q：会拖慢官网吗？**
挂件代码很小，且放在页脚不影响首屏渲染。聊天连接只在访客点击按钮后建立。

**Q：访客关掉了邀请卡还会一直弹吗？**
不会。访客点 X 或 "No Thanks" 后，本次浏览器会话内不会再自动弹出。

**Q：想同时改 WhatsApp 号码和邮箱怎么办？**
改 `data-whatsapp` 和 `data-email` 两个属性的值即可，见第 3 节表格。

---

## 7. 上线检查单

- [ ] 客服系统已在生产域名部署并可访问（`https://你的域名/health` 返回 ok）
- [ ] 嵌入代码中 `src` 已替换为生产域名
- [ ] 已按第 2 节方式之一贴入官网，前台刷新后右下角可见挂件
- [ ] 官网隐私政策页可访问（见第 5 节）
- [ ] 手机浏览器打开官网验证显示正常（建议顺手测一台 Android 和一台 iPhone）
- [ ] 发一条测试消息，确认 AI 正常回复；留下测试联系方式，确认客户经理能收到通知