---
topic: JavaScript SDK 速查手册
sources:
  - raw/接入指南/客户端-sdk/javascript.md
  - raw/接入指南/客户端-sdk/javascript/进阶指南.md
  - raw/接入前准备工作/用户识别规则.md
  - raw/接入前准备工作/预置属性与系统字段.md
generated: 2026-04-15
---

# JavaScript SDK 速查手册

适用于 Web（Vue2/3、React、Angular）及 Electron 桌面应用。最新版本 **v2.3.1**（2026-01-07）[[raw/接入指南/客户端-sdk/javascript.md]]。

## 安装

```bash
# npm
npm install thinkingdata-browser --save
```

或者手动载入（`thinkingdata.min.js` 异步 / `thinkingdata.umd.min.js` 同步）。

## 初始化

```js
import ta from "thinkingdata-browser";
ta.init({
  appId: "YOUR_APP_ID",               // 必填
  serverUrl: "https://YOUR_SERVER_URL/sync_js", // 必填；云服务用 https://global-receiver-ta.thinkingdata.cn
  autoTrack: {
    pageShow: true,   // 自动采集页面展示事件 ta_page_show
    pageHide: true,   // 自动采集页面隐藏事件 ta_page_hide
  }
});
```

[[raw/接入指南/客户端-sdk/javascript.md]]

## 用户 ID 管理

AE 使用三层 ID 体系：访客 ID（`#distinct_id`）、账号 ID（`#account_id`）、AE 用户 ID（系统内部）[[raw/接入前准备工作/用户识别规则.md]]。

```js
// 设置自定义访客 ID（一般不需要，SDK 自动生成）
ta.setDistinctId("custom-visitor-id");

// 获取访客 ID
const vid = ta.getDistinctId();

// 用户登录 → 设置账号 ID
ta.login("user-account-id");   // 不会上报登录事件

// 用户登出 → 清除账号 ID
ta.logout();                   // 不会上报登出事件
```

[[raw/接入指南/客户端-sdk/javascript/进阶指南.md]]

## 事件上报

```js
// 普通事件
ta.track("product_buy", { product_name: "商品名", price: 99 });

// 首次事件（同设备只记录一次）
ta.trackFirstEvent("first_launch", {}, "first_check_id");

// 可更新事件
ta.trackUpdate("order_pay", { status: "paid" }, "ORDER_ID_001");

// 可覆盖事件
ta.trackOverwrite("order_pay", { status: "refunded" }, "ORDER_ID_001");
```

事件名只能以字母开头，包含字母/数字/下划线，最长 50 字符 [[raw/接入指南/客户端-sdk/javascript.md]]。

## 公共事件属性

```js
// 设置（持久化到缓存）
ta.setSuperProperties({
  channel: "ta",
  age: 25,
  isVip: true,
  birthday: new Date(),
  obj: { key: "value" },
  arr: ["a", "b"]
});

// 动态超级属性（每次 track 时实时计算）
ta.setDynamicSuperProperties(() => ({ current_time: Date.now() }));

// 清除单个
ta.unsetSuperProperties("channel");

// 清除全部
ta.clearSuperProperties();

// 设置页面级属性
ta.setPageProperty({ page_title: document.title });
```

[[raw/接入指南/客户端-sdk/javascript/进阶指南.md]]

## 用户属性

```js
ta.userSet({ username: "Alice", level: 10 });       // 覆盖
ta.userSetOnce({ register_date: new Date() });       // 仅首次设置生效
ta.userAdd({ total_spend: 99.9 });                   // 数值累加
ta.userDel();                                        // 删除用户
```

## 时间事件

```js
// 开始计时
ta.timeEvent("product_view");
// 触发时自动附加 #duration 属性（秒）
ta.track("product_view", { product_id: "P001" });
```

## 预置属性说明

[[raw/接入前准备工作/预置属性与系统字段.md]] 中，系统自动填充以 `#` 开头的字段（`#ip`、`#country`、`#os` 等），**不建议手动覆盖**，除 `#ip` 外其他预置属性需在 AE 工作人员指导下设置。

## 多实例

```js
ta.initInstance("sub");         // 创建子实例
ta.sub.init({ appId: "SUB_APP_ID", serverUrl: "..." });
ta.sub.track("event_name", {});
```

[[raw/接入指南/客户端-sdk/javascript/进阶指南.md]]
