# @adobe/spacecat-shared-rum-api-client 中文文档

规范地址：https://npmcn.com/package/%40adobe/spacecat-shared-rum-api-client/

版本：2\.45\.1
npm 元数据更新时间：2026-10-08T17:34:36.820Z
中文译文更新时间：2026-11-08T09:50:31.958Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40adobe/spacecat-shared-rum-api-client
原文对照：https://npmcn.com/package/%40adobe/spacecat-shared-rum-api-client/?lang=original
项目主页：https://github.com/adobe/spacecat-shared#readme
源码仓库：https://github.com/adobe/spacecat-shared

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

- 包体积（解压后）：276 kB，36 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.0\.0 \<25\.0\.0
- 运行依赖：7 个
- 首次发布：2023-12-12T15:01:44.509Z
- 最新版本发布：2026-10-08T17:34:36.485Z
- 近 30 天下载量：1823（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：210（近 12 个月 26 个）

## 中文简介

Spacecat 服务共享模块 - Rum API客户端

## 安装

```sh
npm install @adobe/spacecat-shared-rum-api-client
```

也可以使用：`pnpm add @adobe/spacecat-shared-rum-api-client`、`yarn add @adobe/spacecat-shared-rum-api-client`、`bun add @adobe/spacecat-shared-rum-api-client`

## README

# 空间猫共享 - RUM API 客户端

一个JavaScript客户端,用于Adobe的"真实用户监测(RUM)API",是SpaceCat共享库的一部分.

## 安装

使用 npm 安装软件包 :

```bash
npm install @adobe/spacecat-shared-rum-api-client
```

## 使用量

#### 从 Helix UniversalContext 创建实例

```js
// The context must include an 'env' property so that the client can use RUM_ADMIN_KEY if needed.
const context = { env: process.env };
const rumApiClient = RUMAPIClient.createFrom(context);
```

#### 使用构造器

```js
// Optionally, pass a configuration and a logger objects to the constructor.
// If you want the client to automatically fetch the domainkey for a domain,
// provide the admin key as 'rumAdminKey'. If omitted, you must provide the domainkey
// in the query options.
const rumApiClient = new RUMAPIClient({ rumAdminKey: '<admin-key>' }, logger);
```

### 运行查询

```js
const opts = {
  domain: 'www.aem.live',
  // Either provide the domainkey directly...
  domainkey: '<domain-key>',
  // ...or omit it to let the client auto-fetch it if an admin key is configured.
  granularity: 'hourly',
  interval: 10
};

const result = await rumApiClient.query('cwv', opts);
console.log(`Query result: ${result}`);
```

**使用起始时间和结束时间精确日期范围 :**

```js
const opts = {
  domain: 'www.aem.live',
  domainkey: '<domain-key>',
  granularity: 'daily',
  startTime: '2024-01-01T00:00:00Z',
  endTime: '2024-01-31T23:59:59Z'
};

const result = await rumApiClient.query('cwv', opts);
console.log(`Query result: ${result}`);
```

**说明**:所有查询名称都必须是小写.

### 查询选项: “ 选择” 对象

| 选项 | 需求 | 默认 | 备注 |
| --- | --- | --- | --- |
| 域名 | 对 |  | 用于获取数据的域 . |
| 域键 | 没有 |  | 直接提供或省略自动调试 `RUM_ADMIN_KEY`。 。 。 . |
| 间隔 | 没有 | 第7条 | 以天为相(整数). 在提供开始时间/结束时间时被忽略 . |
| 颗粒性 | 没有 | 每日费用 | "每日"或"小时". |
| 开始时间 | 没有 |  | 以ISO 8601格式(如"2024-01-01T00:00Z")开始的时间. 一定是在结束时间之前 格式 `YYYY-MM-DD` 或者说 `YYYY-MM-DDTHH:MM:SSZ` |
| 结束时间 | 没有 |  | 结束时间为ISO 8601格式(例如"2024-01-31T23:59:59Z"). 一定是在时间之后 格式 `YYYY-MM-DD` 或者说 `YYYY-MM-DDTHH:MM:SSZ` |

