使用文档

AntDock Web SDK

AntDock Analytics Web SDK - 轻量级浏览器端数据追踪库。

获取 SDK

请使用控制台提供的安装地址或下载包。SDK 尚未在 GitHub 或 npm 公开发布。

安装

控制台的应用「接入」页提供「复制给 AI 的接入说明」，包含当前应用 ID、采集地址、所选平台的代码、SDK 文档及验收要求。可先展开查看，再交给项目中的 AI 编码工具；接入后仍需在「验证接入」确认真实、可查询的事件。网站已有 AntDock 时复用一份安装，不要同时安装 Script 与 npm 两套。需要明确同意的网站保留其真实同意流程，不由 AI 自动同意。

Script 标签 (推荐)

最简单的方式是通过 script 标签引入：

<script defer src="https://your-domain.com/static/tracker.js"
  data-app-id="your-website-id">
</script>

配置属性：

  • data-app-id: 必填，Website ID
  • data-endpoint: 可选，API 端点 (默认为 script 所在域名)
  • data-auto-track: 可选，是否自动追踪 (默认 true)
  • data-respect-dnt: 可选，遵循 DNT/GPC 隐私信号 (默认 true)
  • data-visitor-storage: 可选，persistent（默认）、session 或 none
  • data-spa-routing: 可选，单页应用的页面划分：auto（默认）、path、hash 或 url，含义见下文“SPA、归因和隐私控制”
  • data-consent-required: 可选，设为 true 时等待 antdock.setConsent(true)，同意前不读取配置、不写入标识、不采集；同意前调用的 trackEvent 等命令只在页面内存中暂存（最多 100 条），同意后补发，拒绝或撤回即丢弃。撤回同意调用 antdock.setConsent(false)。

忽略本浏览器与本地调试

在网站任意页面加 ?antdock=ignore（已有查询参数时用 &antdock=ignore）即可在该域名的 localStorage 写入 antdock_ignore。SDK 在初始化前处理并移除这个参数，保留其他参数、hash 和历史状态；标记存在时不读取配置、不发送数据，也不替换 fetch/XHR。用 ?antdock=track 删除标记并恢复采集。控制台「应用详情 → 接入与设置 → SDK 集成」提供这两个链接。只影响当前浏览器和当前域名，不影响网站其他访客。

localhost、127.0.0.1、::1、*.localhost、*.local 和 file: 地址默认不采集，也不输出控制台信息。确需本地采集时，在 SDK 的 script 标签上加 data-allow-local；忽略标记仍优先。验证接入请使用线上地址；需要排除已有浏览器标记的影响时，用隐身窗口访问线上地址。

DevTools 的 Network 过滤框输入 -domain:<采集域名>（例如 -domain:antdock.com）可隐藏该域名的采集请求。过滤只影响调试面板的显示，不阻止采集；SDK 无法使网络请求从 DevTools 中不可见。

批量发送与当前在线会话

普通事件与保活合并为每 30 秒最多一个请求。首个浏览立即发送；批次达到 batchSize 时提前发送。首个浏览、批次满、显隐切换、配置变更和失败重试是频率上限的例外。后台页面只在离开时发送一次状态，随后停止发送；返回可见或从 BFCache 恢复时立即上报。

在线指此刻有可见页面的会话，多标签页算一个，后台标签页不算。页面可见且 30 分钟内有操作，或有媒体在播放时，每 30 秒保活；连续 30 分钟无操作且无媒体播放时停止保活，恢复操作立即补发。关闭/隐藏使用离开状态；崩溃或网络丢失无法确认离开时，最后一次可见状态 75 秒后过期。在线状态与历史 PV/UV、停留时长心跳分开；不能把这一指标叫作人数。移动端和小程序未发送 presence 的来源仍按浏览/心跳后 5 分钟计在线。

配置只在初始化时拉取，随后采集成功响应的 configVersion 变化才刷新。关闭采集后，本页不再轮询以重新开启；重新开启设置后刷新网站页面。配置和采集连续三次网络失败后，本页停止发送，并在 sessionStorage 暂停后续页面初始化 30 分钟；已收到响应的 429/503 继续遵循 Retry-After，不计作网络失败。退出 Beacon 没有送达确认；断网时通过在线过期处理。

