7.3 安装 SDK（JavaScript Embedding）

完成站点创建之后，你需要在自己的网站中嵌入一段 JavaScript 代码（SDK），以便启用：

网站统计（Analytics）
智能客服（AI Customer Service）
FAQ 展示
与知识库联动

安装 SDK 是使用网站助手最关键的一步，但也是最简单的一步：只需要在网页中加入一段 <script> 即可，无需改动你的后端代码。

一、获取 SDK 代码

在 Pop 后台中进入：

网站助手 → 站点管理 → 选择某个站点 → 安装指引 / SDK 代码

你会看到类似如下的脚本示例：

<script
  src="https://connect.popllm.com/sdk.js"
  data-site-key="YOUR_SITE_KEY"
  data-api-url="https://api.popllm.com"
  data-lang="zh-CN"
  data-theme="auto"
></script>

其中：

src：SDK 的加载地址（由 Pop 提供）
data-site-key：你的站点唯一标识（SiteKey）
data-api-url：接口地址（通常默认即可）
data-lang：语言（如 zh-CN / en）
data-theme：主题（light / dark / auto）

你只需要 复制完整代码，粘贴到你网站的 HTML 中即可。

建议：不要随意修改 src 与 data-site-key，否则可能导致脚本无法正常工作或数据无法归属到正确站点。

二、脚本放在什么位置？

最常见的两种放置方式：

✅ 推荐方式：放在 `</body>` 前

<html>
  <head>
    <!-- 你自己的网站资源，例如 CSS、JS -->
  </head>
  <body>
    <!-- 页面内容 -->

    <!-- 在 body 结束前插入 Pop SDK -->
    <script
      src="https://connect.popllm.com/sdk.js"
      data-site-key="YOUR_SITE_KEY"
      data-lang="zh-CN"
      data-theme="auto"
    ></script>
  </body>
</html>

优点：

不会阻塞页面主内容加载
SDK 在页面加载后自动初始化

备选方式：放在 `<head>` 中（配合 `defer`）

<head>
  <!-- 其他 head 内容 -->
  <script
    src="https://connect.popllm.com/sdk.js"
    data-site-key="YOUR_SITE_KEY"
    data-lang="zh-CN"
    data-theme="auto"
    defer
  ></script>
</head>

使用 defer 可以避免阻塞 HTML 解析。适用于需要尽早初始化客服按钮的场景。

三、单页应用（SPA）中的安装方式

如果你的网站是基于 React / Vue / Angular 等 SPA 框架构建的，你仍然可以使用同样的 <script> 嵌入方式：

对于 传统模板：直接在 index.html 中添加脚本即可。
对于 服务器渲染框架（如 Next.js、Nuxt）：
- 可以在 _document / app 布局中统一注入脚本；
- 或者在布局组件中通过脚本标签插入。

提示：Pop SDK 会自动监听页面变化并上报访问，无需你手动埋点。

四、环境区分（测试 / 正式）

通常建议：

为测试环境创建一个单独的站点（如 test.example.com）
使用独立的 siteKey 与数据面板
不要在正式站点上使用测试站点的脚本

典型做法：

<!-- 正式环境使用正式站点的 siteKey -->
<script
  src="https://connect.popllm.com/sdk.js"
  data-site-key="PROD_SITE_KEY"
></script>

<!-- 测试环境使用测试站点的 siteKey -->
<script
  src="https://connect.popllm.com/sdk.js"
  data-site-key="STAGE_SITE_KEY"
></script>

这样可以保证测试数据与正式数据完全隔离，方便统计与排查问题。

五、常见安装问题排查

如果你已经嵌入脚本，但在 Pop 后台中：

看不到访客数据
看不到网站统计
智能客服按钮没有出现

可以逐项检查：

1. 浏览器控制台是否有报错？

打开浏览器开发者工具（F12 → Console），查看是否有类似：

Failed to load resource: net::ERR_BLOCKED_BY_CLIENT
sdk.js 404 / 403
CORS 相关错误

若被广告拦截插件（AdBlock 等）拦截，请尝试关闭插件或将域名加入白名单。

2. 域名是否与站点配置一致？

确认你访问的网站域名与 Pop 中配置的域名一致，例如：

站点配置：example.com
实际访问：localhost:3000 → 此时数据可能不会记入正式站点

建议：

开发期使用测试站点 + localhost
正式访问时使用真实域名进行验证

3. siteKey 是否正确？

在 Pop 后台复制时，确保没有：

多复制空格
将测试站点的 key 用在正式站点

如有疑问，可以重新复制并替换。

4. 浏览器缓存

有时旧版页面被缓存，导致脚本未更新。

可以尝试：

浏览器「清理缓存并强制刷新」（Ctrl+F5 / Cmd+Shift+R）
修改版本号或在 src 后添加查询参数：

<script src="https://connect.popllm.com/sdk.js?v=1"></script>

六、在本地开发环境中调试

你可以在本地开发环境中（http://localhost:3000 等）安装 SDK：

使用独立测试站点的 siteKey
在 Pop 后台中可以看到来自 localhost 的访客记录

这有助于你：

验证脚本是否正确执行
预览智能客服样式
验证 FAQ、知识库联动等功能

七、小结

安装 SDK 的步骤非常简单：

在 Pop 中创建站点，复制对应的 SDK 代码；
将 <script> 粘贴到你网站的 HTML（推荐放在 </body> 前）；
刷新网页，访问几次页面；
回到 Pop 后台，即可看到实时访客与网站统计；
如启用智能客服，还可以看到网站右下角的客服按钮与对话界面。