### 获取并缓存域

您也可以直接使用新来获取给定域的域名 `retrieveDomainkey` 方法. 这种方法将使用管理员密钥获取域名(如果需要)并缓存以备后续调用.

```js
const domainKey = await rumApiClient.retrieveDomainkey('www.example.com');
console.log(`Domain key: ${domainKey}`);
```

## 可用查询

### 核心网络生命(CWV)

在请求的间隔内计算给定域的 CWV 数据。 它拿回了P75号 数值 **长效**, (中文(简体) ), **密码**, (中文(简体) ), **INP (英语)**,以及 **专题信托基金B** 指标,以及可用于 每个度量.

此外:

-   计量是 **按 URL 分组** 由 **模式** 用于一组URL,在分析单个页面和逻辑集页面时提供灵活性.
-   包括a **设备级别分解**,将衡量尺度单独分类 **桌面** 财务报告和审定财务报表 **移动**。 。 。 .
-   提供 **页面视图计数** (页面视图)和 **有机交通** (有机)度量衡,提供对用户活动和搜索驱动流量的见解.

示例答复:

```json
[
  {
    "type": "group",
    "name": "Catalog",
    "pattern": "https://www.aem.live/docs/*",
    "pageviews": 12000,
    "organic": 4000,
    "metrics": [
      {
        "deviceType": "desktop",
        "pageviews": 8000,
        "organic": 3000,
        "lcp": 40,
        "lcpCount": 6,
        "cls": 0.3,
        "clsCount": 3,
        "inp": 30,
        "inpCount": 3,
        "ttfb": 30,
        "ttfbCount": 3
      },
      {
        "deviceType": "mobile",
        "pageviews": 1000,
        "organic": 200,
        "lcp": 40,
        "lcpCount": 6,
        "cls": 0.3,
        "clsCount": 3,
        "inp": 30,
        "inpCount": 3,
        "ttfb": 30,
        "ttfbCount": 3
      }
    ]
  },
  {
    "type": "url",
    "url": "https://www.aem.live/home",
    "pageviews": 2620,
    "organic": 1900,
    "metrics": [
      {
        "deviceType": "desktop",
        "pageviews": 2420,
        "organic": 1700,
        "lcp": 2099.699999988079,
        "lcpCount": 8,
        "cls": 0.011145537287059668,
        "clsCount": 7,
        "inp": 8,
        "inpCount": 5,
        "ttfb": 548,
        "ttfbCount": 16
      }
    ]
  }
]
```

### 404 (韩语)

计算请求间隔内指定域的404个出错。 结果 按 URL 和 404 出错的来源进行分组。 产出包括所有各种来源 直接访问404页,以及来自这些来源的浏览总数.

示例答复:

```json
[
  {
    "url": "https://www.aem.live/developer/tutorial",
    "views": 400,
    "all_sources": [
      "https://www.google.com",
      "",
      "https://www.instagram.com"
    ],
    "source_count": 3,
    "top_source": "https://www.google.com"
  },
  {
    "url": "https://www.aem.live/some-other-page",
    "views": 300,
    "all_sources": [
      "https://www.bing.com",
      ""
    ],
    "source_count": 2,
    "top_source": ""
  },
  {
    "url": "https://www.aem.live/developer/",
    "views": 100,
    "all_sources": [
      ""
    ],
    "source_count": 1,
    "top_source": ""
  }
]

```

### 实验

列出请求间隔内指定域的所有实验。 结果按URL分类. 产出包括所有运行实验的URL,以及实验id,变体,每个变体/选取者点击/convert/form提交事件的次数以及实验中每个变体的视图.

示例答复:

