# @aws/clickstream-react-native 中文文档

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

版本：0\.3\.3
npm 元数据更新时间：2026-06-19T19:30:39.136Z
中文译文更新时间：2026-11-07T21:51:37.565Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40aws/clickstream-react-native
原文对照：https://npmcn.com/package/%40aws/clickstream-react-native/?lang=original
项目主页：https://aws-solutions.github.io/clickstream-analytics-on-aws/en/latest/solution-overview/
源码仓库：https://github.com/aws-solutions/clickstream-analytics-on-aws-react-native-sdk

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

- 包体积（解压后）：220 kB，74 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react-native \*
- 首次发布：2024-04-03T07:07:26.015Z
- 最新版本发布：2025-04-15T20:51:57.158Z
- 近 30 天下载量：2355（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 0 个）

## 中文简介

点击流分析反应原生 SDK

## 安装

```sh
npm install @aws/clickstream-react-native
```

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

## README

# AWS 溶液点击流分析 SDK 反应原生

## 导言

Clickstream React Independent SDK 可以帮助您轻松地收集和报告从React Independent apps到AWS的事件. 这个SDK是 aWS 解决方案的一部分 [在 AWS 上点击流分析](https://github.com/aws-solutions/clickstream-analytics-on-aws),哪个 提供数据管道,将事件数据输入AWS服务,如Amazon S3, Redshift.

SDK依赖于 [点击流 Android SDK](https://github.com/aws-solutions/clickstream-android) 财务报告和审定财务报表 [点击流速 SDK](https://github.com/aws-solutions/clickstream-swift)因此,点击流回放原生SDK 支持自动收集常见的预设事件和属性(如会话启动,先打开). 此外,我们已经 增加了易用API来简化React Industrial apps中的数据收集.

访问 我们 [文件网站](https://aws-solutions.github.io/clickstream-analytics-on-aws/en/latest/sdk-manual/react-native/) 改为 了解更多关于 Clickstream React Independent SDK 的信息.

### 平台支持

**机器人**: 支持Android 4.1 (API 级别为16)并后.

**iOS系统**:支持iOS 13及后.

## 整合 SDK

### 包含 SDK

```bash
$ npm install @aws/clickstream-react-native
```

完成后,您需要安装 iOS 的 sock 依赖性 :

```bash
$ cd ios && pod install
```

### 初始化 SDK

从您的点击流解决方案网络控制台复制您的配置代码, 我们建议您将代码添加到您的应用程序中 切入点像 `index.js`,配置代码应如下。 您也可以手动添加此代码 在您在 Clickstream 中将应用程序注册到数据管道后, 将应用和端点的值片断并替换 分析溶液网络控制台.

```javascript
// index.js

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

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

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

> 记得打电话 `ClickstreamAnalytics.init` 在申请的生命周期内,您必须尽早递交申请。 和确保 sDK在呼叫其他API时被初始化.

### 开始使用

#### 记录事件

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

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

// 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-react-native';

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

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

#### 添加用户属性

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

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

在集成SDK后首次打开Apps时,需要手动设置用户属性一次, 而当前登录用户的属性将会被缓存到磁盘中, 所以下次应用程序打开时不需要设置所有用户 属性,您当然可以使用相同的 API `ClickstreamAnalytics.setUserAttributes()` 以更新当前 用户在变化时的属性.

#### 添加全局属性

1.  初始化 SDK 时添加全局属性
    
    以下示例代码显示在初始化SDK时如何将流量源字段添加为全局属性.
    
    ```typescript
    import { ClickstreamAnalytics, Attr } from '@aws/clickstream-react-native';
    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',
         [Attr.APP_INSTALL_CHANNEL]: 'amazon_store',
       },
    });
    ```
    
2.  初始化 SDK 后添加全局属性
    
    ```typescript
    import { ClickstreamAnalytics, Attr } from '@aws/clickstream-react-native';
    
    ClickstreamAnalytics.setGlobalAttributes({
      [Attr.TRAFFIC_SOURCE_MEDIUM]: "Search engine",
      level: 10,
    });
    ```
    

建议在初始化 SDK 时设置全局属性, 所有事件都将包含全局属性 发生在设定之后.

#### 删除全局属性

```typescript
ClickstreamAnalytics.deleteGlobalAttributes(['level','_traffic_source_medium']);
```

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

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

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

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

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

#### 记录屏幕 手动查看事件

默认情况下, SDK 会自动跟踪预设 `_screen_view` android活动触发时的事件 `onResume` 或者说 iOS 视图控制器触发器 `viewDidAppear`。 。 。 .

您也可以手动记录屏幕查看事件, 是否启用自动屏幕查看跟踪, 添加以下 代码来记录屏幕视图事件,包含两个属性.

-   `SCREEN_NAME` 要求。 你的屏幕的名字.
-   `SCREEN_UNIQUE_ID` 可选的 设定您组件的 ID 。 如果您不设定, SDK 将设定基于默认值 当前活动或视图控制器的散列码.

```typescript
import { ClickstreamAnalytics, Attr, Event } from '@aws/clickstream-react-native';

