# @financial-times/o-tracking 中文文档 规范地址：https://npmcn.com/package/%40financial-times/o-tracking/ 版本：4\.12\.0 npm 元数据更新时间：2026-10-06T13:39:56.566Z 中文译文更新时间：2026-11-14T18:43:57.131Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40financial-times/o-tracking 原文对照：https://npmcn.com/package/%40financial-times/o-tracking/?lang=original 项目主页：https://registry.origami.ft.com/components/o-tracking ## 关键信息（来自 npm 元数据） - 包体积（解压后）：162 kB，70 个文件 - 模块格式：ES Module - TypeScript 类型：未声明 - 运行依赖：1 个 - 首次发布：2019-02-15T15:07:00.562Z - 最新版本发布：2026-06-25T07:38:55.694Z - 近 30 天下载量：4614（2026-10-15 至 2026-11-13，npm 官方下载统计） - 已发布版本数：60（近 12 个月 3 个） ## 中文简介 提供产品跟踪。 追踪请求将发送给贫穷的API. ## 安装 ```sh npm install @financial-times/o-tracking ``` 也可以使用：`pnpm add @financial-times/o-tracking`、`yarn add @financial-times/o-tracking`、`bun add @financial-times/o-tracking` ## README # 零跟踪 将跟踪请求发送到 [穷人 API](https://spoor-docs.herokuapp.com/)。 。 。 . - [使用量](https://npmcn.com/package/%40financial-times/o-tracking/#readme-usage) - [没有 Java 脚本的跟踪](https://npmcn.com/package/%40financial-times/o-tracking/#readme-tracking-without-javascript) - [用 JavaScript 跟踪](https://npmcn.com/package/%40financial-times/o-tracking/#readme-tracking-with-javascript) - [如何跟踪额外点击数据 `data-trackable` 属性](https://npmcn.com/package/%40financial-times/o-tracking/#readme-how-to-track-extra-click-data-using-data-trackable-attributes) - [如何查看数据](https://npmcn.com/package/%40financial-times/o-tracking/#readme-how-to-view-the-data) - [执行实例](https://npmcn.com/package/%40financial-times/o-tracking/#readme-example-implementations) - [移徙指南](https://npmcn.com/package/%40financial-times/o-tracking/#readme-migration-guide) - [联系人](https://npmcn.com/package/%40financial-times/o-tracking/#readme-contact) - [许可证](https://npmcn.com/package/%40financial-times/o-tracking/#readme-licence) ## 使用量 检查出来 [如何将 Origami 组件纳入您的项目](https://npmcn.com/package/docs/legacy-o2-docs/technical-guide.md) 开始 `o-tracking`。 。 。 . ### 没有 Java 脚本的跟踪 o- tracking没有JavaScript是行不通的,但是,通过设置一个指向Spoor跟踪像素端点的cs背景图像url,您仍然可以向Spoor API发送基本的跟踪请求(Spoor tracking sixel end point)`https://runtime-api.ft.com/px.gif`) (中文(简体) ). 没有JavaScript,点击事件和其他交互事件将不会被跟踪,但可以跟踪基本的页面视图事件. Spoor 跟踪像素端点需要一个 `data` 查询参数是一个 url- encoded JSON 字符串, 代表要在 Spoor 中跟踪的数据 . ```html
``` 例如,如果您想要在 Spoor 中跟踪以下数据: _建议:_ 用别的 `system.source` 来自 o- tracking JavaScript 模式中使用的值将帮助您的项目更方便地分组没有 JavaScript 的用户的数据 。 下面的例子使用源 `o-tracking-fallback`。 。 。 . ```json { "category": "page", "action": "view", "system": { "source": "o-tracking-fallback", }, "context": { "product": "ft.com", "content": { "asset_type": "page" } } } ``` 以下是相应的跟踪像素设置 : ```html
``` ### 用 JavaScript 跟踪 ### 启动离线支持和队列活动 默认的o跟踪使用浏览器Beacon API向Spoor发送事件,而Beacon API只有在设备在线时才能工作,而o跟踪无法将这些事件排队. 如果想要将事件排队( 如果事件发送失败, 则重试) 和( 或) 关闭时要记录事件, 设置 `queue` 改为 `true` 在电话化期间 `o-tracking` 像这样: ```js import oTracking from '@financial-times/o-tracking'; const config = { queue: true, // Make sure o-tracking stores the events on a local queue (this means o-tracking can work when the device is offline) ... }; oTracking.init(config); ``` #### 开发者/ 测试模式 o- tracking有一个开发/测试模式,它会将事件标记为测试事件,并且还写给控制台额外的调试信息. 要激活模式, 设置 `test` 改为 `true` 在电话化期间 `o-tracking` 像这样: ```js import oTracking from '@financial-times/o-tracking'; const config = { test: true, // Mark the events as test events and turn on extra debug logging. ... }; oTracking.init(config); ``` o-跟踪也有 `test-data` 模式将事件标记为测试事件,而不在控制台中调试信息: ```js import oTracking from '@financial-times/o-tracking'; const config = { test_data: true, // Mark the events as test events without extra debug logging. ... }; oTracking.init(config); ``` #### 方法 ##### 跟踪.init 手动即时 `o-tracking`,导入组件并调用 `init` 具有特定产品配置的方法: ```js import oTracking from '@financial-times/o-tracking'; const config = { context: { // This value is used as a way to identify the high-level product, for example: ft.com, FT app, biz-ops etc. product: 'o-tracking-example', } }; oTracking.init(config); ``` ##### oTracking.page (英语) 要跟踪您称之为产品的页面视图 `oTracking.page` 方法. 页面事件自动跟踪url和裁判. 参见 [页面事件文档](https://npmcn.com/package/%40financial-times/o-tracking/docs/event-parameters/page-view.md) 对于可以设置的属性信息. ```js const pageConfig = { content: { /* Asset type is meant to describe the main purpose of the page The value can be one of these: - `story` - A story or article - `blog` - A blog post - `front` - A home page or front page - `ad` - An advert. - `image` - An image - `interactive` - An interactive graphic - `report` - A special report - `search` - A search results page - `section` - A section or listing page - `topic` - A topic landing page - `video` - A video page - `login` - Any login/sign-in page - `stream` - A stream page - `funnel` - Any funnel page - `epaper` - all epaper pages - `rankings` - A rankings page for schools and courses (i.e. on rankings.ft.com). Not the section's hub page - `markets` - Any market, bond, commoditity, stock, currency 'tearsheet' (usually has "/tearsheet/" in URL) - `myft` - All MyFT pages - `account` - All account pages - `membership` - All membership pages - `page` - anything else, not above. */ asset_type: "story" } }; oTracking.page(pageConfig); ``` ##### 跟踪 点击.init 打电话 `oTracking.click.init` 用于跟踪点击事件的方法。 通过您想要点击事件作为参数的分类: - o- tracking 点击事件也会跟踪从 DOM 树根到被点击元素的路径 。 这被记录在一个名为 `domPathTokens`。 。 。 . - 如果点击的元素有 `data-trackable` 属性集,兄妹元素也将包括在 `domPathTokens` 属性. 请参看 [事件文档](https://npmcn.com/package/%40financial-times/o-tracking/docs/event.md) 用于了解所有可能设置的属性. ```js // Tracking a click const category = 'element'; oTracking.click.init(category); ``` _说明:_ 属性 `data-o-tracking-skip-queue` 不再使用,它现在是默认行为 ##### (原始内容存档于2017-10-21) (英语). Tracking.view.init 要跟踪一个元素在用户视野中的位置, 请添加属性 `data-o-tracking-view` ,然后调用 `oTracking.view.init` 方法 : - 默认情况下,带有 `data-o-tracking-view` 属性被跟踪. - 要跟踪不同的元素,请设定 `selector` 选项属性到 CSS 选择器. - 如点击事件, 视图事件也会跟踪从 DOM 树根到触发跟踪事件的元素的路径 `domPathTokens`。 。 。 . - 要分类视图事件,设置 `category` 选项属性. - 要定制此元素在取景口中需要多少触发事件,请使用 `intersectionObserverThreshold` 选项。 此值将被设定为交叉观察员的门槛值(默认为 `1.0`) (中文(简体) ). - 要收集与跟踪事件一起发送的额外数据, 请添加一个名为 `getContextData` 对选项。 函数收到单个参数时, 触发跟踪事件的元素, 需要用这些可选属性集返回对象 : - `componentContentId` - `type` - `subtype` - `component` 更新 2025-060-12:这些备选方案可能过时,它们绝对是构成部分,可供更新 _说明:_ 这个功能需要 `window.IntersectionObserver` 为了追踪事件 _说明:_ `getContextData` 应该是返回的函数 `{object}`。它接受观点要素作为论据 ###### 构成部分跟踪 [组件标准模板跟踪光谱](https://docs.google.com/spreadsheets/d/16d2-uDM8rhz1wSKOkoupcpPDRFQ8AtY1GxVJpt74vY4/edit?gid=1318706009#gid=1318706009) (c) 说明应收集哪些数据以获取组成部分意见。 有些是为你而生的, `category` 财务报告和审定财务报表 `action` 有默认。 您需要设置以下属性 : `getContextData` ```js getContextData: () => { return { component: { name: '[some-human-readable-name]', type: '[see tracking spec list]', id: '[consistent-guid]' }, content: { asset_type: '[see tracking spec list]', uuid: ['content-id-eg-article-id'] } }; }, }); ``` 可选的是,您也可以通过获取ContextData调用,将额外元数据添加到最多3个自定义值 ```js ... custom: [ { name: 'some-name', value: 'some-value', }, ], ... ``` 请参看 [事件文档](https://npmcn.com/package/%40financial-times/o-tracking/docs/event.md) 用于了解所有可能设置的属性. ```js const opts = { category: 'audio', // default: 'component' selector: '.o-teaser__audio', // default: '[data-o-tracking-view]' getContextData: (el) => { // default: null return { componentContentId: el.getAttribute('data-id'), type: 'audio', subtype: 'podcast', component: 'teaser' }; } }; oTracking.view.init(opts); ``` ##### 追踪. 活动 要跟踪一个自定义事件,请叫 `oTracking.event` 方法。 例如,要跟踪播放的视频: ```js const eventConfig = { "category": "video", // optional "action": "play", // optional }; oTracking.event(eventConfig); ``` 这个 `event` 方法还接受在事件处理后运行的可选回调. ```js const eventConfig = { "category": "video", // optional "action": "play", // optional }; oTracking.event(eventConfig, () => { console.log('The custom video event has been processed!'); }); ``` 请参看 [事件文档](https://npmcn.com/package/%40financial-times/o-tracking/docs/event.md) 用于了解所有可能设置的属性. #### 活动 而不是打电话 `page` 财务报告和审定财务报表 `event` 方法 `o-tracking` 可以配置以捕获基于自定义 DOM 事件的事件 `oTracking.page` 财务报告和审定财务报表 `oTracking.event`。 。 。 . ##### oTracking.page (英语) 打电话 `oTracking.page.init()` 监听方法 `oTracking.page` 事件: ```js // Tell o-tracking to listen for `oTracking.page` events oTracking.page.init(); // Now we can send page events and o-tracking will track the data within them. const pageData = { content: { uuid: 'abc-123', barrier: 'PREMIUM' }; document.body.dispatchEvent(new CustomEvent('oTracking.page', { detail: pageData}, bubbles: true})); ``` ##### 追踪. 活动 让奥追踪听 `oTracking.event` 事件,你叫 `oTracking.event.init()`数字 : ```js // Tell o-tracking to listen for `oTracking.event` events oTracking.event.init(); // Now we can send custom events and o-tracking will track the data within them. const customData = { category: 'video', action: 'play', id: '512346789', pos: '10' }; document.body.dispatchEvent(new CustomEvent('oTracking.event', { detail: customData}, bubbles: true})); ``` ### 如何跟踪额外点击数据 `data-trackable` 属性 您可以通过使用 `data-trackable` 财务报告和审定财务报表 `data-trackable-context-*` 自定义属性. #### `data-trackable` `o-tracking` 将走上 DOM 以获得元素树 `data-trackable` 属性。 例如,点击下面的列表项按钮将会导致一个在其中记录此路径的事件- `header-menu country-selector china`: - (中文) ```html
``` #### `data-trackable-context-*` 要向事件添加额外的上下文, 您可以在窗体中添加自定义属性 : `data-trackable-context-name="data"` 地点 `name` 是额外上下文的名称,并且 `data` 是额外的数据. 例如,当点击以下锁定元素时,它会添加额外事件字段 `article_guid` 财务报告和审定财务报表 `article_source` 数据被跟踪. ```html ``` **嵌入属性** 使用 `data-trackable-context-*` 自定义属性,以类似JSON的格式指定值的字符串表示. 例如,当点击以下主锚元素时: ```html ``` 事件背景将提供属性: `plain_property` 财务报告和审定财务报表 `nested_property`,如下文所显示: ```json { "category": "link", "action": "click", "system": { "source": "o-tracking", }, "context": { "plain_property": "plain-property-value", "nested_property": { "type": "nested", "value": "nested-property-test" } } } ``` ## 如何查看数据 一旦将数据发送到Spoor,您可以通过Looker查看数据. FT有一个名为#ask-an-analyst的Slack频道,任何人都可以在那里获得Looker的帮助. 如果你以前从未使用过Looker,你将需要 [通过此表单请求访问](https://fteunew.freshservice.com/support/catalog/items/73)。 。 。 . 要注册到 Looker : - 打开 [FT 浏览器](https://ft.okta.com/home/looker/0oacqdp1byXmj5Zcz357/63357) 在您的浏览器中. ## 执行实例 - [ft.com (英语)](https://npmcn.com/package/%40financial-times/o-tracking/docs/ftcom_example.md) - [成员](https://npmcn.com/package/%40financial-times/o-tracking/docs/membership_example.md) ## 移徙指南 | 状态 | 主要版本 | 最后一个小版本 | 移徙指南 | | :-: | :-: | :-: | :-: | | 活动 | 页:1 | 不详 | [迁移到 v4](https://npmcn.com/package/%40financial-times/o-tracking/MIGRATION.md#migrating-from-v3-to-v4) | | 维护 | 3个 | 3.1 国家 | [迁移到 v3](https://npmcn.com/package/%40financial-times/o-tracking/MIGRATION.md#migrating-from-v2-to-v3) | | 已贬值 | 2个 | 2.0.10 联合国 | [迁移到 v2](https://npmcn.com/package/%40financial-times/o-tracking/MIGRATION.md#migrating-from-v1-to-v2) | | 已贬值 | 1个 | 1.7.2 国家 | 不详 | * * * ## 联系人 如果您对本部分有任何问题或评论,或需要帮助使用本部分,请 [提出问题](https://github.com/Financial-Times/o-tracking/issues)访问 [#origami - 支持](https://financialtimes.slack.com/messages/origami-support/) 或电子邮件 [折纸支持](mailto:origami-support@ft.com)。 。 。 . * * * ## 许可证 本软件由金融时报根据以下规定出版: [麻省理工学院许可证](http://opensource.org/licenses/MIT)。 。 。 . ## 常见问题 ### @financial-times/o-tracking 是什么？ 提供产品跟踪。 追踪请求将发送给贫穷的API\. ### 如何安装 @financial-times/o-tracking？ 在项目目录运行 npm install @financial-times/o-tracking，或使用 pnpm add / yarn add / bun add。 ### @financial-times/o-tracking 支持 TypeScript 吗？ 该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/financial-times\_\_o-tracking 是否存在。 ### @financial-times/o-tracking 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @financial-times/o-tracking 可以商用吗？ @financial-times/o-tracking 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @financial-times/o-tracking 的下载量有多少？ 根据 npm 官方下载统计，@financial-times/o-tracking 在 2026/10/15 – 2026/11/13 这 30 天内被下载 4,614 次，日均约 154 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @financial-times/o-tracking 还在维护吗？ 最新版本 4\.12\.0 发布于 2026/06/25（4 个月前）；至今共发布 60 个版本，其中过去 12 个月发布了 3 个；首次发布于 2019/02/15。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。