```json
[
  {
    "type": "url",
    "url": "https://www.aem.live/home",
    "pageviews": 2620,
    "organic": 1900,
    "metrics": [
      {
        "deviceType": "desktop",
        "pageviews": 2420,
        "lcp": 2099.699999988079,
        "lcpCount": 8,
        "cls": 0.011145537287059668,
        "clsCount": 7,
        "inp": 8,
        "inpCount": 5,
        "ttfb": 548,
        "ttfbCount": 16
      },
      {
        "deviceType": "mobile",
        "pageviews": 100,
        "lcp": 2454.2,
        "lcpCount": 1,
        "cls": 0.26956930913977606,
        "clsCount": 1,
        "inp": null,
        "inpCount": 0,
        "ttfb": 807.2999999858439,
        "ttfbCount": 1
      }
    ]
  },
  {
    "type": "url",
    "url": "https://www.aem.live/docs/",
    "pageviews": 1910,
    "organic": 602,
    "metrics": [
      {
        "deviceType": "desktop",
        "pageviews": 1804,
        "lcp": 665.9000000059605,
        "lcpCount": 11,
        "cls": 0.012401669733174766,
        "clsCount": 11,
        "inp": 32,
        "inpCount": 8,
        "ttfb": 253.20000000298023,
        "ttfbCount": 12
      },
      {
        "deviceType": "mobile",
        "pageviews": 106,
        "lcp": 26276.5,
        "lcpCount": 4,
        "cls": null,
        "clsCount": 5,
        "inp": 48,
        "inpCount": 1,
        "ttfb": 86,
        "ttfbCount": 5
      }
    ]
  }
]

```

### (试验机会)

计算每页无机流量和回弹率。 确定有高无机流量和高回弹率的网页,这些网页可用于今后的试验机会。 下文举例说明有效载荷:

```json
[
  {
    "type": "high-inorganic-high-bounce-rate",
    "page": "https://www.spacecat.com/",
    "screenshot": "",
    "trackedPageKPIName": "Bounce Rate",
    "trackedPageKPIValue": 0.6507592190889371,
    "trackedKPISiteAverage": "",
    "pageViews": 46100,
    "samples": 46100,
    "metrics": [
      {
        "type": "traffic",
        "value": {
          "total": 46100,
          "paid": 40700,
          "owned": 5400,
          "earned": 0
        }
      }
    ]
  },
  {
    "type": "high-inorganic-high-bounce-rate",
    "page": "https://www.spacecat.com/pricing",
    "screenshot": "",
    "trackedPageKPIName": "Bounce Rate",
    "trackedPageKPIValue": 0.8723897911832946,
    "trackedKPISiteAverage": "",
    "pageViews": 43100,
    "samples": 43100,
    "metrics": [
      {
        "type": "traffic",
        "value": {
          "total": 43100,
          "paid": 24100,
          "owned": 19000,
          "earned": 0
        }
      }
    ]
  }
]
```

### (试验机会)

计算非无机(自有和自有)流量和每页和售出者的点击率。 确定非无机流量高和点击率低的网页,这些网页可以针对未来的实验机会.

#### 支持选项

-   **最大机会** - 返回的最大机会数目,默认为10次

下文举例说明有效载荷:

```json
[
  {
    "type": "high-organic-low-ctr",
    "page": "https://www.spacecat.com/about-us",
    "screenshot": "",
    "trackedPageKPIName": "Click Through Rate",
    "trackedPageKPIValue": 0.14316702819956617,
    "trackedKPISiteAverage": 0.40828402366863903,
    "pageViews": 46100,
    "samples": 46100,
    "metrics": [
      {
        "type": "traffic",
        "vendor": "*",
        "value": {
          "total": 46100,
          "paid": 300,
          "owned": 45800,
          "earned": 0
        }
      },
      {
        "type": "ctr",
        "vendor": "*",
        "value": {
          "page": 0.14316702819956617
        }
      },
      {
        "type": "traffic",
        "vendor": "tiktok",
        "value": {
          "total": 300,
          "owned": 0,
          "earned": 0,
          "paid": 300
        }
      },
      {
        "type": "ctr",
        "vendor": "tiktok",
        "value": {
          "page": 0.3333333333333333
        }
      }
    ]
  }
]

```

