# @aws/clickstream-web 中文文档

规范地址：https://npmcn.com/package/%40aws/clickstream-web/

版本：0\.12\.6
npm 元数据更新时间：2026-06-19T19:30:31.695Z
中文译文更新时间：2026-11-07T14:57:01.949Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40aws/clickstream-web
原文对照：https://npmcn.com/package/%40aws/clickstream-web/?lang=original
项目主页：https://github.com/aws-solutions/clickstream-analytics-on-aws-web-sdk#readme
源码仓库：https://github.com/aws-solutions/clickstream-analytics-on-aws-web-sdk

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

- 包体积（解压后）：329 kB，138 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.16\.0
- 运行依赖：8 个
- 首次发布：2023-08-04T04:03:55.678Z
- 最新版本发布：2025-07-30T22:08:09.707Z
- 近 30 天下载量：11820（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：25（近 12 个月 0 个）

## 中文简介

点击流分析器 Web SDK

## 安装

```sh
npm install @aws/clickstream-web
```

也可以使用：`pnpm add @aws/clickstream-web`、`yarn add @aws/clickstream-web`、`bun add @aws/clickstream-web`

## README

# AWS 解决方案 点击流分析 SDK for Web

## 导言

Clickstream Web SDK可以帮助您轻松地收集和报告从浏览器到AWS的事件. 这个SDK是AWS解决方案的一部分.. [在 AWS 上点击流分析](https://github.com/aws-solutions/clickstream-analytics-on-aws),它提供数据管道,将事件数据摄入并处理到S3,Redshift等AWS服务中.

SDK依赖于用于JS SDK Core库的Amplify,并且根据Amplify Analytics Provider接口来开发. 此外,我们还增加了自动收集常见用户事件和属性(如页面视图,先开)的功能来简化用户的数据收集.

拜访我们 [文件网站](https://aws-solutions.github.io/clickstream-analytics-on-aws/en/latest/sdk-manual/web/) 以了解更多关于 Clickstream Web SDK 的信息.

## 整合 SDK

### 包含 SDK

```bash
$ npm install @aws/clickstream-web
```

### 初始化 SDK

从点击流解决方案网络控制台复制您的配置代码, 我们建议您将代码添加到您的应用程序的根入口上, 例如 `index.js/app.tsx` 在反应中或 `main.ts` 在 Vue/Angular 中,配置代码应类似以下。 您也可以手动添加此代码片段, 并替换您在 Clickstream Analytics 溶液控制台中注册了 app之后的 appId 和 endpoint 的值 .

```typescript
import { ClickstreamAnalytics } from '@aws/clickstream-web';

ClickstreamAnalytics.init({
   appId: "your appId",
   endpoint: "https://example.com/collect",
});
```

 `appId` 财务报告和审定财务报表 `endpoint` 已经设置在里面.

### 开始使用

#### 记录事件

在需要记录事件时添加以下代码 .

```typescript
import { ClickstreamAnalytics } from '@aws/clickstream-web';

// record event with attributes
ClickstreamAnalytics.record({
  name: 'button_click',
  attributes: {
    event_category: 'shoes',
    currency: 'CNY',
    value: 279.9,
  }
});

//record event with name
ClickstreamAnalytics.record({ name: 'button_click' });
```

#### 登录和停用

```typescript
import { ClickstreamAnalytics } from '@aws/clickstream-web';

// when user login success.
ClickstreamAnalytics.setUserId("UserId");

// when user logout
ClickstreamAnalytics.setUserId(null);
```

#### 添加用户属性

```typescript
ClickstreamAnalytics.setUserAttributes({
  userName:"carl",
  userAge: 22
});
```

在集成SDK后首次打开时,您需要手动设置用户属性一次,当前登录用户的属性会在本地Storage中被缓存,所以下次浏览器打开时您不需要再次设置所有用户的属性,当然您可以使用相同的 api `ClickstreamAnalytics.setUserAttributes()` 以更新当前用户的属性.

#### 添加全局属性

1.  初始化 SDK 时添加全局属性
    
    以下示例代码显示在初始化SDK时如何将流量源字段添加为全局属性.
    
    ```typescript
    import { ClickstreamAnalytics, Attr } from '@aws/clickstream-web';
    
    ClickstreamAnalytics.init({
       appId: "your appId",
       endpoint: "https://example.com/collect",
       globalAttributes:{
         [Attr.TRAFFIC_SOURCE_SOURCE]: 'amazon',
         [Attr.TRAFFIC_SOURCE_MEDIUM]: 'cpc',
         [Attr.TRAFFIC_SOURCE_CAMPAIGN]: 'summer_promotion',
         [Attr.TRAFFIC_SOURCE_CAMPAIGN_ID]: 'summer_promotion_01',
         [Attr.TRAFFIC_SOURCE_TERM]: 'running_shoes',
         [Attr.TRAFFIC_SOURCE_CONTENT]: 'banner_ad_1',
         [Attr.TRAFFIC_SOURCE_CLID]: 'amazon_ad_123',
         [Attr.TRAFFIC_SOURCE_CLID_PLATFORM]: 'amazon_ads',
       }
    });
    ```
    
2.  初始化 SDK 后添加全局属性
    
    ```typescript
    import { ClickstreamAnalytics, Attr } from '@aws/clickstream-web';
    
    ClickstreamAnalytics.setGlobalAttributes({
      [Attr.TRAFFIC_SOURCE_MEDIUM]: "Search engine",
      level: 10,
    });
    ```
    

建议在初始化 SDK 时设置全局属性,全局属性将包含在设置后发生的所有事件中,您也可以通过设置其值去除全局属性 `null`。 。 。 .

#### 有项目的记录事件

您可以添加以下代码来记录带有项目的事件 .

**注:只有1.1+版本的管道才能处理带有自定义属性的项目.**

```typescript
import { ClickstreamAnalytics, Item, Attr } from '@aws/clickstream-web';

const itemBook: Item = {
  id: '123',
  name: 'Nature',
  category: 'book',
  price: 99,
  book_publisher: "Nature Research",
};
ClickstreamAnalytics.record({
  name: 'view_item',
  attributes: {
    [Attr.CURRENCY]: 'USD', 
    [Attr.VALUE]: 99,
    event_category: 'recommended',
  },
  items: [itemBook],
});
```

#### 立即以批量模式发送事件

当您处于批量模式时,您仍然可以通过设置 `isImmediate` 属性,如以下代码:

```typescript
import { ClickstreamAnalytics } from '@aws/clickstream-web';

ClickstreamAnalytics.record({
  name: 'button_click',
  isImmediate: true,
});
```

#### 其他配置

除所需外 `appId` 财务报告和审定财务报表 `endpoint`,您可以配置其他信息以获得更定制的用途 :

```typescript
import { ClickstreamAnalytics, EventMode, PageType } from '@aws/clickstream-web';

ClickstreamAnalytics.init({
   appId: "your appId",
   endpoint: "https://example.com/collect",
   sendMode: EventMode.Batch,
   sendEventsInterval: 5000,
   isTrackPageViewEvents: true,
   isTrackUserEngagementEvents: true,
   isTrackClickEvents: true,
   isTrackSearchEvents: true,
   isTrackScrollEvents: true,
   isTrackPageLoadEvents: true,
   isTrackAppStartEvents: true,
   isTrackAppEndEvents: true,
   pageType: PageType.SPA,
   isLogEvents: false,
   authCookie: "your auth cookie",
   sessionTimeoutDuration: 1800000,
   idleTimeoutDuration: 120000,
   searchKeyWords: ['product', 'class'],
   domainList: ['example1.com', 'example2.com'],
});
```

以下是对每个财产的解释:

-   **应用( 需要)**: 您在控制平面上的项目的应用代号.
-   **结束点( 需要)**: 您将把事件上传到 AWS 服务器的终点路径 .
-   **发送模式**: 事件模式。 立即,事件模式。 批,默认为即时模式.
-   **发送事件Interval**: 事件发送间隔毫秒, 只工作洗澡发送模式, 默认值为 `5000`
-   **是 TrackPageView 事件**: 无论是自动记录浏览器中的页面查看事件,默认是 `true`
-   **跟踪用户启动事件**: 自动记录浏览器中的用户参与事件,默认是 `true`
-   **是 Track克事件**: 是否在浏览器中单击自动记录链接事件,默认为 `true`
-   **是追踪事件**: 无论是自动记录浏览器中的搜索结果页面事件,默认是 `true`
-   **是轨迹滚动事件**: 无论是自动记录浏览器中的页面滚动事件,默认是 `true`
-   **是 TrackPageLoad Events 服务器**: 自动记录页面是否在浏览器中加载性能事件, 默认为 `false`
-   **是 TrackAppStart 活动**:当页面可见时,自动记录应用程序是否在浏览器中启动事件,默认是 `false`
-   **是 TrackAppEnd 事件**:当页面变得无形时,自动记录应用程序在浏览器中的结束事件是否为默认 `false`
-   **页面类型**: 网站类型, `SPA` 用于单页应用程序, `multiPageApp` 用于多个页面应用程序,默认为 `SPA`。这个属性只有在属性时才有效 `isTrackPageViewEvents`'值为 `true`
-   **是LogEvents 数据**: 是否打印出调试事件json, 默认是虚假的 .
-   **认证曲奇**: 您用于 AWS 应用程序负载平衡器的 Auth cookie .
-   **会话时长**: 会话超时毫秒, 默认为 1800000
-   **闲置时间间隔**:在触发闲置状态前用户不活动的最大持续时间,默认为120000毫秒,任何超过此阈值的闲置持续时间都会被当前页面上的用户 约定事件去掉.
-   **搜索关键字**: 用于触发的定制关键词 `_search` 事件,默认情况下,我们检测 `q`, (中文(简体) ), `s`, (中文(简体) ), `search`, (中文(简体) ), `query` 财务报告和审定财务报表 `keyword` 在查询参数中.
-   **域列表**:如果您的网站跨越多个域,可以自定义域名列表. 这个 `_outbound` 属性 `_click` 当链接引导到一个不属于您所配置域的网站时,事件将是真的.

#### 配置更新

您可以在初始化 SDK 后更新默认配置, 下面是您可以自定义的额外配置选项 .

```typescript
import { ClickstreamAnalytics } from '@aws/clickstream-web';

ClickstreamAnalytics.updateConfigure({
  isLogEvents: true,
  authCookie: 'your auth cookie',
  isTrackPageViewEvents: false,
  isTrackUserEngagementEvents: false,
  isTrackClickEvents: false,
  isTrackScrollEvents: false,
  isTrackSearchEvents: false,
  isTrackPageLoadEvents: false,
  isTrackAppStartEvents: true,
  isTrackAppEndEvents: true,
});
```

## 在 Google 标签管理器中使用模板执行 Clickstream Web SDK

1.  从中下载 Clickstream SDK 模板文件(.tpl) [SDK 发布页面](https://github.com/aws-solutions/clickstream-analytics-on-aws-web-sdk/releases)。 。 。 .
    
2.  参见 Google 标签管理器 [导入指南](https://developers.google.com/tag-platform/tag-manager/templates#export_and_import) 用于在标签管理控制台中将.tpl文件导入为自定义模板.
    
3.  参见 [使用您的新标签](https://developers.google.com/tag-platform/tag-manager/templates#use_your_new_tag) 在容器中添加 ClickstreamAnatics 标记.
    
4.  点击流分析标记目前支持四种标记类型:
    
    -   初始化 SDK
    -   记录自定义事件
    -   设置用户代号
    -   设置用户属性
    
    注意: 确保您在使用其他 ClickstreamAnatics 标记类型之前先初始化 SDK 标记 .
    

## 如何在当地整合和测试

### 整合 `.tgz` 文件

本地克隆此寄存器并执行以下脚本生成 `aws-clickstream-web-0.12.6.tgz` zip包,将位于工程根文件夹中.

```bash
$ cd clickstream-web && npm i && npm run pack
```

复制 `aws-clickstream-web-0.12.6.tgz` ,然后执行项目根文件夹中的脚本以安装 SDK.

```bash
$ npm install ./aws-clickstream-web-0.12.6.tgz
```

**说明**: 请更正 SDK 版本, 并将路径更改为 `aws-clickstream-web-0.12.6.tgz` 文件已经找到.

### 整合 `clickstream-web.min.js` 文件

执行以下脚本生成 `clickstream-web.min.js`,位于 `/dist` 文件夹.

```bash
$ cd clickstream-web && npm i && npm run pack
```

复制 `clickstream-web.min.js` 将以下初始代码添加到您的工程中 `index.html`。 。 。 .

```html
<script src="clickstream-web.min.js"></script>
<script>
    window.ClickstreamAnalytics.init({
        appId: 'your appId',
        endpoint: 'https://example.com/collect',
        isLogEvents: true,
        pageType: window.PageType.SPA, //multiPageApp
        sendMode: window.SendMode.Batch, //Immediate
    })
</script>
```

你也可以发现 `clickstream-web.min.js` 文档中 [释放](https://github.com/aws-solutions/clickstream-analytics-on-aws-web-sdk/releases) 页 次.

### 测试

```bash
$ npm run test

# with lint
$ sh ./deployment/run-unit-tests.sh
```

## 收集业务指标

这个解决方案收集匿名操作度量,以帮助AWS改进 溶液特性的质量。 更多信息,包括如何禁用 请参看 [执行指南](https://docs.aws.amazon.com/solutions/latest/clickstream-analytics-on-aws)。 。 。 .

## 警卫

见 [捐款](https://npmcn.com/package/%40aws/clickstream-web/CONTRIBUTING.md#security-issue-notifications) 更多信息.

## 许可证

该图书馆根据 [Apache 2.0 许可证](https://npmcn.com/package/%40aws/clickstream-web/LICENSE)。 。 。 .

## 常见问题

### @aws/clickstream-web 是什么？

点击流分析器 Web SDK

### 如何安装 @aws/clickstream-web？

在项目目录运行 npm install @aws/clickstream-web，或使用 pnpm add / yarn add / bun add。

### @aws/clickstream-web 支持 TypeScript 吗？

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

### @aws/clickstream-web 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @aws/clickstream-web 需要什么版本的 Node\.js？

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

### @aws/clickstream-web 可以商用吗？

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

### @aws/clickstream-web 的下载量有多少？

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

### @aws/clickstream-web 还在维护吗？

最新版本 0\.12\.6 发布于 2025/07/31（1\.3 年前）；至今共发布 25 个版本，其中过去 12 个月发布了 0 个；首次发布于 2023/08/04。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。