@guardian/ophan-tracker-js

中文文档
5.5.0发布于 2026/11/12TypeScriptES Module近 30 天下载 2.7万

Ophan 的浏览器JavaScript客户端.

中文使用文档
文档目录13 节
  1. 安装
  2. 使用量
  3. 国家防范机制一揽子计划
  4. CDN 分发
  5. 使用类型脚本
  6. 将事件直接发送到后端
  7. 编译
  8. 类型检查
  9. 测试
  10. 浏览器行为测试
  11. 发布
  12. 两种发布格式
  13. 发布

使用 Ophan 跟踪器- js

Ophan 的浏览器JavaScript客户端.

安装

$ npm install @guardian/ophan-tracker-js

使用量

tracker-js既作为国家防范机制的软件包,又作为CDN的发售版本.

国家防范机制一揽子计划

国家防范机制一揽子方案采用支持多个平台的统一切入点。 急切地导入并呼叫 init() 在调用其他跟踪器方法之前, 平台默认为 ng 在运行时省略或无法识别.

国家预防机制

  • ng (简为下源) 为guardian.com
  • manage-my-account (原始内容存档于2017-10-21). the guardian.com
  • support (原始内容存档于2018-09-28). for support. the guardian.com

默认行为

库的默认切入点是 @guardian/ophan-tracker-js,决定 NPM-dist/index.js调用 init() 启动选定平台的跟踪器,并发送初始页面视图事件。 使用 record() 用于额外活动。 使用 sendInitialEvent() 仅当您有意需要一个新的页面视图事件时,例如单页应用程序路由更改后.

如果在之前调用跟踪器方法 init() 在浏览器上下文中,该方法警告而不发送事件。 在服务器侧渲染或其他非浏览器上下文中,跟踪器方法返回时不会触碰浏览器全局.

CDN 分发

CDN版本为特定用途案例提供了单个切入点,可访问地址: https://j.ophan.co.uk/。这些切入点本身为历史平台,并为现有的CDN消费者保留:

  • contribution.js - 捐款追踪
  • embed.js - 嵌入内容
  • fb-instant.js - 脸书即时文章
  • holidays.js - 监护人假日
  • http-status.js - HTTP状态页面跟踪
  • interactive.js - 守护者互动
  • jobs.js - 守护者工作网站
  • jobs-courses.js - 监护工课程网站
  • membership.js - 监护成员(旧址)
  • ng.js - 为守护者.com
  • r2.js - 遗产R2平台跟踪
  • smart-news.js - 智能新闻平台跟踪
  • witness.js - 守护网跟踪

平面 <script src> (IIFE) 建设