### 窗体维度

在特定时间间隔内收集指定域的构成关键要素。 确定每个 URL 是否有嵌入式表格并计数 。 这些数据可以推断机会,如低CTR和有限形式参与的URL,高页面浏览但较少形式提交等. 示例答复:

```json
[
  {
    "url": "https://business.adobe.com/",
    "formsubmit": {},
    "formview": {
      "desktop:mac": 800,
      "desktop:windows": 1900,
      "mobile:ios": 100,
      "mobile:android": 300
    },
    "formengagement": {
      "desktop:windows": 100
    },
    "pageview": {
      "desktop:mac": 800,
      "desktop:windows": 1900,
      "mobile:ios": 100,
      "mobile:android": 300
    }
  },
  {
    "url": "https://business.adobe.com/se/resources/main.html",
    "formsubmit": {      
      "desktop:windows": 100
    },
    "formview": {},
    "formengagement": {
      "desktop:windows": 100
    },
    "pageview": {
      "desktop:windows": 100
    }
  }
]
```

### 用户参与

从 RUM 数据计算所有页面的用户参与度量。 如果至少有一些用户互动(点击事件)或重要内容被浏览(4起或更多取景媒体或取景屏蔽事件),则页面视图被视为涉及. 参考文献 - [https://github.com/adobe/rum-distiller/blob/22f8b3caa6d700f4d1cbe29a94b7da34b9d50764/series.js#L89](https://github.com/adobe/rum-distiller/blob/22f8b3caa6d700f4d1cbe29a94b7da34b9d50764/series.js#L89)

示例答复:

```json
[
  {
    "url": "https://www.example.com/home",
    "totalTraffic": 5000,
    "engagementPercentage": 50
  },
  {
    "url": "https://www.example.com/about",
    "totalTraffic": 2000,
    "engagementPercentage": 40
  }
]
```

## 线性

使用 :

```
npm run lint
```

## 清理

要清理软件包( 删除) `node_modules` 财务报告和审定财务报表 `package-lock.json`:

```
npm run clean
```

## 仓库

查找源代码并贡献 [这里](https://github.com/adobe/spacecat-shared.git)。 。 。 .

## 问题

报告问题或错误 [这里](https://github.com/adobe/spacecat-shared/issues)。 。 。 .

## 许可证

这个项目根据Apache-2.0许可证获得许可证.

## 常见问题

### @adobe/spacecat-shared-rum-api-client 是什么？

Spacecat 服务共享模块 - Rum API客户端

### 如何安装 @adobe/spacecat-shared-rum-api-client？

在项目目录运行 npm install @adobe/spacecat-shared-rum-api-client，或使用 pnpm add / yarn add / bun add。

### @adobe/spacecat-shared-rum-api-client 支持 TypeScript 吗？

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

### @adobe/spacecat-shared-rum-api-client 支持 ESM 还是 CommonJS？

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

### @adobe/spacecat-shared-rum-api-client 需要什么版本的 Node\.js？

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

### @adobe/spacecat-shared-rum-api-client 可以商用吗？

@adobe/spacecat-shared-rum-api-client 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @adobe/spacecat-shared-rum-api-client 的下载量有多少？

根据 npm 官方下载统计，@adobe/spacecat-shared-rum-api-client 在 2026/10/05 – 2026/11/03 这 30 天内被下载 1,823 次，日均约 61 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @adobe/spacecat-shared-rum-api-client 还在维护吗？

最新版本 2\.45\.1 发布于 2026/10/09（30 天前）；至今共发布 210 个版本，其中过去 12 个月发布了 26 个；首次发布于 2023/12/12。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。