# @altertable/altertable-js 中文文档

规范地址：https://npmcn.com/package/%40altertable/altertable-js/

版本：1\.5\.0
npm 元数据更新时间：2026-11-03T13:35:32.574Z
中文译文更新时间：2026-11-06T22:22:10.952Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40altertable/altertable-js
原文对照：https://npmcn.com/package/%40altertable/altertable-js/?lang=original
项目主页：https://github.com/altertable-ai/altertable-js
源码仓库：https://github.com/altertable-ai/altertable-js

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

- 包体积（解压后）：718 kB，11 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2025-06-26T14:42:27.679Z
- 最新版本发布：2026-11-03T13:35:32.133Z
- 近 30 天下载量：2264（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：23（近 12 个月 13 个）

## 中文简介

JavaScript SDK可以捕捉并发送事件到Altertable.

## 安装

```sh
npm install @altertable/altertable-js
```

也可以使用：`pnpm add @altertable/altertable-js`、`yarn add @altertable/altertable-js`、`bun add @altertable/altertable-js`

## README

# @ taltertable/taltertable-js (中文(简体) )

JavaScript SDK用于捕获并发送分析事件到Altertable.

## 安装

```bash
npm install @altertable/altertable-js
# or
pnpm add @altertable/altertable-js
# or
yarn add @altertable/altertable-js
# or
bun add @altertable/altertable-js
```

## 快速启动

```javascript
import { altertable } from '@altertable/altertable-js';

// Initialize with your API key
altertable.init('YOUR_API_KEY');

// Track an event
altertable.track('Step Completed', {
  step: 1,
});

// Identify a user
altertable.identify('u_01jza857w4f23s1hf2s61befmw', {
  email: 'john.doe@example.com',
  name: 'John Doe',
  company: 'Acme Corp',
  role: 'Software Engineer',
});

// Update user traits
altertable.updateTraits({
  onboarding_completed: true,
});

// Link a new ID to the current identity
altertable.alias('new_user_id-019aca6a-1e42-71af-81a0-1e14bbe2ccbd');
```

## 特征

-   **自动页面视图跟踪** - 自动抓取页面视图
-   **会话管理** - 自动处理匿名和会话ID
-   **离线交付** — 浏览器上线时, 恒定事件和重试
-   **活动排队** - 等待同意的事件排队
-   **遵守隐私** - 内部跟踪同意管理
-   **多个存储选项** - 本地Storage、饼干或两者兼有
-   **类型脚本支持** - 包含全部类型脚本定义
-   **轻巧** - 无外部依赖的最小捆绑大小

## API 参考

### 初始化

#### `altertable.init(apiKey, config?)`

以您的 API 密钥和可选配置初始化 .

**参数:**