AMD( AMD ) :ophan/*.js)和系统JS(*.jsCDN 两者都需要一个模块 页面上的加载器 。 对于拥有 没有模块加载器和捆绑器 ——例如销售力量主办的帮助中心——有一个自动执行的IIFE大楼:

  • help-centre.iife.js - 展示明确的帮助中心页面视图跟踪 window.guardian.ophan 当脚本装入时,不发送任何信息.
<script src="https://j.ophan.co.uk/help-centre.iife.js"></script>
<script>
  // Call only when the Help Centre considers this to be a page view.
  window.guardian.ophan.sendInitialPageview();
</script>

您可以在 guardian.com 上看到图书馆的用例 这里

  1. 导入和启用库 :

    图书馆应紧急(非懒散地)输入和登录,以确保适当的初始化。 准确的语法可能因您的构建工具或环境而异.

    import { init, record } from '@guardian/ophan-tracker-js';
    
    // Initialise for your platform. This sends the initial page-view event.
    init('ng'); // or 'manage-my-account' or 'support'
    
  2. 发送跟踪事件 record()数字 :

    record({
        edition: 'UK',
    });
    

使用类型脚本

包会导出 TypeScript 声明,声明地图,以及源文件. 编辑器应该让您从 record() 改为 EventPayload, (中文(简体) ), ComponentEvent, (中文(简体) ), Product,以及相关工会类型 src/types/event.ts 和相邻类型文件.

当你传递一个对象字元到 record(),TypeScript将拒绝未知的顶级字段和无效的嵌入值,例如不支持的组件动作,组件类型,产品,或版本. 如果需要添加新事件类型或属性,则会故意更新跟踪器-js类型和下游Ophan模型.

示例使用

import {
    getViewId,
    init,
    record,
    sendInitialEvent,
} from '@guardian/ophan-tracker-js';
import type {
    EventPayload,
    Product,
    ComponentEvent,
    AbTest,
} from '@guardian/ophan-tracker-js';

// Initialise the library for your platform. This sends the initial page-view event.
init('ng'); // or 'manage-my-account' or 'support'

const exampleProduct: Product = 'APP_PREMIUM_TIER';
const exampleAbTest: AbTest = {
    name: 'myAbTest',
    variant: 'variant',
    campaignCodes: ['code1', 'code2'],
};

const componentV2 = {
    componentType: 'ACQUISITIONS_BUTTON',
    id: 'component-id',
    products: [exampleProduct],
    campaignCode: 'campaign-code',
    labels: ['label1', 'label2'],
};

const componentEvent: ComponentEvent = {
    component: componentV2,
    action: 'CLICK',
    value: 'some-value',
    id: 'event-id',
    abTest: exampleAbTest,
    targetingAbTest: exampleAbTest,
};

const payload: EventPayload = {
    componentEvent: componentEvent,
};

record(payload);

const currentViewId = getViewId();

// Use sendInitialEvent() only when intentionally creating a new page view,
// for example after a single-page app route change.
sendInitialEvent();

getViewId() 财务报告和审定财务报表 getPageViewId() 返回当前活页视图 ID。 默认导出也会被曝光 viewId 财务报告和审定财务报表 pageViewId 作为与对象类消费者兼容的获取器.

如果您想要添加一个不存在的新事件类型或事件属性, 请 联系Ophan团队。 。 。 .

将事件直接发送到后端

请 咨询Ophan团队 如果你想这样做.

追踪器的后端暴露出两个端点, img/1 用于页面查看事件,以及 img/2 它包含所有其它事件。 送审会的活动 img/2 结束点, 也会通过 img/1在Ophan和Datatech管道下,同页视图ID的事件被捆绑在一起,以便于查询和数据分析。 因此,必须举行页面浏览活动.

开发 Ophan 跟踪器-js

库使用 Javascript 和 TypeScript 执行,源代码位于 src 目录及其子目录。 该项目的设置既包括了TypeScript (.ts)的文件,也包括了JavaScript (.js)的文件,允许两种语言在库的执行中混合.

字典界面和类型在 src/types 文件夹.

TypeScript 编译器配置生成已编译的 JavaScript 文件及相应的声明文件(.d.ts)在 NPM-dist 目录。 声明文件为库的公开API提供类型信息,声明地图将编辑器点回源文件.

编译

    .../ophan/tracker-js $ npm run build-for-npm

类型检查

    .../ophan/tracker-js $ npm run test:types

测试

运行单元测试 npm test. 浏览器行为测试介绍如下.

我们决定不进行生产影子测试 因为运行和隔离 读者浏览器中的第二个跟踪器增加了更多 JavaScript 复杂度和持续 维持费比回归后的额外保险有正当理由。 这个 孤儿原型 财务报告和审定财务报表 Dotcom 整合 为: 保留以供参考.

浏览器行为测试

浏览器行为测试从当前源头构建 NPU 软件包, 加载 在无头Chrome中,守护者阵线并注入它作为自成一体的脚本. 从现在的结账结果来看,这个建筑叫做候选人,以区分它 从追踪器 -js 版本已经部署在直播页面上。 密码在 测试来自 NPM-dist,同样安装国家预防机制消费者 把它写成一个脚本 这样Puppeteer就可以注入它。 请求改为: 非可路性测试源头并在浏览器中检查,因此测试不发送 分析奥芬.

这些测试验证了候选人的浏览器行为和外出请求 在释放前. OphTrack 而不是检查部署 制作跟踪器并验证页面视图通过完整的Ophan 摄入管道进入弹性搜索.

npm run test:browser

设定 GUARDIAN_FRONT_URL 测试不同的 Guardian 页面。 默认是 https://www.theguardian.com/uk。 。 。 .

测试会抑制Ophan的要求 并禁用同意管理器,但是 生产页面仍可与其他第三方联系。 CI运行它们为 tracker-js 拖取请求;也可以由 GitHub 动作手动启动.

代理跟踪器-js :

  1. 安装依赖关系

    $ brew install lighttpd
    .../ophan/tracker-js $ npm install
    
  2. 在另一个终端窗口中 :

    .../ophan/tracker-js $ lighttpd -f lighttpd.conf -D
    
  3. 安装 FoxyProxy (https://getfoxyproxy.org/downloads/ 页面存档备份,存于互联网档案馆)在浏览器中创建一条强制j.ophan.co.uk的规则 到当地主机8000。 (对我来说,FoxyProxy在决定开始和Lighttpd交谈之前,需要一些开关和关机

  4. 在另一个终端窗口中,启动一个服务器,即 运行守护者前端

  5. 导航到您正在本地运行的守护者( 例如 https://localhost: 900/uk)

  6. 确保FoxyProxy启用

  7. 快乐地发展

发布

两种发布格式

当你改变追踪器时 你必须打开 两者 这些系统:

国家预防机制

我们用 changesets 国家防范机制软件包的自动化出版:

  1. 添加更改列表, 运行以下命令并遵循指令

    .../ophan/tracker-js $ npx changeset
    
  2. 当您提出一个 PR 时, 更改器 bot 将不会正确看到您包含一个更改器 — 它只检查寄存器根部的 . changersets 文件夹, 而我们在子目录中 。 别担心.

  3. 公关合并后 changesets github 动作 将创建一个新的公关, 示例在合并这一生成的PR后,行动将向国家预防机制公布。 (此检查子目录正确

S3 弹匣

滚动

从 Rollup( 使用 build-for-cdn 脚本在 package.json)仅用于向CDN发布,用于使用SystemJS / AMD

发布

公布后,使用Tracker-JS向团队通报最新消息将是一个好的做法.

见 谷歌医生 需要根据赛道赛车手的球队名单.

如果对追踪器-js的更改很小,我们可以在相关回购中快速地提高PR,并要求团队进行审查.

版本与发布记录

@guardian/ophan-tracker-js 共发布 126 个版本,首次发布于 2023/11/08;过去 12 个月发布了 68 个版本。

版本发布日期距今
5.5.0latest2026/11/124 天前
5.4.02026/11/0412 天前
5.3.02026/11/0214 天前
0.0.0-canary-20261102144926canary2026/11/0214 天前
0.0.0-canary-202611021449082026/11/0214 天前
0.0.0-canary-202611021440022026/11/0214 天前

其他发布通道:next → 2.1.2-next.6,canary → 0.0.0-canary-20261102144926。

关于 @guardian/ophan-tracker-js 的常见问题

@guardian/ophan-tracker-js 是什么?

Ophan 的浏览器JavaScript客户端.

如何安装 @guardian/ophan-tracker-js?

在项目目录运行 npm install @guardian/ophan-tracker-js,或使用 pnpm add / yarn add / bun add。

@guardian/ophan-tracker-js 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@guardian/ophan-tracker-js 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@guardian/ophan-tracker-js 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=16。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@guardian/ophan-tracker-js 可以商用吗?

@guardian/ophan-tracker-js 使用 未声明 许可。package.json 没有声明许可证。没有许可证的代码默认保留全部权利,商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括,不构成法律意见,请以许可原文为准。

@guardian/ophan-tracker-js 的下载量有多少?

根据 npm 官方下载统计,@guardian/ophan-tracker-js 在 2026/10/17 – 2026/11/15 这 30 天内被下载 27,040 次,日均约 901 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@guardian/ophan-tracker-js 还在维护吗?

最新版本 5.5.0 发布于 2026/11/12(4 天前);至今共发布 126 个版本,其中过去 12 个月发布了 68 个;首次发布于 2023/11/08。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。