@aws/clickstream-web

中文文档

0.12.6发布于 2025/07/31Apache-2.0TypeScriptESM + CJS近 30 天下载 1.2万

点击流分析器 Web SDK

文档目录13 节

导言
整合 SDK
包含 SDK
初始化 SDK
开始使用
在 Google 标签管理器中使用模板执行 Clickstream Web SDK
如何在当地整合和测试
整合 .tgz 文件
整合 clickstream-web.min.js 文件
测试
收集业务指标
警卫
许可证

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

导言

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

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

拜访我们文件网站以了解更多关于 Clickstream Web SDK 的信息.

整合 SDK

包含 SDK

$ npm install @aws/clickstream-web

初始化 SDK

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

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

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

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

开始使用

记录事件

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

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' });

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

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

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

添加用户属性

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

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

添加全局属性

初始化 SDK 时添加全局属性

以下示例代码显示在初始化SDK时如何将流量源字段添加为全局属性.

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',
   }
});

初始化 SDK 后添加全局属性

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

ClickstreamAnalytics.setGlobalAttributes({
  [Attr.TRAFFIC_SOURCE_MEDIUM]: "Search engine",
  level: 10,
});

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

有项目的记录事件

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

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

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 属性,如以下代码:

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

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

其他配置

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

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 后更新默认配置, 下面是您可以自定义的额外配置选项 .

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

从中下载 Clickstream SDK 模板文件(.tpl) SDK 发布页面。。。 .
参见 Google 标签管理器导入指南用于在标签管理控制台中将.tpl文件导入为自定义模板.
参见使用您的新标签在容器中添加 ClickstreamAnatics 标记.
点击流分析标记目前支持四种标记类型:
- 初始化 SDK
- 记录自定义事件
- 设置用户代号
- 设置用户属性
注意: 确保您在使用其他 ClickstreamAnatics 标记类型之前先初始化 SDK 标记 .

如何在当地整合和测试

整合 `.tgz` 文件

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

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

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

$ 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 文件夹.

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

复制 clickstream-web.min.js 将以下初始代码添加到您的工程中 index.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 文档中释放页次.

测试

$ npm run test

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

收集业务指标

这个解决方案收集匿名操作度量,以帮助AWS改进溶液特性的质量。更多信息,包括如何禁用请参看执行指南。。。 .

警卫

见捐款更多信息.

许可证

该图书馆根据 Apache 2.0 许可证。。。 .

版本与发布记录

@aws/clickstream-web 共发布 25 个版本，首次发布于 2023/08/04；过去 12 个月发布了 0 个版本。

版本	发布日期	距今
`0.12.6`latest	2025/07/31	1.3 年前
`0.12.5`	2025/05/30	1.4 年前
`0.12.4`	2025/04/10	1.6 年前
`0.12.3`	2025/03/01	1.7 年前
`0.12.2`	2024/08/07	2 年前
`0.12.1`	2024/05/16	2 年前

关于 @aws/clickstream-web 的常见问题

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