跟踪代码段是一个小型的异步脚本（大小仅几 KB，通过边缘缓存的第一方路径提供），用于识别每次会话背后的组织机构。如果安装正确，您甚至感觉不到它的存在；但若安装有误，您可能会花上整整一周时间去调试为何遗漏了已识别的企业，结果却发现加载器被放进了一个延迟加载的局部组件中。本指南将帮助您避开这些误区，省下那一周的调试时间。
在粘贴代码前的三大原则
- 加载器应放置在全站 HTML 的头部（head）中。不能放在页脚，不能放在特定页面模板中，也不能放在仅在营销页面上渲染的组件中。它必须在每个页面的 head 标签内。
- 加载器默认是异步（async）的。请勿添加 defer/async 覆盖属性来改变其执行时机；我们提供的默认属性即为经过全面测试的最佳配置。
- 仅需且必须安装一次。在同一页面上放置两份加载器代码不会让您的数据翻倍——只会使请求次数翻倍，并让调试过程变得混乱。
WordPress
在 WordPress 上最整洁的安装方式是避免修改主题。您可以使用头部脚本插件（任何知名插件均可），将加载器粘贴到“scripts in head”（头部脚本）字段中，保存并清除所有页面缓存。如果您不想使用插件，可以添加一个简单的 mu-plugin 文件，以优先级 5 挂载到 wp_head，从而确保加载器排在分析标签之前。切勿将其粘贴到页面或文章正文中——WordPress 会在清理格式时将该 script 标签移除。
WordPress 特有的注意事项：如果您使用了全页缓存插件（如 LiteSpeed、WP Rocket、W3 Total Cache），请在安装后清除缓存。安装前生成的 HTML 缓存是不会包含该加载器的。
Shopify
Shopify 将主题 HTML 放在 theme.liquid 文件中。在您的 Shopify 后台，依次打开 Online Store（在线商店） → Themes（主题） → Actions（操作） → Edit code（编辑代码） → theme.liquid，将加载器紧贴着粘贴在闭合的 </head> 标签之前。保存即可。就这么简单——不需要安装应用，也不需要结账页脚本（毕竟结账流程原本也不在企业级识别的范围内）。
建议先复制一份主题
在编辑 theme.liquid 之前，请使用 Actions（操作） → Duplicate（复制）。如果出现任何问题，您可以一键还原。这个只需五秒钟的好习惯，已经拯救了无数个听从该建议的 Shopify 团队。
Webflow
依次点击 Webflow → Site Settings（网站设置） → Custom Code（自定义代码） → Head Code（头部代码）。粘贴加载器代码，保存并发布网站。该头部代码会全局应用于所有页面，这正是您所需要的。请勿将加载器粘贴到页面级别的嵌入代码中——否则您将只能跟踪那一个页面。
Google Tag Manager
GTM 也是可行的，但有两点需要注意。首先，使用自定义 HTML（Custom HTML）标签，并将触发器设置为“All Pages（所有页面）”，以确保加载器在每次网页浏览时都会运行。其次，将标签的优先级设置得足够高，使其在其他可能拖慢初始加载的分析标签之前触发。GTM 用户经常在头部叠加四五个标签；我们的加载器虽然很小，但如果您希望实现首次请求的准确识别，标签的触发顺序就至关重要。
同意模式注意事项：如果您在同意横幅后运行 GTM，并且该横幅仅在用户选择加入（opt-in）后才触发分析标签，请勿将企业级识别放在同一限制条件下——它不使用 cookie，也不在访客设备上存储数据，因此不需要相同的同意层级。请将该标签配置为与您的严格必要（strictly-necessary）标签一起立即触发。
纯 HTML / 定制技术栈
对于手动编写的网站或未在上方提及的框架，请将加载器粘贴到基础模板的 <head> 元素中——即那个会在每个页面上渲染的文件。然后重新构建并重新部署。对于静态网站生成器，加载器应放在全站布局文件中（例如：在 Next.js 中，是在应用级布局中使用 strategy="afterInteractive" 的 <Script> 标签；在 Astro 中，是 <BaseHead> 组件；在 11ty 中，是基础模板的局部组件）。如果您将其作为组件级脚本添加，则只有包含该组件的页面才会报告数据。
单页应用（SPA）——需要注意的一个细节
在 SPA 中，初始页面浏览会在页面首次加载时被加载器捕获。然而从浏览器的角度来看，随后的客户端导航并不会自动产生新的页面浏览记录。默认情况下，我们的加载器会监听 History API，因此无论后退/前进还是基于 pushState 的导航，都会被自动注册为新的页面浏览，您无需编写任何代码。如果您的 SPA 使用了绕过 History API 的非标准路由器（这很少见，但也并非没有先例），请在路由更改时调用文档中说明的小型 pageview 函数——只需三行代码，详见官方文档。
两分钟验证安装结果
验证步骤绝不可省略。请在关闭安装加载器的标签页之前进行验证；在粘贴代码后五分钟内发现并修复安装问题轻而易举，但如果在五天后才发现，那就麻烦大了。
- 在隐私/无痕窗口中打开您的网站（避免缓存资产对您造成干扰）。
- 打开开发者工具（DevTools） → Network（网络）选项卡，使用“l5e”或加载器路径进行过滤。
- 重新加载页面。您应该能看到一个对加载器的请求，紧接着是一个小型的识别信标请求。两者的状态码都应为 200。加载器的响应头中应包含带有 s-maxage 和 stale-while-revalidate 的 cache-control 字段。
- 导航到第二个页面。您应该能看到另一个识别信标被触发，而加载器不会重新下载（其状态码将为 304）。
- 返回 lead.box 仪表板，打开实时访客动态（live visitor feed），确认您的测试访问记录已显示。如果出现，说明安装完成。
常见错误——排查首选对照表
| 症状 | 可能原因 | 修复方法 |
|---|---|---|
| 完全没有实时访问记录 | 头部缺失加载器，或者放置在了错误的模板中 | 将加载器移至全站适用的头部模板中 |
| 只有部分版块有实时访问记录 | 加载器被嵌入在了页面级代码中，而非全局 | 移动至全局头部 / 主题头部文件中 |
| 加载器已加载但没有识别信标 | 同意横幅过于激进地阻止了第三方脚本 | 将横幅配置为允许严格必要的脚本；加载器不需要获取同意 |
| 每次页面浏览触发两次信标 | 加载器被安装了两次（如主题代码 + 插件/标签） | 移除其中一个 |
| 安装后首次渲染变慢 | 加载器被放置在了关键 CSS 之前 | 确认已添加 async 属性；将其放置在关键 CSS 预加载之后 |
| SPA 仅报告第一个页面 | 自定义路由器绕过了 History API | 在路由更改时调用文档说明中的 pageview() 函数 |
| 页面提供的是未包含加载器的旧版 HTML | 安装后未清除全页缓存 | 清除缓存；在无痕模式下验证 |
性能说明——边缘缓存加载器
加载器由代理到我们边缘缓存的第一方路径提供，并设置了 s-maxage=300 和 stale-while-revalidate。在实际运行中，这意味着每个边缘节点（PoP）每五分钟仅获取一次加载器，然后便从缓存中为所有后续访客提供服务。它的字节数和对渲染的阻塞影响都微乎其微，因此我们不建议在其之上再叠加额外的加载逻辑。
何时寻求帮助
如果您已经完成了验证步骤，但仍发现存在问题，我们非常希望您能在十分钟后就来联系我们，而不是拖到十天以后。请提供以下三项信息：您的网站 URL、经过加载器路径过滤的 DevTools 网络选项卡截图，以及您安装时所用平台的名称。这三项信息足以让我们在初次回复时为您诊断出几乎所有的安装问题。
Published by