绝大多数站点不用写任何代码。页面浏览进入 页面 与 来源与渠道 等报表，在网站统计里叫「浏览量」，在行为分析里以 $pageview 事件出现。

自动记录规则

脚本加载后，下面这些时机会自动记录一次页面浏览：

时机	说明
首次加载	文档解析完成（DOMContentLoaded）后记录；如果脚本加载时文档已解析完，立即记录
history.pushState / history.replaceState	脚本包装了这两个方法，调用后在下一个事件循环记录
popstate	浏览器前进 / 后退时记录
hashchange	仅在 data-hash="true" 时监听

同一个 URL 不会连续记录两次：如果新 URL 与上一次记录的 URL 相同，这次调用直接忽略。因此 replaceState 只改了 state、没改 URL 时不会多算一次浏览。

默认情况下 URL 里的 # 及其后的部分会被去掉，/docs#intro 与 /docs#faq 算同一个页面。如果你的站点用 hash 路由（例如 /#/pricing），在脚本上加 data-hash="true"，脚本会保留 hash 并监听 hashchange。

主流框架不需要额外代码

Vue Router、React Router、Next.js、Nuxt 的 history 模式都通过 pushState / replaceState 切换路由，装好脚本即可。各框架的写法见 Vue 接入指南、React 接入指南、Next.js 接入指南、Nuxt 接入指南。

参数与方法

脚本属性

data-sitestring必填

站点标识（site key），在控制台的 SDK 代码页复制。

data-hashstring默认: 不保留 hash

保留 URL 中的 hash，并在 `hashchange` 时记录页面浏览。用于 hash 路由的单页应用。

data-excludestring默认: 空

不记录页面浏览的路径，多个用英文逗号分隔。含 `*` 的规则按通配匹配，否则要求路径完全相等。例如 `/admin/*,/preview`。

data-auto-trackstring默认: 开启

设为 `"false"` 时关闭全部自动采集，包括首次页面浏览、路由跟随、停留时长、外链与下载点击、表单提交、Web Vitals 和 404 事件。之后只记录你手动调用的 `pageview()` 与 `track()`。

JavaScript 方法

window.webcount.pageview() 按当前 location 记录一次页面浏览。它不接受参数，URL 与标题都从当前页面读取。

pageview() 和自动记录走同一套规则：URL 与上一次相同时忽略，命中 data-exclude 时忽略，切换前补发上一页的停留时长。

默认与限制

• 排除路径只匹配路径部分：data-exclude 用 location.pathname 匹配，不含查询串和 hash。排除只作用于页面浏览，同一页面上的 track() 事件照常发送。
• 标题：取 document.title，最多 200 个字符。路由切换后，标题在下一个事件循环读取；如果你的框架更晚才更新标题，记录到的可能是上一页的标题，URL 不受影响。
• URL：只接受 http: / https: 页面，最长 4000 个字符。采集端统计页面时去掉查询串和末尾的 /，路径最长 512 个字符；URL 含 #/ 时把 hash 部分并入路径。
• 来源：首次加载取 document.referrer；单页应用内切换后，来源是站内上一页。
• 停留时长：页面切换、标签页隐藏（visibilitychange）或页面关闭（pagehide）时，如果当前页已停留超过 1 秒，补发一条 __leave 事件，携带停留毫秒数。
• 去重：采集端对同一访客 2 秒内重复的页面浏览只保留一条。
• 不使用 Cookie：w.js 本身不写 Cookie 和本地存储。访客如何去重见 访客、用户与身份归一。

示例

hash 路由的单页应用：

<script async src="https://app.tapcub.com/w.js" data-site="{{SITE_KEY}}" data-hash="true"></script>

排除后台与预览页：

<script async src="https://app.tapcub.com/w.js" data-site="{{SITE_KEY}}" data-exclude="/admin/*,/preview"></script>

完全手动控制页面浏览（例如路由库不使用 History API，或你想在数据加载完成后再记录）：

<script async src="https://app.tapcub.com/w.js" data-site="{{SITE_KEY}}" data-auto-track="false"></script>
<script>
  // 在你的路由完成回调里调用
  function onRouteReady() {
    if (window.webcount) window.webcount.pageview();
  }
</script>

关闭自动采集的代价

data-auto-track="false" 会同时关闭停留时长、外链与下载点击、Web Vitals 和 404 事件，这些没有单独的手动方法可以补回来。只想排除部分页面时，用 data-exclude 更合适。

响应与副作用

• 每次页面浏览向采集端点（脚本所在域名 + /api/v1/pulse）发送一条请求。优先用 navigator.sendBeacon，不可用时退回 fetch（keepalive，不带凭据）。
• 每次页面加载的第一条页面浏览改用可读取响应的 fetch，响应里带回站点配置，脚本据此决定是否加载客服组件或身份扩展脚本（w-id.js）。
• 采集端始终返回 202，被丢弃的请求也一样，所以不能用状态码判断是否入库。验证方法见 验证安装。

错误与兼容性

• 重复安装：页面上放了两份脚本时，只有第一份生效，后加载的那份检测到 window.webcount 已就绪后直接退出，不会重复计数。
• 本地开发：在 localhost、127.*、0.0.0.0、[::1] 上默认不发送数据。需要本地调试时加 data-allow-local="true"，或显式设置 data-api。即使发送了，域名不在已登记网站之列的请求也会被采集端丢弃。
• DNT / GPC：浏览器开启「请勿跟踪」或全局隐私控制时，脚本默认完全不运行。详见 CSP、拦截与网络限制。
• 静默失败：脚本内部错误一律吞掉，不会影响你的页面，也不会在控制台打印日志。
• 爬虫：带有自动化特征的浏览器（如 navigator.webdriver、无头浏览器 UA）会在请求里附带信号，由采集端判定为机器人后单独统计，见 机器人与 AI 爬虫。