ClickstreamAnalytics.record({
  name: Event.SCREEN_VIEW,
  attributes: {
    [Attr.SCREEN_NAME]: 'HomeComponet',
    [Attr.SCREEN_UNIQUE_ID]: '123adf',
  },
});
```

#### 使用 React 导航时记录屏幕视图

这个 [实例](https://github.com/aws-samples/clickstream-sdk-samples/pull/25/files#diff-96a74db413b2f02988e5537fdbdf4f307334e8f5ef3a9999df7de3c6785af75bR344-R397) 使用 React Navigation 6.x 时的本地屏幕查看事件

对于其他版本的React Navigation,可以参考官方文档: [分析的屏幕跟踪](https://reactnavigation.org/docs/screen-tracking/)。 。 。 .

#### 其他配置

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

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

ClickstreamAnalytics.init({
  appId: 'your appId',
  endpoint: 'https://example.com/collect',
  isLogEvents: true,
  isCompressEvents: true,
  isTrackScreenViewEvents: false,
  isTrackUserEngagementEvents: true,
  isTrackAppExceptionEvents: true,
  sendEventsInterval: 15000,
  sessionTimeoutDuration: 1800000,
  authCookie: 'your auth cookie',
  globalAttributes: {
    _traffic_source_medium: 'Search engine',
  },
});
```

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

-   **应用( 需要)**: 您工程在溶液网络控制中的应用 id.
-   **结束点( 需要)**: 您将把事件上传到摄取服务器的端点路径 .
-   **是LogEvents 数据**: 是否为调试打印出事件json, 默认是 `false`。 。 。 .
-   **压缩事件**: 上传事件时是否压缩事件内容, 默认是 `true`。 。 。 .
-   **发送事件Interval**: 事件发送间隔毫秒, 只工作洗澡发送模式, 默认值为 `5000`
-   **是 TrackScreenView 事件**: 是否自动记录本地屏幕视图事件, 默认为 `true`
-   **跟踪用户启动事件**: 自动记录用户参与事件,默认是 `true`
-   **是 TrackApp 除外事件**: 是否自动记录本地应用程序的例外事件, 默认为 `false`
-   **发送事件Interval**: 事件发送间隔毫秒,默认值为 `10000` (10个)
-   **会话时长**: 会话超时毫秒,默认为 `1800000` (30分钟)
-   **认证曲奇**: 您用于 AWS 应用程序负载平衡器的 Auth cookie .
-   **全局属性**: SDK 初始化时的全局属性.

#### 配置更新

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

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

ClickstreamAnalytics.updateConfigure({
  appId: 'your appId',
  endpoint: 'https://example.com/collect',
  isLogEvents: true,
  authCookie: 'your auth cookie',
  isCompressEvents: true,
  isTrackPageViewEvents: false,
  isTrackUserEngagementEvents: false,
  isTrackAppExceptionEvents: false,
});
```

#### 在调试模式下日志事件json

```javascript
import { ClickstreamAnalytics } from '@aws/clickstream-react-native';

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

配置后 `isLogEvents:true` 初始化 SDK 时, 当您记录一个事件时, 您可以看到事件 生 json 在 AndroidStudio Logcat 或 Xcode 调试控制台中通过过滤器 `EventRecorder`。 。 。 .

#### 禁用 SDK

您可以在您需要的情况下禁用 SDK 。 SDK拆卸后,SDK将不处理伐木和 发送任何事件。 当然,当你需要继续伐木时,你可以启用SDK.

```javascript
import { ClickstreamAnalytics } from '@aws/clickstream-react-native';

// disable SDK
ClickstreamAnalytics.disable();

// enable SDK
ClickstreamAnalytics.enable();
```

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

本地克隆此寄存器并执行以下脚本生成 `aws-clickstream-react-native-0.3.3.tgz` 拉链 软件包,该软件包将位于工程根文件夹.

```bash
$ cd clickstream-react-native && yarn && yarn run pack
```

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

```bash
$ yarn add ./aws-clickstream-react-native-0.3.3.tgz
```

**说明**: 请更正 SDK 版本, 并将路径更改为 `aws-clickstream-react-native-0.3.3.tgz` 文件为 地点.

你也可以发现 `aws-clickstream-react-native-0.3.3.tgz` 文件输入 页:1 [释放](https://github.com/aws-solutions/clickstream-react-native/releases) 页 次.

### 测试

```bash
$ yarn 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-react-native/CONTRIBUTING.md#security-issue-notifications) 更多信息.

## 许可证

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

虽然此寄存器是在 [Apache 2.0 许可证](https://npmcn.com/package/%40aws/clickstream-react-native/LICENSE),包括一些 [第三方依赖关系](https://npmcn.com/package/%40aws/clickstream-react-native/NOTICE) 与 [蓝橡-1.0.0](https://spdx.org/licenses/BlueOak-1.0.0.html) 执照.

## 常见问题

### @aws/clickstream-react-native 是什么？

点击流分析反应原生 SDK

### 如何安装 @aws/clickstream-react-native？

在项目目录运行 npm install @aws/clickstream-react-native，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react-native（\*）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @aws/clickstream-react-native 支持 TypeScript 吗？

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

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

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

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

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

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

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

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

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