前端CMS【免费下载链接】wp-calypsoThe JavaScript and API powered WordPress.com项目地址https://gitcode.com/gh_mirrors/wp/wp-calypso点击查看免费下载本指南以 client/lib/analytics/docs/tracks.md 及其迁移目标 packages/calypso-analytics/README.md 为核心系统讲解 wp-calypso 中基于 Automattic Tracks 体系的事件埋点方案如何通过automattic/calypso-analytics包的recordTracksEvent记录事件、如何通过 Redux Analytics Middleware 以无副作用的方式接入、以及事件/属性命名规范与源码级的校验规则。读完本文你将掌握在 Calypso 项目中正确、合规地埋点并保证事件可被 Tracks 收录的完整技术路径。文档定位tracks.md 已迁移至 calypso-analytics 包仓库中的 client/lib/analytics/docs/tracks.md 本身只有一行内容——它声明 Tracks 相关能力已整体迁移到automattic/calypso-analytics这个 npm 包并指向该包的 README.md。这是 wp-calypso 将通用分析能力从client/应用层剥离、下沉到packages/可复用包的典型示例。从源码结构看packages/calypso-analytics包的核心导出集中在 src/index.ts它统一 re-export 了以下能力事件记录recordTracksEvent、recordTracksPageView、recordTracksPageViewWithPageParams初始化与用户识别initializeAnalytics、identifyUser、getCurrentUser、setCurrentUser跟踪偏好与隐私getTrackingPrefs、setTrackingPrefs、getDoNotTrack、isRegionInCcpaZone、isCountryInGdprZone推荐流埋点recordTrainTracksRender、recordTrainTracksInteract、getNewRailcarId通用属性注入getGenericSuperPropsGetter站点上下文withSiteContext、NO_SITE_CONTEXT。包内还包含train-tracks.ts推荐结果曝光/点击跟踪、page-view-params.ts页面浏览上下文参数以及utils/下若干隐私与网络工具。其中当前版本包的 README 明确声明“Currently this package supports calls to Tracks only”即该包现阶段只承载 Tracks 一种分析通道。快速上手recordTracksEvent 记录事件最直接的埋点方式是从包中导入recordTracksEvent并调用import { recordTracksEvent } from automattic/calypso-analytics; recordTracksEvent( calypso_signup_step_start, { step: a_nice_step } );第二个参数properties为可选的事件属性对象用于携带事件的业务上下文。官方 README 给出的典型场景是注册流程中的分步埋点例如在某个步骤开始时记录calypso_signup_step_start并附上step属性标明当前步骤。如果需要在事件中附带更丰富的元数据如当前用户、站点信息则需要先初始化模块——README 推荐的流程是在应用启动对应源码 client/boot/common.js 的setupMiddlewares见 client/boot/common.js#L264阶段调用一次initializeAnalytics之后再在组件中正常埋点import { initializeAnalytics, recordTracksEvent } from automattic/calypso-analytics; // 应用启动时仅需调用一次传入当前用户与 superProps 生成器 // ... client/boot/common.js initializeAnalytics( currentUser, superProps ); // 在你的组件中 recordTracksEvent( calypso_do_thing, { extra: info } );源码视角一次 recordTracksEvent 调用内部发生了什么recordTracksEvent的真正实现位于 src/tracks.ts其完整执行链路包括附加用户语言若存在当前用户且其带有localeSlug自动把user_lang属性写入事件属性跟踪偏好闸门调用getTrackingPrefs()读取 cookie 中的隐私偏好若buckets.analytics为false事件被直接丢弃debug 日志会说明“Analytics has been disabled”开发环境校验非生产环境下对事件名与属性名做合法性检查并输出console.error详见下文“命名规范”一节事件源校验事件名必须带有合法来源前缀calypso、jetpack、remotedatablocks、wpcom_dsp_widget否则不进入 Tracks 队列除非事件名列入了EVENT_NAME_EXCEPTIONS白名单superProps 合并若设置了_superProps生成器会用它基于事件属性生成一批全局属性并合入合并到新对象不修改调用方传入的对象剔除 undefined 属性值为undefined的属性会被过滤掉这也是一种“删除属性”的惯用技巧——把不想上报的属性设为undefined即可入队与事件广播通过pushEventToTracksQueue([ recordEvent, eventName, eventProperties ])推入window._tkq全局队列同时analyticsEventsEventEmitter发出record-event事件供监听器使用。其中window._tkq队列由 tracks.ts 中加载的外部脚本//stats.wp.com/w.js消费加载结果保存在_loadTracksResultPromise 中可通过getTracksLoadPromise()获取供需要等待脚本就绪的场景使用。推荐路径通过 Analytics Middleware 埋点README 明确建议除非有强烈理由直接调用recordTracksEvent否则应使用 Analytics Middleware即 client/state/analytics。原因在于 Middleware 没有任何浏览器直接依赖不会给使用它的模块的单元测试带来复杂度——事件只是普通 Redux action测试时无需真实浏览器环境。import { recordTracksEvent } from calypso/state/analytics/actions; dispatch( recordTracksEvent( calypso_checkout_coupon_apply, { coupon_code: abc123 } ) );中间件的分发机制行动创建器 client/state/analytics/actions/record.js 将 Tracks 事件封装为一个带meta.analytics元数据的 Redux actionexport const recordTracksEvent ( name, properties ) recordEvent( tracks, { name, properties } );对应的recordEvent( service, args )会构造{ type: ANALYTICS_EVENT_RECORD, meta: { analytics: [ { type, payload } ] } }结构的 action。这个 action 被 client/state/analytics/middleware.js 中的dispatcher拦截它遍历action.meta.analytics按type分发到对应的服务处理器tracks服务最终调用recordTracksEvent( name, properties )。同一中间件还统一处理了 GAgaRecordEvent、Facebook 转化trackCustomFacebookConversionEvent、AdWords 再营销trackCustomAdWordsRemarketingEvent、页面浏览recordPageView与 MC 统计bumpStat并支持通过ANALYTICS_TRACKING_ON加载 HotJar / Survicate 等工具——也就是说Tracks 只是该中间件多通道分析能力中的一路但本文聚焦 Tracks。这种“action 声明意图、中间件执行副作用”的设计让业务代码保持纯净也让测试可以只断言 action 结构而无需触碰 DOM。初始化与 superProps全局属性的注入事件除了业务属性外通常还需要一批与用户、环境、站点相关的全局属性这些由 superProps 生成器在事件入队前合并对应 tracks.ts 中的_superProps( eventProperties )调用。Calypso 应用层在 client/lib/analytics/init.js 中封装了对initializeAnalytics的调用并在初始化完成后、存在匿名用户 ID 时动态加载 Floodlight 别名上报模块而真正的 superProps 实现位于 client/lib/analytics/super-props.js它基于 Redux store 的当前状态生成const superProps { environment: process.env.NODE_ENV, environment_id: config( env_id ), site_count: getCurrentUserSiteCount( state ) || 0, site_id_label: wpcom, client: config( client_slug ), }; // 浏览器环境下追加 // vph / vpw视口宽高、getConnectionSpeedData()网络连接速度数据同时只要事件发生在站点上下文中或显式携带了blog_id属性superProps 还会补充 Tracks 约定的blog_id、blog_lang、site_plan_id等字段——注意 Tracks 使用blog_id而非site_id与blog_lang而非site_language来标识站点。对于/reader路径等场景则会根据 should-report-omit-blog-id.js 的规则省略被选中站点避免把“正在阅读的站点”与“用户选中的站点”混淆。如果不想依赖 Calypso 应用层的实现包本身也提供了无状态的通用版本getGenericSuperPropsGetter( config )见 src/tracks.ts它只注入environment、environment_id、site_id_label、client以及浏览器视口与连接速度数据。初始化时identifyUser会将用户身份用户 ID 与用户名通过window._tkq的identifyUser指令同步给 Tracks见 src/tracks.ts用户数据中的 PIIID、用户名、邮箱会先经 SHA-256 哈希src/utils/hash-pii.ts后存入内存原始邮箱等字段不会进入事件。命名规范不符合规则的事件将被丢弃README 用专门一节强调命名规范这是 Tracks 埋点能否被收录的关键前提源自 Calypso 的事件名必须以calypso_前缀开头事件名与属性名中的每个 token 必须用下划线_分隔不以calypso_开头、token 间使用空格或连字符、或采用驼峰命名的事件会被直接丢弃为了在按字母排序的事件列表中聚合相似事件动词应放在事件名的末尾calypso_cart_product_add calypso_cart_product_remove如果用calypso_add_cart_product与calypso_remove_cart_product它们会在全量事件列表中彼此分开不利于分析。末尾动词应使用非变形形式如add、remove、view、click而不是adds、added、adding这些规则不适用于属性名除了 token 用下划线分隔这一条所以coupon_code这样的属性名完全没问题。源码级的校验规则上述规范在 src/tracks.ts 中有可验证的硬实现const ALLOWED_EVENT_SOURCES [ calypso, jetpack, remotedatablocks, wpcom_dsp_widget ];事件名校验函数isValidEventName使用正则^${ eventSource }(?:_[a-z0-9]){2,}$进行匹配src/tracks.ts它要求事件名满足合法来源前缀 至少两个下划线分隔的小写字母数字 token。例如calypso_signup_step_start可以拆为calypsosignupstepstart符合要求而calypso_thing仅一个 token会被判为非法。事件源前缀的检查在isValidEventSource中单独执行不匹配且不在EVENT_NAME_EXCEPTIONS白名单内的事件不会进入队列。EVENT_NAME_EXCEPTIONSsrc/tracks.ts是为跨产品/历史事件保留的豁免名单例如a8c_cookie_banner_ok、wcadmin_storeprofiler_payment_login、wpcom_unified_admin_page_view等它们不需要calypso_前缀。属性名校验同样严格开发环境下属性名不匹配/^[a-z_][a-z0-9_]*$/会输出错误提示src/tracks.ts同时存在一组 Tracks 保留属性名TRACKS_SPECIAL_PROPS_NAMES [ geo, message, request, geocity, ip ]src/tracks.ts使用这些名字的属性会被 Tracks 服务端覆盖必须避免嵌套对象属性值为对象同样不被支持会直接导致该事件无法记录src/tracks.ts。页面浏览事件recordTracksPageView除业务事件外Tracks 还支持页面浏览级别的埋点。包导出recordTracksPageView( urlPath, params )与recordTracksPageViewWithPageParams( urlPath, params )src/tracks.tsimport { recordTracksPageView } from automattic/calypso-analytics; recordTracksPageView( /me/account, { /* 额外属性 */ } );页面浏览事件会统一记录为calypso_page_view并自动附带do_not_track根据浏览器 DNT 信号src/utils/do-not-track.ts兼容window.doNotTrack与navigator.doNotTrack置 1 或 0path当前 URL 路径build_timestamp当全局存在window.BUILD_TIMESTAMP时附带构建时间戳所有utm_*营销参数与ref参数从当前 URL 的 query string 解析。recordTracksPageViewWithPageParams则额外调用 src/page-view-params.ts在事件中附带last_pageview_path_with_count与this_pageview_path_with_count两个字段形如(/previous(1)与/current(2)用于分析页面浏览的顺序与跳转路径模块内部通过pathCounter计数并在popstate用户点击前进/后退时重置最近路径记录。隐私合规跟踪偏好与 GDPR/CCPA 处理事件是否真正上报还受跟踪偏好tracking prefs控制。getTrackingPrefs()src/utils/get-tracking-prefs.ts依据 cookiecountry_code/region判断用户所在法域非 GDPR 与 CCPA 区域默认允许全部跟踪GDPR 区域默认essential与analytics桶开启analytics 采用 opt-out 机制、advertising桶关闭opt-incookie banner 需要展示CCPA 区域仅advertising桶受偏好影响其余桶恒为允许。偏好本身通过sensitive_pixel_optionsV2JSON 结构与sensitive_pixel_optionV1yes/no两个 cookie 持久化解析逻辑见parseTrackingPrefssrc/utils/get-tracking-prefs.ts。recordTracksEvent在记录前会检查buckets.analytics因此应用侧无需额外判断只需依赖 cookie banner 正确写入偏好即可。另外src/tracks.ts 的checkForBlockedTracks会在 Tracks 脚本加载失败说明用户屏蔽了统计脚本时改用用户 ID 或tk_ai匿名 cookie 调用/nostats.js上报“统计被屏蔽”的事实保证数据盲区可见。进阶用法TrainTracks、站点上下文与离线队列推荐流埋点TrainTracks包内的 src/train-tracks.ts 封装了推荐内容如读者推荐流的曝光与交互埋点import { recordTrainTracksRender, recordTrainTracksInteract, getNewRailcarId, } from automattic/calypso-analytics; const railcarId getNewRailcarId(); // 形如 32 位 hex-{suffix} recordTrainTracksRender( { railcarId, uiAlgo: reader-feed-v2, uiPosition: 3, fetchAlgo: rec-algo, recBlogId: 1234567, } ); recordTrainTracksInteract( { railcarId, action: click } );渲染事件统一命名为calypso_traintracks_render交互事件为calypso_traintracks_interact属性名遵循下划线命名ui_algo、ui_position、fetch_algo、rec_blog_id等未传入的字段会被过滤。站点上下文标记当事件与某个具体站点相关、但调用方不便从 Redux 取站点时可使用withSiteContext( properties, source, siteId )src/utils/site-context.tsimport { withSiteContext, NO_SITE_CONTEXT } from automattic/calypso-analytics; const props withSiteContext( { action: view }, post-editor, 1234567 ); // { action: view, blog_id: 1234567, site_context_source: post-editor }该工具会把siteId写入blog_id、来源写入site_context_source当站点 ID 无效或来源为NO_SITE_CONTEXT时事件不携带blog_id并报告site_context_source: none同时清除可能矛盾的force_site_id。这样可避免 superProps 回退到“用户选中站点”而污染事件语义。离线事件队列针对注册等可能在页面跳转瞬间触发、容易丢失的事件client/lib/analytics/queue.js 提供基于localStorage的延迟队列addToQueue( moduleName, trigger, ...args )先把调用意图序列化入队上限 100 条之后由processQueue()在合适的时机例如新页面加载后回放执行。模块名与触发函数采用间接映射避免不必要的代码加载。这是保证“关键转化事件不因跳转而丢失”的配套机制。弃用说明旧 API 与新 API 的对应关系README 明确说明recordTracksEvent( name, properties )取代了旧版calypso/lib/analytics/tracks中同名方法的调用方式// 旧用法已弃用 // eslint-disable-next-line no-restricted-imports import { recordTracksEvent } from calypso/lib/analytics/tracks; recordTracksEvent( name, properties );值得注意的是仓库中 client/lib/analytics/tracks.js 仍然存在但它已经变成对automattic/calypso-analytics的薄封装转发recordTracksEvent的同时通过analyticsEvents.once( record-event, ... )把包级事件再广播到应用层的tracksEventsEventEmitter供旧的订阅方继续使用。因此新增代码应优先从automattic/calypso-analytics导入或使用calypso/state/analytics/actions的 Middleware 路径遗留订阅依赖 client/lib/analytics/tracks.js 的事件广播仍然可用但建议逐步迁移。接入清单Checklist完成一次合规的 Tracks 埋点可按以下步骤自查初始化在应用启动处参考 client/boot/common.js调用initializeAnalytics( currentUser, superProps )确保用户身份与全局属性就绪选路径优先使用dispatch( recordTracksEvent( name, properties ) )client/state/analytics/actions/record.js仅在确需绕过 Redux 时直接调用包的recordTracksEvent命名合规事件名以calypso_开头、全小写、token 用下划线分隔、动词放末尾且用非变形形式如calypso_cart_product_add属性合规属性名匹配/^[a-z_][a-z0-9_]*$/不使用geo、message、request、geocity、ip等保留名不传嵌套对象值为undefined的属性不会上报隐私检查确认 cookie banner 逻辑会正确写入sensitive_pixel_options偏好buckets.analytics开启时事件才会真正记录页面浏览使用recordTracksPageViewWithPageParams记录页面级事件自动附带utm_*与页面顺序参数测试由于 Middleware 路径的事件只是普通 action可在测试中直接断言 action 结构无需浏览器环境这正是 README 推荐 Middleware 的原因。通过上述路径即可在 wp-calypso 中实现既符合 Tracks 收录规则、又具备隐私合规保障的事件埋点方案。赞分享前端CMS【免费下载链接】wp-calypsoThe JavaScript and API powered WordPress.com项目地址https://gitcode.com/gh_mirrors/wp/wp-calypso点击查看免费下载相关推荐wp-calypso Reader 站点流链接组件 ReaderSiteStreamLink从 href 生成到点击埋点的完整实现解析wp calypso Reader 站点流链接组件 ReaderSiteStreamLink从 href 生成到点击埋点的完整实现解析 导读 ReaderSi前端CMSVoiceCraft 入门指南三步跑通零样本语音编辑与文本转语音VoiceCraft 入门指南三步跑通零样本语音编辑与文本转语音 录音里读错一个词整段重来其实不必。VoiceCraft 是一个开源的零样本语音编辑与文本人工智能大模型语音音频深入解析 wp-calypso 的 UpsellNudge 组件从 Banner 封装到一键升级的完整实践指南深入解析 wp calypso 的 UpsellNudge 组件从 Banner 封装到一键升级的完整实践指南 导读 UpsellNudge 是 WordPr前端CMS上一篇企业微信打卡位置修改神器Android版完整使用指南下一篇终极指南3步搞定Windows版iperf3网络测速神器创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考