# @elastic/behavioral-analytics-javascript-tracker 中文文档

规范地址：https://npmcn.com/package/%40elastic/behavioral-analytics-javascript-tracker/

版本：2\.1\.4
npm 元数据更新时间：2026-09-25T13:38:07.122Z
中文译文更新时间：2026-11-13T11:44:31.054Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40elastic/behavioral-analytics-javascript-tracker
原文对照：https://npmcn.com/package/%40elastic/behavioral-analytics-javascript-tracker/?lang=original

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

- 包体积（解压后）：29.2 kB，17 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2022-12-14T14:27:06.058Z
- 最新版本发布：2023-05-22T13:32:45.680Z
- 近 30 天下载量：4091（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：9（近 12 个月 0 个）

## 中文简介

### 安装

## 安装

```sh
npm install @elastic/behavioral-analytics-javascript-tracker
```

也可以使用：`pnpm add @elastic/behavioral-analytics-javascript-tracker`、`yarn add @elastic/behavioral-analytics-javascript-tracker`、`bun add @elastic/behavioral-analytics-javascript-tracker`

## README

## Javascript 跟踪器

### 安装

您可以使用 npm 或纱线安装跟踪器 :

```bash
yarn add @elastic/behavioral-analytics-javascript-tracker
## OR
npm install @elastic/behavioral-analytics-javascript-tracker
```

## 使用量

导入应用程序中的跟踪器 .

```javascript
import {
  createTracker,
  trackPageView,
  trackSearch,
  trackSearchClick,
} from "@elastic/behavioral-analytics-javascript-tracker";
```

### 初始化跟踪器

使用情况 `createTracker` 用您的 DSN 初始化跟踪器的方法。 您可以在 Collection > 整合下的行为分析 UI 中找到您的 DSN 。 然后您就可以使用跟踪器将事件发送到行为分析中.

```javascript
import {
  createTracker,
  trackPageView,
  trackEvent,
} from "@elastic/behavioral-analytics-javascript-tracker";

createTracker({
  endpoint: "https://my-endpoint-url",
  collectionName: "website",
  apiKey: "<api-key>",
});
```

## 脚印

何时 `createTracker` 追踪器会在浏览器饼干中存储两个指纹:

-   User Token - 用户独有的标识符. 储存在 `EA_UID` 饼干 默认 时间长度自用户首次访问该网站起为24小时.
-   会话托肯 - 会话的独特标识符 。 储存在 `EA_SID` 饼干 时间长度自用户最后一次访问该网站起为30分钟.

这些指纹用于在整个会话中识别用户.

### 更改用户键和时间长度

您可以通过在 `token` 财务报告和审定财务报表 `lifetime` 参数 `createTracker` 方法.

您也可以通过在 `session.lifetime` 参数 `createTracker` 方法.

```js
createTracker({
  user: {
    token: () => "my-user-token", // can be a string too
    lifetime: 24 * 60 * 60 * 1000, // 24 hours
  },
  session: {
    lifetime: 30 * 60 * 1000, // 30 minutes
  },
  }
});
```

### 采用抽样

你并不总是希望所有的会话 被发送到你的弹性集群。 您可以通过添加引入基于会话的抽样 `sampling` 参数 `createTracker` 方法.

如果采样被设定为 1( 默认) , 所有会话都会发送事件 。 如果采样设定为 0, 则不会发送事件 .

```js
createTracker({
  // ... tracker settings
  sampling: 0.3, // 30% of sessions will send events to the server
});
```

### 与搜索用户界面( TODO) 整合

