🌐 网站/H5接入文档

3分钟完成网站接入，支持普通网站、SPA单页应用、各类CMS系统

网站/H5接入

网站JS SDK支持所有现代浏览器，自动采集页面浏览、停留时长、来源、设备等核心数据，gzip压缩后仅约2KB。

💡 前置条件：请先在后台添加站点获取 Tracking ID（格式如 tid_xxxxxxxxxx）。

基础接入

将以下脚本标签添加到你网站所有HTML页面的 </body> 标签之前即可：

html 
<!-- 澄泓统计 SDK -->
<script async defer 
  data-tid="你的TrackingID" 
  src="https://your-domain/t.js">
</script>

参数说明：

  • async defer：异步加载脚本，不阻塞页面渲染
  • data-tid：替换为你在后台获取的 Tracking ID
  • src：替换为你的统计服务部署域名
✅ 安装位置：必须放在 </body> 标签之前，不要放在 <head> 中，确保不影响首屏加载速度。

高级选项

通过 data-* 属性可以配置高级功能：

1. 严格同意模式（GDPR合规）

启用后，SDK不会立即上报数据，直到用户明确同意后才开始采集：

html 
<script async defer 
  data-tid="你的TrackingID" 
  data-consent="explicit"
  src="https://your-domain/t.js">
</script>

用户同意后调用以下方法启动采集：

js 
// 用户点击同意隐私政策后调用
window.lightAnalytics.grantConsent();

2. SPA单页应用自动模式

对于React/Vue/Angular等单页应用，启用自动路由监听：

html 
<script async defer 
  data-tid="你的TrackingID" 
  data-spa="auto"
  src="https://your-domain/t.js">
</script>
⚠️ 注意：启用 data-spa="auto" 后，SDK会自动监听 pushState 和 replaceState 事件，无需手动上报页面浏览。

SPA手动上报

如果你需要更精细的控制，可以关闭自动模式，使用JS API手动上报：

js 
// 手动上报页面浏览（在路由切换完成后调用）
window.lightAnalytics.trackPageview();

// 上报自定义事件
// name: 事件名称，字符串类型
// props: 事件属性，可选的对象类型
window.lightAnalytics.trackEvent(name, props);

自定义事件示例

例如追踪按钮点击、表单提交、购买转化等行为：

js 
// 追踪按钮点击
document.getElementById('hero-cta').addEventListener('click', function() {
  window.lightAnalytics.trackEvent('button_click', {
    location: 'hero',
    text: '立即注册',
    color: 'primary'
  });
});

// 追踪表单提交
document.getElementById('contact-form').addEventListener('submit', function() {
  window.lightAnalytics.trackEvent('form_submit', {
    form_id: 'contact',
    has_email: true
  });
});

// 追踪购买转化
function trackPurchase(amount, productId) {
  window.lightAnalytics.trackEvent('purchase', {
    amount: amount,
    product_id: productId,
    currency: 'CNY'
  });
}

性能监控

SDK自动采集Web Vitals核心性能指标，无需额外配置：

  • LCP (Largest Contentful Paint)：最大内容绘制，衡量加载性能
  • FID (First Input Delay)：首次输入延迟，衡量交互性
  • CLS (Cumulative Layout Shift)：累积布局偏移，衡量视觉稳定性
  • FP (First Paint)：首次绘制
  • FCP (First Contentful Paint)：首次内容绘制
  • TTFB (Time to First Byte)：首字节时间
📊 数据查看：性能数据在后台的「性能监控」菜单中查看，提供各指标的达标率和分布直方图。

反广告拦截建议

部分广告拦截插件可能会阻止默认路径 /t.js 的加载。建议采取以下措施提高数据准确率：

方案1：重命名脚本路径

在你的服务器/CDN上将脚本文件重命名为不显眼的路径，例如：

html 
<!-- 将 t.js 重命名为其他名称，例如 static.js、app.js、analytics.min.js 等 -->
<script async defer 
  data-tid="你的TrackingID" 
  src="https://your-domain/static.js">
</script>

方案2：Nginx反向代理

通过Nginx将脚本路径代理到同域名下，完全避免被拦截：

nginx 
location /js/collect.js {
    proxy_pass https://your-analytics-domain/t.js;
    proxy_set_header Host your-analytics-domain;
}

location /api/collect {
    proxy_pass https://your-analytics-domain/api/collect;
    proxy_set_header Host your-analytics-domain;
}

CMS系统接入

对于WordPress、DedeCMS、帝国CMS、PHPCMS等内容管理系统，无需安装插件，直接插入脚本到模板即可。

WordPress接入

登录WordPress后台，进入「外观」→「主题编辑器」，找到 footer.php 文件，在 </body> 前插入脚本：

html 
<?php wp_footer(); ?>
<!-- 澄泓统计 -->
<script async defer 
  data-tid="你的TrackingID" 
  src="https://your-domain/t.js">
</script>
</body>
</html>

DedeCMS/织梦CMS接入

在后台「模板」→「默认模板管理」中找到 footer.htm，同样在 </body> 前插入脚本即可。

其他CMS

所有CMS系统原理相同：找到全站公共的底部模板文件（通常命名为footer、foot、bottom等），在 </body> 标签前插入上述脚本代码即可。

⚠️ 验证安装：插入代码后，访问你的网站，打开浏览器开发者工具（F12）→ Network，刷新页面，检查是否有对 t.js 和 collect 的请求，且状态码为200即表示接入成功。