# @guardian/ophan-tracker-js 中文文档

规范地址：https://npmcn.com/package/%40guardian/ophan-tracker-js/

版本：5\.5\.0
npm 元数据更新时间：2026-11-12T11:17:07.719Z
中文译文更新时间：2026-11-17T02:46:55.456Z
软件包许可：未声明

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40guardian/ophan-tracker-js
原文对照：https://npmcn.com/package/%40guardian/ophan-tracker-js/?lang=original
项目主页：https://github.com/guardian/ophan#readme
源码仓库：https://github.com/guardian/ophan

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：341 kB，225 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=16
- 运行依赖：1 个
- 首次发布：2023-11-08T11:56:20.707Z
- 最新版本发布：2026-11-12T11:17:07.214Z
- 近 30 天下载量：27040（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：126（近 12 个月 68 个）

## 中文简介

Ophan 的浏览器JavaScript客户端.

## 安装

```sh
npm install @guardian/ophan-tracker-js
```

也可以使用：`pnpm add @guardian/ophan-tracker-js`、`yarn add @guardian/ophan-tracker-js`、`bun add @guardian/ophan-tracker-js`

## README

# 使用 Ophan 跟踪器- js

Ophan 的浏览器JavaScript客户端.

## 安装

```bash
$ 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(`*.js`CDN 两者都需要一个模块 页面上的加载器 。 对于拥有 **没有模块加载器和捆绑器** ——例如销售力量主办的帮助中心——有一个自动执行的IIFE大楼:

-   `help-centre.iife.js` - 展示明确的帮助中心页面视图跟踪 `window.guardian.ophan` 当脚本装入时,不发送任何信息.

```html
<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 上看到图书馆的用例 [这里](https://github.com/guardian/dotcom-rendering/blob/main/dotcom-rendering/src/client/ophan/ophan.ts)

1.  **导入和启用库 :**
    
    图书馆应紧急(非懒散地)输入和登录,以确保适当的初始化。 准确的语法可能因您的构建工具或环境而异.
    
    ```javascript
    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()`数字 :**
    
    ```javascript
    record({
        edition: 'UK',
    });
    ```
    

### 使用类型脚本

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

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

#### 示例使用

```typescript
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团队](mailto:Ophan.Dev@guardian.co.uk)。 。 。 .

### 将事件直接发送到后端

_请 [咨询Ophan团队](https://npmcn.com/package/%40guardian/ophan-tracker-js/Ophan.Dev@guardian.co.uk) 如果你想这样做._

追踪器的后端暴露出两个端点, `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 复杂度和持续 维持费比回归后的额外保险有正当理由。 这个 [孤儿原型](https://github.com/guardian/ophan/pull/8523) 财务报告和审定财务报表 [Dotcom 整合](https://github.com/guardian/dotcom-rendering/pull/17129) 为: 保留以供参考.

### 浏览器行为测试

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

这些测试验证了候选人的浏览器行为和外出请求 在释放前. [`OphTrack`](https://npmcn.com/package/%40guardian/oph-track/README.md) 而不是检查部署 制作跟踪器并验证页面视图通过完整的Ophan 摄入管道进入弹性搜索.

```shell
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/ 页面存档备份,存于互联网档案馆](https://getfoxyproxy.org/downloads/))在浏览器中创建一条强制j.ophan.co.uk的规则 到当地主机8000。 (对我来说,FoxyProxy在决定开始和Lighttpd交谈之前,需要一些开关和关机
    
4.  在另一个终端窗口中,启动一个服务器,即 [运行守护者前端](https://github.com/guardian/frontend/blob/main/docs/01-start-here/01-installation-steps.md)
    
5.  导航到您正在本地运行的守护者( 例如 https://localhost: 900/uk)
    
6.  确保FoxyProxy启用
    
7.  快乐地发展
    

## 发布

### 两种发布格式

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

#### 国家预防机制

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

1.  添加更改列表, 运行以下命令并遵循指令
    
    ```
    .../ophan/tracker-js $ npx changeset
    ```
    
2.  当您提出一个 PR 时, 更改器 bot 将不会正确看到您包含一个更改器 — 它只检查寄存器根部的 . changersets 文件夹, 而我们在子目录中 。 别担心.
    
3.  公关合并后 [`changesets` github 动作](https://github.com/changesets/action) 将创建一个新的公关, [示例](https://github.com/guardian/ophan/pull/5626)在合并这一生成的PR后,行动将向国家预防机制公布。 (此检查子目录正确
    

#### S3 弹匣

-   [https://j.ophan.co.uk/ (中文(简体) )](https://j.ophan.co.uk/jobs.js) - CDN/S3, [通过里夫拉夫部署](https://riffraff.gutools.co.uk/deployment/history?projectName=ophan%3A%3Aophan-tracker-js&page=1) 被一些卫报网站使用 [https://jobs.theguardian.com/ 页面存档备份,存于互联网档案馆](https://jobs.theguardian.com/). 这个方法的一个优点是,使用它的网站立即获得跟踪器-js的更新,而无需开发者干预.

#### 滚动

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

## 发布

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

见 [谷歌医生](https://docs.google.com/document/d/1MndFG-DLDQAMHIi55T4kZkGq4ONcded1-MDd9QS_NZE/edit?tab=t.0) 需要根据赛道赛车手的球队名单.

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

## 常见问题

### @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 和提交记录判断。