如果您使用 [搜索用户界面](https://npmcn.com/package/%40elastic/behavioral-analytics-javascript-tracker/github.com/elastic/search-ui),可以使用 `AnalyticsPlugin` 锁定自动跟踪搜索事件 。 有关 `AnalyticsPlugin` [这里](https://npmcn.com/package/%40elastic/behavioral-analytics-javascript-tracker/github.com/elastic/search-ui/blob/master/packages/search-analytics-plugin/README.md)。 。 。 .

```javascript
import AnalyticsPlugin from "@elastic/search-ui-analytics-plugin";
import { getTracker } from "@elastic/behavioral-analytics-javascript-tracker";

const searchUIConfig = {
  ...
  plugins: [AnalyticsPlugin({
    client: getTracker()
  })],
  ...
}
```

### 发送页面视图事件

然后可以使用跟踪器跟踪页面视图.

```javascript
// track a page view

const SearchPage = (props) => {
  useEffect(() => {
    trackPageView({
      // optional
      document: {
        id: "search-page",
        index: "pages",
      },
    });
  }, []);

  return (
    <div>
      <h1>Search Page</h1>
    </div>
  );
};
```

### 调度搜索事件

这些事件被用来跟踪用户的搜索行为. 你可以通过呼叫 `trackSearch` 方法.

下面是用户搜索查询,假设搜索API时如何发送搜索事件的例子.

```typescript
import { trackSearch } from "@elastic/behavioral-analytics-javascript-tracker";

const getSearchResults = async (query: string) => {
  const results = await api.getSearchResults(query);
  trackSearch({
    search: {
      query: query,
      results: {
        // optional
        items: [],
        total_results: results.totalResults,
      },
    },
  });
};
```

完整的属性列表可以传递给 `trackSearch` 方法如下:

```javascript
trackSearch({
  search: {
    query: "laptop",
    filters: [
      // optional
      { field: "brand", value: ["apple"] },
    ],
    page: {
      //optional
      current: 1,
      size: 10,
    },
    results: {
      // optional
      items: [
        {
          document: {
            id: "123",
            index: "products",
          },
          page: {
            url: "http://my-website.com/products/123",
          },
        },
      ],
      total_results: 100,
    },
    sort: {
      name: "relevance",
    },
    search_application: "website",
  },
});
```

### 调度搜索点击事件

这些事件用于跟踪用户的搜索点击行为. 以追踪用户在进行搜索后点击的内容。 你可以通过呼叫 `trackSearchClick` 方法.

以下是用户点击搜索结果时如何发送搜索点击事件的例子,用于假设搜索API.

```typescript
import { trackSearchClick } from "@elastic/behavioral-analytics-javascript-tracker";

trackSearchClick({
  // document that they clicked on
  document: { id: "123", index: "products" },
  // the query and results that they used to find this document
  search: {
    query: "laptop",
    filters: [
      { field: "brand", value: ["apple"] },
      { field: "price", value: ["1000-2000"] },
    ],
    page: {
      current: 1,
      size: 10,
    },
    results: {
      items: [
        {
          document: {
            id: "123",
            index: "products",
          },
          page: {
            url: "http://my-website.com/products/123",
          },
        },
      ],
      total_results: 100,
    },
    sort: {
      name: "relevance",
    },
    search_application: "website",
  },
});
```

## 共同问题

### 当我试图发出一个事件, 我得到以下错误: `behavioral Analytics: Tracker not initialized.`

这意味着追踪器还没有被初始化. 您需要初始化跟踪器才能发送事件 。 你可以打给 `createTracker` 方法.

## API 方法

### `createTracker`

以给定的配置初始化跟踪器。 在使用跟踪器之前,必须使用这种方法.

```javascript
import { createTracker } from "@elastic/behavioral-analytics-javascript-tracker";

createTracker({
  endpoint: "https://my-analytics-dsn.elastic.co",
  collectionName: "website",
  apiKey: "<api-key>",
});
```

#### 示例

```javascript
createTracker({});
```

#### 参数

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| 选项 | 跟踪选项 | 追踪器的选项 . |

#### 跟踪选项

追踪器的选项 .

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| 用户. token | () qq字符串 qq字符串 | 返回用户符号的字符串或函数 . |
| 用户。寿命 | 编号 | 用户代币的过期日期 . |
| 结束点 | 字符串 | 事件终点. 您可以在收藏下的行为分析UI中找到你的终点 > 整合. |
| 收藏库Name | 字符串 | 您可以在 Collection > 整合下的行为分析UI 中找到您的收藏名称 . |
| 键 | 字符串 | 端点的阿皮基 您可以在“ 收集” > “ 整合” 下的行为分析UI中找到. |

### `trackPageView`

跟踪页面视图事件.

```javascript
trackPageView();
```

#### 示例

```javascript
import { trackPageView } from "@elastic/behavioral-analytics-javascript-tracker";

trackPageView({
  document: {
    id: "123",
    index: "products",
  },
});
```

#### 参数

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| 属性 | 页面查看输出收益 | 事件属性. |

### `trackSearch`

跟踪自定义事件.

```ts
trackSearch(
  properties: SearchEventInputProperties
)
```

#### 示例

```javascript
import { trackSearch } from "@elastic/behavioral-analytics-javascript-tracker";

trackSearch({
  search: {
    query: "laptop",
    filters: [
      { field: "brand", value: ["apple"] },
      { field: "price", value: ["1000-2000"] },
    ],
    page: {
      current: 1,
      size: 10,
    },
    results: {
      items: [
        {
          document: {
            id: "123",
            index: "products",
          },
          page: {
            url: "http://my-website.com/products/123",
          },
        },
      ],
      total_results: 100,
    },
    sort: {
      name: "relevance",
    },
    search_application: "website",
  },
});
```

### `trackSearchClick`

跟踪与搜索事件有关的点击。 使用的实例是用户点击搜索查询的结果.

肯定有一个 `document` 或者说 `page` 属性。 最佳两种.

```ts
trackSearchClick(
  properties: SearchClickEventInputProperties
)
```

#### 示例

```javascript
import { trackSearchClick } from "@elastic/behavioral-analytics-javascript-tracker";

trackSearchClick({
  document: {
    id: "123",
    index: "products",
  },
  page: {
    url: "http://my-website.com/products/123",
    title: "My Product",
  },
  search: {
    query: "laptop",
    filters: [
      { field: "brand", value: ["apple"] },
      { field: "price", value: ["1000-2000"] },
    ],
    page: {
      current: 1,
      size: 10,
    },
    results: {
      items: [
        {
          document: {
            id: "123",
            index: "products",
          },
          page: {
            url: "http://my-website.com/products/123",
          },
        },
      ],
      total_results: 100,
    },
    sort: {
      name: "relevance",
    },
    search_application: "website",
  },
});
```

#### 参数

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| 属性 | 搜索 ClickEvent 输出收益 | 事件属性. |

### `getTracker`

返回跟踪器实例 。 用于与搜索用户界面分析插件集成时有用 .

```javascript
import { getTracker } from "@elastic/behavioral-analytics-javascript-tracker";

const tracker = getTracker();
```

## 常见问题

### @elastic/behavioral-analytics-javascript-tracker 是什么？

安装

### 如何安装 @elastic/behavioral-analytics-javascript-tracker？

在项目目录运行 npm install @elastic/behavioral-analytics-javascript-tracker，或使用 pnpm add / yarn add / bun add。

### @elastic/behavioral-analytics-javascript-tracker 支持 TypeScript 吗？

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

### @elastic/behavioral-analytics-javascript-tracker 支持 ESM 还是 CommonJS？

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

### @elastic/behavioral-analytics-javascript-tracker 可以商用吗？

@elastic/behavioral-analytics-javascript-tracker 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @elastic/behavioral-analytics-javascript-tracker 的下载量有多少？

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

### @elastic/behavioral-analytics-javascript-tracker 还在维护吗？

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