npm 接入

当前提供可直接安装的版本包，尚未发布到公共 npm registry。

// npm install https://antdock.com/static/sdk/antdock-tracker-1.0.17.tgz
import antdock from '@antdock/tracker'

antdock.init({ appId: 'your-website-id', endpoint: 'https://antdock.com' })

自己部署 AntDock 时，将 endpoint 换成统计服务的地址。

页面点击视图

在 AntDock 的“点击分析”中选页面，点击“在页面上查看”。新版脚本接入自动支持；npm 接入请升级到 1.0.6 或之后版本并部署。站点 CSP 需要允许 endpoint 的脚本和 API 请求。

工具按需加载，仅在主动打开私人查看链接的浏览器中显示。链接只读、限定完整页面地址，15 分钟失效。查看期间暂停本次浏览的采集；关闭后刷新网站恢复。普通访客不下载查看工具。

默认根据元素标识或结构匹配当前页面，不还原历史个性化内容。旧记录和无法匹配的元素保留为列表；结构匹配不代表内容相同。对动态列表或 A/B 实验，可选地提供不含个人信息的稳定标识和页面版本：

<html data-antdock-page-version="release-2026-10">
<button data-antdock-key="signup" data-antdock-label="开始注册">开始注册</button>

元素标识须以英文字母开头，最多 64 个英文字母、数字、下划线或连字符，并在页面中唯一；版本最多 80 个英文字母、数字、下划线、连字符、点或冒号。输入值和任意 DOM 文本不会用于采集定位；查看工具可在本地读取当前按钮名称以帮助识别，不会上传它。

手动集成

如需更多控制，可以将 SDK 源码复制到您的项目中：

  1. 复制 src/ 目录下的所有文件
  2. 在您的项目中引入使用
import { AntDockTracker } from './antdock'

const antdock = new AntDockTracker()
antdock.init({
  appId: 'your-website-id',
  endpoint: 'https://your-domain.com'
})

快速开始

初始化

antdock.init({
  appId: 'your-website-id',
  endpoint: 'https://your-domain.com',
  autoTrack: true,        // 自动追踪页面
  respectDNT: true,       // 默认遵循 DNT 和 GPC
  visitorStorage: 'persistent', // 用于识别同一浏览器的新老访客
  transport: 'auto',       // 默认 fetch-first，可识别服务端失败并重试

  enableScroll: true,    // 滚动深度追踪
  enableError: true,      // 错误追踪
  enablePerformance: true,// 性能追踪
  debug: false            // 调试模式
})

页面追踪

// 自动追踪 (默认启用)
// 或手动追踪
antdock.trackPageView('/home')

antdock.trackPageView('/product/detail', {
  product_id: '12345'
})

SPA、归因和隐私控制

默认（spaRouting: 'auto'）在 origin + pathname 或 Hash 路由（#/page、#!/page）变化时自动记录 PV；目录锚点（#section）、搜索筛选同步到 query 或 Hash 路由里的 ? 参数不重复计算。只按路径划分用 'path'，任何 Hash 变化都算新页面用 'hash'，确实需要完整 URL 划分的应用使用 'url'。Script 接入用 data-spa-routing 设置。标题在路由更新后的下一任务读取；框架异步获取标题时可关闭 autoTrack，在页面渲染完成后手动记录。

路径统计和完整 URL 点击视图的范围不同：完整 URL 视图只归因到该 URL 有页面浏览记录的会话。同页改变 query/hash 而没有新 PV 的点击仍保留在统计中，但可能无法归因或绘制；若这些变化实际代表不同页面，请显式使用 spaRouting: 'url' 或 'hash'。不把另一个 URL 的画面或分母借来填充热力图。

