【免费下载链接】analyticsjs-boilerplateExamples and best practices for using analytics.js项目地址https://gitcode.com/gh_mirrors/an/analyticsjs-boilerplate点击查看免费下载对于用 Google Analytics 做网站统计的工程师来说自定义维度Custom Dimensions往往是最容易翻车的一环维度没填值就丢行、改版后数据对不上、性能指标散落各处难汇总。开源项目 analyticsjs-boilerplate 正是为解决这些问题而生——它提供了一套可直接落地的 analytics.js 埋点最佳实践样板其中完整设计了9 个自定义维度 6 个自定义指标的采集体系覆盖页面性能、错误追踪、滚动深度等场景。本文将带你逐维拆解这套体系的设计思路。一、先搞懂自定义维度 vs 自定义指标是什么很多人分不清这两个概念先花 1 分钟建立正确认知概念作用类比自定义维度dimension给每次数据访问hit打上标签用于分类、筛选给包裹贴快递单收件人、城市自定义指标metric记录一个可求和/求平均的数值记录包裹的重量、体积以页面加载为例页面从哪个来源进入是维度文字标签页面加载耗时 3200ms是指标数字。在样板中这两套映射表分别定义在 src/analytics/autotrack.js 中const dimensions { TRACKING_VERSION: dimension1, CLIENT_ID: dimension2, // ... 共 9 个维度 }; const metrics { RESPONSE_END_TIME: metric1, // ... 共 6 个指标 }; 注意Google Analytics 后台要求先创建好维度/指标代码中的dimension1~dimension9、metric1~metric6必须与后台编号一一对应。二、9 个自定义维度逐个拆解完整的 9 维定义见 src/analytics/autotrack.js基础版 src/analytics/base.js 则是 8 维少了第 9 维编号维度名含义采集时机dimension1TRACKING_VERSION埋点版本号如1页面加载时dimension2CLIENT_IDGoogle 自动分配的客户端 ID页面加载时dimension3WINDOW_ID本次打开窗口的 UUID页面加载时dimension4HIT_ID每一次 hit 的唯一 UUID每次发送前dimension5HIT_TIME每次 hit 的时间戳每次发送前dimension6HIT_TYPEhit 类型pageview/event 等每次发送前dimension7HIT_SOURCEhit 来源pageload / 插件名发送时按场景dimension8VISIBILITY_STATE发送时页面可见性状态每次发送前dimension9URL_QUERY_PARAMS被剥离的 URL 查询参数autotrack 插件写入可以看到一个巧妙的设计9 个维度被分成两类采集时机——页面级维度1~3只在页面加载时设置一次描述这次会话是谁、用什么版本hit 级维度4~8每次发送数据前动态注入描述这一条数据本身。高手技巧 1用buildHitTask钩子给每条数据盖章hit 级维度是整套体系最精华的部分。在 src/analytics/base.js 中样板替换了 tracker 的buildHitTask方法——这是 analytics.js 提供的数据发送前最后拦截点ga((tracker) { const originalBuildHitTask tracker.get(buildHitTask); tracker.set(buildHitTask, (model) { const qt model.get(queueTime) || 0; model.set(dimensions.HIT_TIME, String(new Date - qt), true); model.set(dimensions.HIT_ID, uuid(), true); model.set(dimensions.HIT_TYPE, model.get(hitType), true); model.set(dimensions.VISIBILITY_STATE, document.visibilityState, true); originalBuildHitTask(model); }); });无论后续代码通过哪个插件发出 pageview、event 还是 timing 数据都会在发送前自动补上这 4 个字段。好处是每条 hit 有唯一HIT_ID——排查重复数据、去重统计时是硬通货HIT_TIME扣除了queueTime——数据在队列里排队的时间不算入时间戳报表更准确这是 0.2.0 版本专门修复的点见 CHANGELOG.mdVISIBILITY_STATE能帮你区分用户切后台后发来的数据过滤脏数据。高手技巧 2版本号维度改版数据不串味TRACKING_VERSION看起来不起眼却是报表排障的救命稻草。当埋点逻辑发生破坏性变更时把版本号1改为2就能在后台用维度筛选只隔离新逻辑采集的数据新旧数据互不污染。这个思路在 src/analytics/base.js 的注释中写得明明白白。三、6 个自定义指标把性能数据搬进 GA6 个指标定义在 src/analytics/autotrack.js编号指标名含义metric1RESPONSE_END_TIME服务器响应结束耗时metric2DOM_LOAD_TIMEDOM 加载完成耗时metric3WINDOW_LOAD_TIME窗口 load 完成耗时metric4PAGE_VISIBLE页面是否可见0/1metric5MAX_SCROLL_PERCENTAGE用户最大滚动深度%metric6PAGE_LOADS页面加载次数前 3 个Navigation Timing 性能三件套sendNavigationTimingMetrics 函数从performance.timing取出三个时间戳统一换算成相对 navigationStart 的毫秒数后通过一条 event 命中一次性上报const responseEnd Math.round(nt.responseEnd - navStart); const domLoaded Math.round(nt.domContentLoadedEventStart - navStart); const windowLoaded Math.round(nt.loadEventStart - navStart);这里有两个细节值得抄作业等 load 事件触发后再上报如果页面还没加载完就先挂监听避免拿到 0 值数据合法性校验allValuesAreValid会拦截浏览器偶发的 0、负数或未来时间等异常值要求0 value 6e6防止脏数据拉偏均值。后 3 个交给 autotrack 插件自动填充PAGE_VISIBLE、MAX_SCROLL_PERCENTAGE、PAGE_LOADS分别由pageVisibilityTracker和maxScrollTracker插件写入。插件初始化见 requireAutotrackPlugins其中有个实用小函数getDefinitionIndexautotrack.js#L258const getDefinitionIndex (definition) /\d$/.exec(definition)[0];它把metric5转成数字5让插件配置和维度映射表共用同一份定义避免编号写两遍、改一处漏一处。四、一个关键防坑设计(not set)兜底值Google Analytics 有个坑维度值为空的行会被直接从报表中丢弃。如果某次事件没带HIT_SOURCE整行数据可能人间蒸发。样板的解法非常朴素——在 trackCustomDimensions 中先把所有维度统一预置为(not set)Object.keys(dimensions).forEach((key) { ga(set, dimensions[key], NULL_VALUE); });之后真正有值的字段再按需覆盖。这样每条数据都有话说报表行数才可信——新手最容易忽略、但影响最大的一条实践。五、三个版本样板难度阶梯式递进项目提供了三份逐步增强的样板入口切换只需改 src/index.js 中的一行import路径版本文件特性维度/指标规模基础版src/analytics/base.js错误追踪 维度体系 性能事件8 维 / 3 指标自动追踪版src/analytics/autotrack.js增加 5 个 autotrack 插件9 维 / 6 指标多追踪器版src/analytics/multiple-trackers.jsprod/test 双追踪器隔离9 维 / 6 指标多追踪器版测试数据不污染生产报表multiple-trackers.js 定义了prod和test两组 tracker并用createGaProxy工厂生成了gaAll/gaProd/gaTest三个代理函数L87-L108gaAll(...)→ 两个 tracker 都发用于基础行为数据gaTest(...)→ 只发测试 tracker用于先在测试属性里验证新数据是否合理比如滚动深度插件就只挂在 test 上gaProd(...)→ 只发生产 trackerNavigation Timing 数据就只用它上报。这套先试后发的工作流让埋点上线像代码发布一样有了灰度验证环节。六、跑起来看看本地体验完整样板克隆仓库并安装依赖git clone https://gitcode.com/gh_mirrors/an/analyticsjs-boilerplate cd analyticsjs-boilerplate npm install npm start浏览器打开 localhost:8080按 F12 打开开发者控制台由于 index.html 加载的是analytics_debug.js调试版每条 hit 的完整参数包括所有 dimension/metric都会打印在控制台——不用后台就能看到 9 维 6 指标全部就位。⚠️ 上线前记得把analytics_debug.js换回analytics.js这一点 index.html 的注释里特意标红提醒了。七、给你的 5 条落地清单学完这套体系可以直接搬走的经验✅维度/指标集中映射用一张dimensions/metrics表管住全部编号别让dimension7散落在各文件里✅buildHitTask钩子加 hit 级字段一次钩住所有 hit零遗漏✅空值兜底(not set)防止 GA 静默丢行✅埋点版本号维度改版时用筛选器隔离新旧数据✅性能数据先校验再上报拒绝 0、负数、未来时间等异常值。这套样板代码量不大却把自定义维度怎么设计才经得起长期运营这件事讲透了——维度负责回答这条数据是谁、何时、从哪来指标负责回答有多快、多深、多少次。照着 9 维 6 指标的思路搭一套自己的埋点骨架你的 Google Analytics 报表质量会立刻上一个台阶。赞分享【免费下载链接】analyticsjs-boilerplateExamples and best practices for using analytics.js项目地址https://gitcode.com/gh_mirrors/an/analyticsjs-boilerplate点击查看免费下载相关推荐Apache Superset语义层详解如何快速定义自定义维度和指标Apache Superset语义层详解如何快速定义自定义维度和指标 Apache Superset是一个强大的开源数据可视化和商业智能平台其核心功能之一就数据可视化数据分析大数据后端前端企业应用如何实现高精度OpenCV相机标定完整的三维视觉测量指南如何实现高精度OpenCV相机标定完整的三维视觉测量指南 想要获得精确的计算机视觉测量结果 OpenCV相机标定 是必不可少的关键步骤。通过标定过程您可以计算机视觉图像处理机器学习深度学习视频处理如何快速配置AI思维助手Claude自定义思考协议完整指南如何快速配置AI思维助手Claude自定义思考协议完整指南 Thinking Claude是一个革命性的开源项目让您的Claude AI能够进行深度、系统的人工智能AI 应用提示工程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
