【免费下载链接】piwik
Matomo (Formerly known as piwik) has corrected their fallacy
Matomo（原名 Piwik）是一款开源网站分析平台，其核心 JavaScript 文件 piwik.js 就是嵌入到你网站中的跟踪代码脚本。本文带你系统掌握 piwik.js 的跟踪代码 API：从页面浏览、事件跟踪，到自定义变量（Custom Variables）、自定义维度、目标转化，覆盖"跟踪网站每一个行为"所需的完整能力。
🧩 piwik.js 是什么？工作原理一句话讲清
piwik.js 是 Matomo 前端的"数据采集器"：它记录访客的页面浏览、点击、事件、目标转化等数据，然后通过 piwik.php 接口异步上报到你自建的 Matomo 服务器。
仓库中与跟踪代码相关的核心文件：
| 文件 | 作用 |
|---|---|
| js/piwik.js | 未压缩的跟踪代码源码，包含全部 API 方法，适合阅读参考 |
| js/piwik.min.js | 压缩版，生产环境实际加载的就是它 |
| js/index.php | 可代替 piwik.js 的加载地址，支持 gzip 压缩与缓存，还能绕过部分隐私过滤插件 |
| js/README.md | 官方对 js/ 目录的部署与压缩说明 |
💡 小贴士：如果你担心隐私过滤器拦截跟踪，可以把跟踪代码中的脚本地址改为
js/目录（即js/index.php隐式路径），详见 js/README.md。
🚀 跟踪代码的标准结构
跟踪代码的核心是一个名为 _paq 的队列数组，所有 API 调用都以"推入命令"的方式完成。这是理解 piwik.js API 的关键——你不需要等待脚本加载完毕，命令会按顺序被队列执行：
var _paq = window._paq = window._paq || [];
// 设置目标站点 ID 与 Matomo 服务器地址
_paq.push(['setTrackerUrl', 'https://analytics.example.org/piwik.php']);
_paq.push(['setSiteId', 1]);
// 上报一次页面浏览
_paq.push(['trackPageView']);
脚本加载部分只需一段标准引用：
<script type="text/javascript" src="https://analytics.example.org/piwik.js"></script>
一个页面可以同时跟踪多个站点，通过 Piwik.addTracker() 注册新的 Tracker 实例，每个实例拥有独立的 siteId（对应 js/piwik.js 中的 addTracker 方法）。
📋 核心 API 速查表
以下是日常使用频率最高的 piwik.js 跟踪方法一览（全部定义于 js/piwik.js）：
| API 方法 | 用途 | 一句话说明 |
|---|---|---|
trackPageView | 页面浏览 | 手动上报一次 PV，单页应用必备 |
trackEvent | 事件跟踪 | 记录视频播放、下载、加购等行为 |
setCustomVariable | 自定义变量 | 按"访问/页面/事件"范围存储业务数据 |
setCustomDimension | 自定义维度 | 按 Matomo 后台配置的维度 ID 存值 |
trackGoal | 目标转化 | 手动触发目标（如注册成功） |
trackLink | 出站链接 | 手动记录特定链接点击 |
trackSiteSearch | 站内搜索 | 记录站内搜索关键词 |
enableLinkTracking | 自动链接跟踪 | 自动捕获出站链接与下载点击 |
setUserId | 用户 ID | 以邮箱、用户名等标识回访用户 |
setDoNotTrack | 隐私合规 | 尊重浏览器 DNT 信号 |
👀 如何跟踪每一次页面浏览
默认情况下，跟踪代码加载即自动记录一次页面浏览。但以下两种场景需要你手动调用 trackPageView：
1️⃣ 单页应用（SPA）：路由切换不刷新页面，必须在每次路由变化后手动上报：
// 例如在 React Router 的路由切换回调中
_paq.push(['trackPageView', '产品详情页']);
第一个可选参数 customTitle 可自定义页面标题，否则 Matomo 会取 HTML 的 <title>。
2️⃣ 非标准 URL 页面：用 setCustomUrl 先设定要记录的 URL，再上报 PV：
_paq.push(['setCustomUrl', 'https://example.org/checkout-step-2']);
_paq.push(['trackPageView']);
📌 判断当前页面已上报了几次 PV，可以用
getNumTrackedPageViews方法（见 js/piwik.js）。
🎯 事件跟踪：记录视频、下载、表单等"每一个行为"
事件（Event）是 piwik.js 中最灵活的跟踪原语，适合记录页面内不产生跳转的交互行为。核心方法是 trackEvent，参数结构如下：
_paq.push(['trackEvent',
'Video', // category 类别（必填）：如 Video、Download、Form
'Play', // action 动作（必填）：如 Play、Pause、Submit
'新手教程.mp4', // name 名称（可选）：具体的对象名
15, // value 数值（可选）：如播放时长、下载大小
{ 'extra': 'data' } // customData 自定义数据（可选）
]);
各参数的典型用法：
- category + action：两个必填参数，共同描述"发生了什么"。例如
category='Video'、action='Play'。源码要求二者不能为空，否则会报Error while logging event错误（js/piwik.js）； - name：被操作的对象，如视频名、文件 URL；
- value：数值型附加指标，如播放时长（秒）、下载大小（KB）；
- customData：附加键值对，会随请求一并上报到 Matomo。
在 Matomo 后台的"行为 → 事件"报表中，你可以按类别、动作、名称逐层下钻，精确到某个视频被播放了多少次。
🏷️ 自定义变量：把业务数据"贴"在每次跟踪上
setCustomVariable 允许你为访问附加业务维度的键值对（如会员等级、来源活动），签名是 setCustomVariable(index, name, value, scope)：
// 将"会员等级"存储为访问级自定义变量
_paq.push(['setCustomVariable', 1, 'member_level', 'gold', 'visit']);
关键规则（来自 js/piwik.js 的源码注释）：
| 参数 | 说明 |
|---|---|
index | 槽位编号 1~5，自定义变量最多 5 个 |
name / value | 变量名与值，都会被强制转为字符串 |
scope | 作用范围：visit（整个访问，默认）、page（仅下一次 PV）、event（仅下一次事件） |
三种作用范围（scope）的区别：
visit（访问级）：写入 Cookie，在整个访问期间持续生效，适合"登录状态、会员等级"；page（页面级）：只附加到下一次trackPageView，适合"当前页面类别"；event（事件级）：只附加到下一次trackEvent，是 Piwik/Matomo 独有的第三范围，Google Analytics 没有对应物。
配套方法还有 getCustomVariable（读取）与 deleteCustomVariable（删除）。
⚠️ 注意：Matomo 的电商功能（
setEcommerceView、addEcommerceItem等）会占用page范围的 2~5 号槽位（如_pkc、_pks等内部键），自定义变量请避开这些槽位。
📐 自定义维度：更规范的"结构化"扩展字段
如果需要在报表中长期、稳定地按某个字段切分（比如"落地页模板"），推荐使用 Matomo 后台预定义的自定义维度配合 setCustomDimension：
// 先登录 Matomo 后台创建自定义维度（编号 1）
_paq.push(['setCustomDimension', 1, 'mobile_template']);
与自定义变量的差异：
| 对比项 | 自定义变量 | 自定义维度 |
|---|---|---|
| 是否需后台预配置 | 不需要 | 需要（管理 → 自定义维度） |
| 数量上限 | 5 个槽位 | 无硬性上限 |
| 报表能力 | 辅助筛选 | 可独立成列、可排序聚合 |
setCustomDimension 设置的值不会在页面浏览后清除，会随后续所有跟踪请求发送，可用 deleteCustomDimension 移除（js/piwik.js）。
🛒 目标、链接与搜索：转化链路跟踪
手动触发目标：当用户完成注册、提交表单等转化行为时，用 trackGoal 上报（参数为目标 ID、可选收入、可选自定义数据）：
// 上报 3 号目标完成，收入 99 元
_paq.push(['trackGoal', 3, 99]);
自动链接跟踪：调用 enableLinkTracking 后，所有出站链接点击和文件下载都会被自动捕获；若页面 DOM 动态变化，需再次调用该方法让 piwik.js 重新绑定监听（js/piwik.js）。特殊场景可给特定链接单独加监听：
_paq.push(['addListener', document.getElementById('btn-download')]);
站内搜索：用 trackSiteSearch 上报用户搜索的关键词、分类与结果数，Matomo 会生成专门的站内搜索报表：
_paq.push(['trackSiteSearch', '关键词', '商品', 25]);
⚙️ 值得了解的高频配置 API
| 方法 | 用途 |
|---|---|
setUserId | 传入邮箱/用户名，跨设备识别同一用户（js/piwik.js） |
setTrackerUrl | 指定 piwik.php 跟踪接口地址 |
setSiteId | 指定站点 ID |
setCustomData | 附加任意键值对到跟踪请求 |
enableHeartBeatTimer | 心跳计时器，延长页面停留时间统计的准确性 |
enableJSErrorTracking | 上报页面 JS 报错 |
setDoNotTrack | 开启后尊重浏览器"请勿跟踪"设置，并删除已存 Cookie |
✅ 最佳实践清单
- SPA 必调
trackPageView：否则路由切换只会被记为一次浏览； - 命令尽早推入
_paq：所有push操作都可在脚本加载前执行，队列机制保证顺序； - 自定义变量用
visit范围存"身份"，用page范围存"上下文"，避免数据错位； - 合规优先：欧盟站点建议配合 Cookie 同意机制使用
setConsentGiven系列方法，并考虑开启setDoNotTrack； - 生产环境加载压缩版：默认使用
piwik.min.js；对性能敏感或需绕过拦截时，改用 js/index.php 提供的js/路径； - 不止浏览器：服务端也能用 PHP 客户端 libs/PiwikTracker/PiwikTracker.php 直接记录事件与目标，无需依赖前端。
总结
piwik.js 的 API 设计遵循"队列式、方法式"风格：_paq.push([...]) 即可调用。掌握 trackPageView（浏览）、trackEvent（事件）、setCustomVariable（自定义变量）、trackGoal（目标） 这四个核心方法，再辅以自定义维度与链接跟踪，你就能把网站的每一次点击、播放、搜索与转化都记录在案。全部方法签名与注释均可在 js/piwik.js 中查证，建议收藏备查。
【免费下载链接】piwik
Matomo (Formerly known as piwik) has corrected their fallacy
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