来源和 UTM 按同一应用、同一会话保存。persistent 访客在标签页间共享首次归因；session 与 none 只保存在当前标签页。新会话不沿用旧来源。事件的 referrer 始终是该页面的 document.referrer；会话首个外部来源另放在 source.referrer，由服务端统一分类。搜索词只使用搜索引擎实际提供的 referrer 参数；隐藏词保持未知。AI 引流在外部来源中显示 ChatGPT、Perplexity 等平台，不推断未提供的来源。

已知的 code、token、password、email 等 URL 参数默认脱敏；路由、普通筛选和 UTM 保留。自定义敏感字段、错误内容、用户身份及业务属性仍需站点依据实际数据配置过滤：

antdock.init({
  appId: 'your-website-id', endpoint: 'https://antdock.com',
  consentRequired: true,
  ignoreUrls: ['/account/reset', /\/internal\//],
  ignoreErrors: ['Known noncritical error'],
  beforeSend(event) {
    delete event.userId
    return event // return null to drop; throwing also drops the event
  },
})
// 在站点自己的同意管理回调中调用；SDK 不会自动替站点取得同意。
antdock.setConsent(true)
// 撤回后停止采集并清除本浏览器的追踪标识和待发队列。
antdock.setConsent(false)

beforeSend 在事件入队、写入重试存储之前执行。控制台设置不能放宽显式的本地 DNT、访客存储与过滤规则。撤回同意不能撤回此前已发送的数据，也不代替服务端访客删除功能。

配置确认后首个 PV 立即发送；冷启动仍需等待控制台开关，不能保证配置返回前就离开的访问被统计。首次读取配置失败时进行有限退避重试（遵循 Retry-After）；连续三次网络错误后暂停，不再轮询；服务端缓存已确认的开关，数据库短时故障期间仍可返回。关页使用 text/plain Beacon，并在拒绝入队时尝试 keepalive fetch，按字节拆批；浏览器共享 keepalive 配额、网络断开和系统直接终止仍可能丢失，Beacon 入队不等于服务端已收到。表单离开使用 pagehide，切换标签页不会被误判为放弃；系统直接杀死页面仍无法保证记录。

事件追踪

antdock.trackEvent('button_click', {
  button_id: 'submit'
})

antdock.trackEvent('purchase', {
  order_id: 'ORD-12345',
  amount: 99.99
})

电商事件

antdock.trackEcommerce({ action: 'purchase', transactionId: 'ORD-12345', revenue: 99.99, currency: 'CNY' })

用户标识

antdock.identify('user_123', {
  email: 'user@example.com',
  name: '张三'
})

API

init(config)

初始化追踪器。Script、npm 默认导出和 new AntDockTracker() 都会先读取一次控制台设置，其后由采集响应中的版本变化触发同步开关。首次配置加载失败时暂不采集，之后自动重试；无需重新安装 SDK。npm 安装请设置 endpoint 为 AntDock 服务地址。

页面、点击、滚动、错误、性能、请求、媒体和可识别的电商行为默认开启。通用网页无法自动知道真实订单支付和业务用户身份：请分别在业务成功后调用 trackEcommerce 和 identify。

trackPageView(path?, properties?)

追踪页面访问。

trackEvent(name, properties?)

追踪自定义事件。

identify(userId, traits?)

识别用户身份。

reset()

重置用户身份。

flush()

立即发送队列中的事件。

enable() / disable()

启用/禁用追踪。

配置选项

选项 类型 默认值 说明
appId string - 必填，网站 ID
endpoint string 当前域名 API 端点
autoTrack boolean true 自动追踪页面
enableScroll boolean true 启用滚动追踪
enableError boolean true 启用错误追踪
enablePerformance boolean true 启用性能追踪
batchSize number 50 批量大小
flushInterval number 30000 批次间隔 (ms)
debug boolean false 调试模式

安装来源

以控制台和本文列出的安装地址为准。

版本与诊断（1.0.15）

release: '2026.10.11' 关联控制台版本记录和私有 Source Map。data-release 用于 Script 安装。INP 默认包含标签结构和输入等待、处理、绘制延迟，不发送元素文本、ID 或输入值。

enableBreadcrumbs: true（Script：data-breadcrumbs="true"）开启最多 20 条页面内存操作轨迹，出错时发送路径和 API 状态，不记录请求体、表单值或用户文字。enableLongTasks: true（data-long-tasks="true"）在离开页面时发送长任务次数与时长。两项默认关闭，beforeSend 仍在持久化前执行，可丢弃整个事件。

会话回放（1.0.16）

默认关闭，需要在网站设置启用并保存，再在本地设置 enableReplay: true 或 Script 的 data-replay="true"；一键复制代码会反映已保存的选择。两处均允许、配置已确认且同意要求满足后，才从采集域名加载独立的 /static/replay-recorder.js。主 SDK 不包含录制库，普通统计不会下载它。

录制与发送前始终遮罩页面文本和输入值，移除 URL、表单值、业务属性与主动资源；可以用 .rr-block 或 data-antdock-private 阻止一个区域及其子节点的录制。图片、画布、视频、音频、内嵌页面、可编辑区域不录制。样式仅保留不含资源 URL、内容表达式与引号文本的部分，复杂页面可能出现样式缺失。CSS 类名和页面路径属于元数据，仍可能含有业务信息，站点应在敏感页面设置 ignoreUrls、遮挡区域或关闭回放。

每个页面文档最多录制 5 分钟 / 约 900 KiB，序列化分段上传，不写浏览器持久存储。网络失败有限重试；关页、超限或无法传输时可能缺段。DNT/GPC、采样、ignoreUrls 和同意控制继续生效；进入忽略页面、重置身份、撤回同意、禁用或销毁立即停止并丢弃未发送内容。beforeSend 面向统计事件，不接收回放；回放采用独立的固定遮罩规则。

网站详情 → 访客与流量 → 会话回放提供播放、暂停和时间定位。回放仅向工作空间所有者、管理员与成员开放，查看/删除进入活动日志，公开报告与 Viewer 不含回放。回放独立保留 7 天；每网站在保留窗口内最多 200 段 / 16 MiB，每工作空间额度由套餐分配（免费版 200 段 / 16 MiB，Starter 400 段 / 32 MiB，Pro 1600 段 / 128 MiB，Team 3200 段 / 256 MiB，Business 6400 段 / 512 MiB，按未压缩数据计），各工作空间额度互不占用，满额停止接收而保留已存内容。后台每 5 分钟清理到期数据。管理员可删除单段，访客删除和应用/工作空间删除也清理回放。

第一方代理需同时转发 /static/replay-recorder.js 和 /api/collect/replay。不要公开导出原始录制，也不要放宽播放器的 sandbox 或网络限制。录制模块基于 rrweb 官方录制与回放 API。

框架接入和 SSR 示例见 frameworks.md。包的 endpoint 必须显式配置；品牌域名与采集域名可分离，无需改变包名。npm 尚未发布时仍使用上述 tgz，不能把未发布的版本写为公共 registry 安装说明。

可选诊断模块（1.0.17）

enableBreadcrumbs 和 enableLongTasks 默认关闭。配置及同意确认后，有对应开关才下载 /static/diagnostics.js；撤回同意、关闭或重新初始化会停止观察并清空轨迹。模块加载完成前的轨迹不回补，下载失败不影响常规统计。自建采集代理需要同时转发这个静态地址。

回放内容保存在服务端私有存储目录 REPLAY_STORAGE_PATH（默认 /app/data/replays），数据库只保存元数据。Docker Compose 已挂载持久目录；私有部署备份与搬迁时需要一起保留这个目录。目录禁止公开访问。云对象存储尚未接入。

Chrome 调试调用栈

浏览器包提供 tracker.js.map，全部 SDK 源文件标为忽略列表。Chrome 默认设置下，控制台错误栈和暂停调用栈折叠 SDK 帧，网站源码位置仍保留；可在 DevTools 开启“显示忽略的帧”查看完整栈。Network 请求仍可见，需要按前面的域名过滤。

伙伴站点Around the web

实用工具与技术笔记，继续探索。Tools and ideas for your next project.