| 参数 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `apiKey` | `string` | 对 | 您的目标环境的可调整 API 密钥 |
| `config` | [`AltertableConfig`](https://npmcn.com/package/%40altertable/altertable-js/#readme-altertableconfig) | 没有 | 配置选项 |

**示例**

```javascript
altertable.init('YOUR_API_KEY');
```

通话 `init` 替换配置和 **丢弃** 输出批量缓冲中的任何事件。 如果您需要先发送( 例如在切换 API 密钥之前) , `await altertable.flush()` 打电话前 `init` 再来一次.

### 事件跟踪

#### `altertable.track(event, properties?)`

跟踪带有可选属性的自定义事件.

**参数:**

| 参数 | 类型 | 需求 | 默认 | 说明 |
| --- | --- | --- | --- | --- |
| `event` | `string` | 对 | \- 说吧 | 事件名称 |
| `properties` | [`EventProperties`](https://npmcn.com/package/%40altertable/altertable-js/#readme-eventproperties) | 没有 | `{}` | 自定义事件属性 |

**示例**

```javascript
altertable.track('Purchase Completed', {
  product_id: 'p_01jza8fr5efvgbxxdd1bwkd0m5',
  amount: 29.99,
  currency: 'USD',
});
```

#### `altertable.page(url)`

跟踪页面视图事件.

何时 [`autoCapture`](https://npmcn.com/package/%40altertable/altertable-js/#readme-autocapture) 启用,当页面 URL 更改时,此方法会自动调用.

**参数:**

| 参数 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `url` | `string` | 对 | 页面 URL |

**示例**

```javascript
altertable.page('https://example.com/products');
```

> \[注\]
> 
> **跟踪**:默认情况下,Altertable自动抓取页面浏览. 仅使用 `page()` 当你被禁用自动捕捉.
> 
> **为什么要使用自动抓取( 默认) ?**
> 
> -   无需手工跟踪
> -   处理浏览器导航事件( M)[`popstate`](https://developer.mozilla.org/docs/Web/API/Window/popstate_event), (中文(简体) ), [`hashchange`](https://developer.mozilla.org/docs/Web/API/Window/hashchange_event)(中文(简体) )
> -   对所有页面更改进行一致跟踪
> 
> **何时使用 `page()`数字 :**
> 
> -   自定义不会触发浏览器事件的路由
> -   不触发 URL 更改的虚拟页面视图( 模式, 步骤更改)
> -   无法自动抓取的服务器端跟踪

#### 现有分析适配器

重用现有的 PostHog 执行而不改变其跟踪呼叫 . 初始化 PostHog 之前的可变性 :

```javascript
import posthog from 'posthog-js';
import { altertable } from '@altertable/altertable-js';

altertable.init('ALTERTABLE_KEY', {
  adapters: { posthog },
});

posthog.init('POSTHOG_KEY');
```

改变可移动 PostHog 事件并禁用自己的收藏 . `track`, (中文(简体) ), `page`, (中文(简体) ), `identify`, (中文(简体) ), `alias`,以及 `updateTraits` 电话被忽略 在配置适配器时,自动抓取不动.

#### 转变事件

使用 `transformEvent` 以自定义在 SDK队列,坚持或发送. 变压器也自动运行 抓取的页面视图, 这样您就可以丰富它们而不会损坏 `autoCapture` 或者说 添加路由器特定跟踪码.

```typescript
altertable.init('YOUR_API_KEY', {
  transformEvent(event) {
    if (event.event === '$pageview') {
      return {
        ...event,
        properties: {
          ...event.properties,
          title: document.title,
          content_group: 'documentation',
        },
      };
    }

    return event;
  },
});
```

呼叫收到完整 [`TrackPayload`](https://npmcn.com/package/%40altertable/altertable-js/#readme-trackpayload),包括: 事件名称、生成上下文、时间戳和默认属性。 它运行 同步创建的事件 `track()` 财务报告和审定财务报表 `page()`;适配器,身份, 和别名有效载荷不改变.

返回时 `null` 丢弃事件 :

```typescript
altertable.init('YOUR_API_KEY', {
  transformEvent(event) {
    if (event.properties.internal_traffic === true) {
      return null;
    }

    return event;
  },
});
```

如果变压器抛出, 变压表会丢弃事件而不是发送 原始载荷。 错误已被记录并传递到 `onError` 错误时 处理器已配置 。 您可以替换 `transformEvent` 运行时间 `altertable.configure({ transformEvent })`。 。 。 .

### 用户标识

#### `altertable.identify(userId, traits?)`

识别用户的ID和可选特征. 它标出身份为身份识别的用户.

**参数:**

| 参数 | 类型 | 需求 | 默认 | 说明 |
| --- | --- | --- | --- | --- |
| `userId` | `string` | 对 | \- 说吧 | 用户独有的标识符 |
| `traits` | [`UserTraits`](https://npmcn.com/package/%40altertable/altertable-js/#readme-usertraits) | 没有 | `{}` | 用户属性 |

**示例**

```javascript
altertable.identify('u_01jza857w4f23s1hf2s61befmw', {
  email: 'john.doe@example.com',
  name: 'John Doe',
  company: 'Acme Corp',
  role: 'Software Engineer',
});
```

#### `altertable.updateTraits(traits)`

更新当前用户的用户特性.

**参数:**

| 参数 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `traits` | [`UserTraits`](https://npmcn.com/package/%40altertable/altertable-js/#readme-usertraits) | 对 | 要更新的用户属性 |

**示例**

```javascript
altertable.updateTraits({
  onboarding_completed: true,
});
```

#### `altertable.alias(newUserId)`

链接到当前身份的新ID.

**参数:**

| 参数 | 类型 | 需求 | 默认 | 说明 |
| --- | --- | --- | --- | --- |
| `newUserId` | `string` | 对 | \- -- - -- | 连接当前身份的新 ID |

**示例**

```javascript
altertable.alias('new_user_id-019aca6a-1e42-71af-81a0-1e14bbe2ccbd');
```

### 会话管理

#### `altertable.reset(options?)`

重新设置当前身份背景, 因此未来事件与前一个用户无关 .

**参数:**

| 参数 | 类型 | 需求 | 默认 | 说明 |
| --- | --- | --- | --- | --- |
| `options` | `object` | 没有 | `{}` | 重置选项 |
| `options.resetDeviceId` | `boolean` | 没有 | `false` | 是否重置设备 ID |

**示例**

```javascript
// Reset everything except device ID
altertable.reset();

// Reset all IDs
altertable.reset({
  resetDeviceId: true,
});
```

### 配置

#### `altertable.configure(updates)`

初始化后更新配置。 A 类 `baseUrl` 更改适用于新的 请求; 已经在飞行中的批次保留其原目的地的回转. 如果启用自动抓取失败订阅, 请拨打 `configure({ autoCapture: true })` 重新进行注册.

**参数:**

| 参数 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `updates` | [`AltertableConfigUpdates`](https://npmcn.com/package/%40altertable/altertable-js/#readme-altertableconfigupdates) | 对 | 配置更新 |

**示例**

```javascript
altertable.configure({
  trackingConsent: 'granted',
});
```

### 隐私和同意

#### `altertable.getTrackingConsent()`

返回当前跟踪同意状态.

**回返情况:** [`TrackingConsentType`](https://npmcn.com/package/%40altertable/altertable-js/#readme-trackingconsenttype)

**示例**

```javascript
const consent = altertable.getTrackingConsent();
if (consent === 'granted') {
  // Tracking is allowed
}
```

## 类型

### `AltertableConfig`

变相 SDK 的配置选项 .

| 财产 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `baseUrl` | `string` | `"https://api.altertable.ai"` | 迁移 API 的基础 URL |
| `adapters` | `Adapters` | \- 说吧 | 现有分析实例; 目前 `{ posthog }` |
| `mode` | [`TrackingMode`](https://npmcn.com/package/%40altertable/altertable-js/#readme-trackingmode) | `"product"` | 产品分析或限制受众测量;固定到下一次 `init()` |
| `autoCapture` | `boolean` | `true`; 在设置适配器时关闭 | 是否自动抓取页面视图和事件 |
| `release` | `string` | \- 说吧 | 应用程序的发布 ID |
| `debug` | `boolean` | `false` | 是否将事件记录到控制台 |
| `persistence` | [`StorageType`](https://npmcn.com/package/%40altertable/altertable-js/#readme-storagetype) | `"localStorage+cookie"` | 身份证的持久性战略 |
| `eventPersistence` | [`StorageType`](https://npmcn.com/package/%40altertable/altertable-js/#readme-storagetype) 或者说 `false` | 与 `persistence` | 未定事件有效载荷的持久性战略 |
| `trackingConsent` | [`TrackingConsentType`](https://npmcn.com/package/%40altertable/altertable-js/#readme-trackingconsenttype) | `"granted"` | 追踪同意状态 |
| `onError` | `(error: Error) => void` | \- 说吧 | SDK 错误的可选处理器 |
| `transformEvent` | [`TransformEvent`](https://npmcn.com/package/%40altertable/altertable-js/#readme-transformevent) | \- 说吧 | 变形或丢弃音轨和页面视图事件 |
| `flushEventThreshold` | `number` | `20` | 当综合缓冲事件达到这个计数时, 浮起 |
| `flushIntervalMs` | `number` | `150` | 定期批次冲洗间隔( 毫秒) |
| `maxBatchSize` | `number` | `20` | HTTP 请求中的最大有效载荷 |

#### 观众计量

使用受众模式来收集总体使用统计,而不会持续 客户端标识符 :

```javascript
altertable.init('YOUR_API_KEY', { mode: 'audience' });
altertable.track('Install Copied', { package: 'react' });
```

页面视图和自定义事件会自动使用观众处理. 在这个模式下, 这个SDK:

-   Omits 用户,匿名,会话,以及事件的设备ID.
-   在记忆中保持身份、同意和未发生事件,压倒一切的持久性 选项。 保存的数据不恢复,在重新装入时丢失了未发送的事件.
-   忽略 `identify()`, (中文(简体) ), `alias()`,以及 `updateTraits()` 打电话.
-   删除 URL 证书、 查询参数、 碎片、 裁判路径以及 视图数据. 无效、 相对和非 HTTP URL 变为 `null`。 。 。 .
-   Omits 浏览器请求所有发送的证书和 HTTP 推荐人 .

事件名称,自定义属性,和URL路径可以包含个人数据. 使用 `transformEvent` 在传输前删除它。 SDK应用观众 改造后的限制。 适应器前进源身份和 属性,不支持受众模式.

`trackingConsent` 控制交付:等待或解除事件等待内存, 和否认的事件被抛弃。 提供每份同意书 `init()`。 。 。 .

要更改模式, 请调用 `init()`。 。 。 . `configure()` 无法更改 `mode`。 。 。 . 重新初始化丢弃缓冲事件; 调用 `flush()` 首先,如果你想的话 派他们来.

##### 搜索测量

观众模式条列搜索查询参数,例如 `q` 从自动页面 追踪。 跟踪搜索,明确用来测量使用情况和结果计数:

```javascript
altertable.track('Search Performed', {
  category: 'documentation',
  result_count: results.length,
});
```

搜索术语可以包含个人数据. 如果你需要收集,明确 添加一个 `search_term` 属性,然后审查哪些值可以安全发送.

#### 离线交付

变相器可以坚持未发生事件的有效载荷,这样它们就可以活下来再装入并当浏览器回到网上时发送. 默认情况下,事件有效载荷使用的存储策略与 [`persistence`](https://npmcn.com/package/%40altertable/altertable-js/#readme-altertableconfig),但饼干支持的战略将事件有效载荷存储在 `localStorage` 只有这个.

如果您不希望将事件有效载荷写入持久浏览器存储, 设置 `eventPersistence: false`。事件会作为当前页面会话的内存进行分批处理,但不会在重载中幸存.

```javascript
altertable.init('YOUR_API_KEY', {
  eventPersistence: false,
});
```

### `AltertableConfigUpdates`

接受的选项 `configure()`。包括 `AltertableConfig` 除外 `mode`,通过 `init()`。 。 。 .

### `EventProperties`

自定义事件属性 .

```typescript
type EventProperties = Record<string, unknown>;
```

**示例**

```javascript
{
  product_id: 'p_01jza8fr5efvgbxxdd1bwkd0m5',
  amount: 29.99,
  currency: 'USD',
  category: 'electronics',
  user_type: 'premium'
}
```

### `TrackPayload`

整个有效载荷传到 `transformEvent` 在两种跟踪模式中。 产品 模式发送已转换 `TrackPayload`; 观众模式应用其限制 发送 `AudienceTrackPayload` 没有身份.

```typescript
type TrackPayload = {
  event: string;
  properties: EventProperties;
  timestamp: string;
  device_id: `device-${string}`;
  distinct_id: string;
  anonymous_id: `anonymous-${string}` | null;
  session_id: `session-${string}`;
};
```

### `AudienceTrackPayload`

观众有效载荷发送到轨道API之后 `transformEvent`数字 :

```typescript
type AudienceTrackPayload = {
  mode: 'audience';
  event: string;
  properties: EventProperties;
  timestamp: string;
};
```

### `TransformEvent`

```typescript
type TransformEvent = (event: TrackPayload) => TrackPayload | null;
```

`EventProperties`, (中文(简体) ), `TrackPayload`, (中文(简体) ), `AudienceTrackPayload`,以及 `TransformEvent` 从 `@altertable/altertable-js` 用于应用代码.

### `UserTraits`

用户属性用于识别.

```typescript
type UserTraits = Record<string, unknown>;
```

**示例**

```javascript
{
  email: 'john.doe@example.com',
  name: 'John Doe',
  company: 'Acme Corp',
  role: 'Software Engineer',
  plan: 'premium',
  signup_date: '2024-01-15'
}
```

### `StorageType`

`persistence` 财务报告和审定财务报表 `eventPersistence` 也接受自定义同步存储 适配器. 它必须执行 `getItem(key): string | null`, (中文(简体) ), `setItem(key, value): boolean`,以及 `removeItem(key): void`返回时 `false` 从 `setItem` 当写作失败时。 Async 后端必须在水合之前完成 初始化并提供同步的相模适配器; 不通过相模 直接存储 API.

丢弃自定义写和删除出错 `onError`。失败事件写出请假 存储错误不会重排已确认的事件。 读取 错误传播到 `init()` 或者说 `configure()`;在迁移失败后读取,请修正 后端并重试相同的配置.

使用导出 `getStorageKeys(apiKey)` 以解析 API 密钥瞄准镜 `session` 财务报告和审定财务报表 `events` 水合前键. 对于自定义运行时间, 提供 a [平台](https://npmcn.com/package/%40altertable/altertable-js/#readme-runtime-platforms) 给建筑师. 内容 `isOnline()` 方法读取连接; 返回 `false` 保留缓冲 事件直到稍后冲出.

这个 `Altertable` 为需要单独的应用程序导出构造器 客户实例。 调用返回的清理函数 `init()` 处理时 一个实例.

可用存储策略.

| 数值 | 说明 |
| --- | --- |
| `"localStorage"` | 仅使用本地Storage |
| `"sessionStorage"` | 只使用会话集 |
| `"cookie"` | 仅使用 cookie |
| `"memory"` | 使用内存(未持续) |
| `"localStorage+cookie"` | 使用本地 Storage 与 cookie 回落 |

### `TrackingMode`

| 数值 | 行为 |
| --- | --- |
| `"product"` | 具有特性、特征和可配置持久性的产品分析. |
| `"audience"` | 在没有持续客户标识的情况下,对总使用量进行测量. |

### `TrackingConsentType`

现有追踪同意状态.

| 数值 | 说明 |
| --- | --- |
| `"granted"` | 用户已同意跟踪 |
| `"denied"` | 用户拒绝同意跟踪 |
| `"pending"` | 用户还没有做决定 |
| `"dismissed"` | 用户拒绝立即同意 |

## 运行时平台

`new Altertable()` 用途 `browserPlatform` 默认。 供应a `Platform` 页:1 在另一个运行时间托管核心SDK时的构造器 。 月台已经修好了 客户寿终正寝,且可在 `init()`,所以队列事件保留 记录它们时的上下文.

```typescript
import { Altertable, type Platform } from '@altertable/altertable-js';

const platform: Platform = {
  getContext: () => ({ properties: { runtime: 'worker' } }),
};

const client = new Altertable(platform);
client.track('Started');
const cleanup = client.init('YOUR_API_KEY', { persistence: 'memory' });
await client.flush();
cleanup();
```

| 能力 | 合同 |
| --- | --- |
| `getContext()` | 返回当前 URL、 引用者、 视图和默认事件 `properties`。 浏览器字段变为 `null`。事件属性可以覆盖默认值. |
| `isOnline()` | 读取互联互通而无副作用. 假设它是连通的. |
| `subscribeLifecycle(listener)` | 报告 `active`, (中文(简体) ), `inactive`, (中文(简体) ), `online`,或 `exit`; 返回清理函数。 活动,不活动,和在线活动请求正常发送. |
| `subscribeUrlChanges(listener)` | 报告随后的 URL 更改;返回清理函数 。 与 `autoCapture` 启用后, SDK 将初始 URL 记录下来, 并用先前的 URL 作为参考器跟踪变化 . |
| `prepareDelivery()` | 在发送每个固定的正常快递前等待先决条件 。 解决 `true` 或者说 `undefined` 继续, `false` 推迟或拒绝阻止这种企图。 这不会用于出站运输或每个HTTP重试. |
| `sendOnExit({ url, body })` | 可选提供同步最优出站交付. 事件持续到正常交付成功为止。 如果没有这种能力,退出事件要求正常交付. |

仅 `getContext()` 需要时间。 订阅缺失使这些整合无法进行; sDK 不替代浏览器执行 平台。 储存仍然是通过 `persistence` 财务报告和审定财务报表 `eventPersistence`,接受 `StorageAdapter`。 。 。 .

正常交付尊重跟踪同意和连接。 用于平台 同步交付准备、相重叠的自动请求合在一起; 新阈值事件触发后续快照, 而失败的请求等待 为后起触发. 重叠生命周期或间隔请求共享当前 快照; 阈值以下的事件仍然分批进行到下一个触发. 快照在准备开始前选择活动;后来抵达者需要他们 自己准备的快照。 明确 `flush()` 继续排水,准备每一次新的 示意图. `flush({ drain: false })` 共享这些自动传送任务 平台。 准备失败 `onError` 自动尝试和拒绝 明显的冲出.

清理停止了平台订阅,定时器,并进一步交付. 订阅 在清理运行前取消所有者名, 因此队列了回调和回调 被失败的清理保留会被忽略 。 已退役的批发器无法修改存储 当旧的要求完成。 清理、重置和拒绝同意取消HTTP重试; 清理和重新初始化也防止了有待准备的工作开始停滞 交货。 在继续使用清理客户端之前重新初始化 .

要扩展浏览器行为, 直接构成导出的执行 :

```typescript
import { Altertable, browserPlatform } from '@altertable/altertable-js';

const client = new Altertable({
  ...browserPlatform,
  getContext() {
    return {
      ...browserPlatform.getContext(),
      properties: { application: 'dashboard' },
    };
  },
});
```

React 本地软件包提供本地环境, App State 生命周期处理, 可选连接,并通过此同步存储准备 合同。 分析提供者订阅独立于浏览器检测; 配置的供应商必须履行自己的适配器合同.

## 许可证

[麻省理工学院](https://npmcn.com/package/%40altertable/altertable-js/LICENSE)

## 常见问题

### @altertable/altertable-js 是什么？

JavaScript SDK可以捕捉并发送事件到Altertable\.

### 如何安装 @altertable/altertable-js？

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

### @altertable/altertable-js 支持 TypeScript 吗？

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

### @altertable/altertable-js 支持 ESM 还是 CommonJS？

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

### @altertable/altertable-js 可以商用吗？

@altertable/altertable-js 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @altertable/altertable-js 的下载量有多少？

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

### @altertable/altertable-js 还在维护吗？

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