# @active-reach/web-sdk 中文文档

规范地址：https://npmcn.com/package/%40active-reach/web-sdk/

版本：1\.48\.0
npm 元数据更新时间：2026-10-27T14:06:45.022Z
中文译文更新时间：2026-11-06T17:08:38.511Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40active-reach/web-sdk
原文对照：https://npmcn.com/package/%40active-reach/web-sdk/?lang=original

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

- 包体积（解压后）：5.7 MB，214 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react \>=18\.0\.0
- 首次发布：2026-04-15T14:16:44.013Z
- 最新版本发布：2026-10-27T14:06:44.638Z
- 近 30 天下载量：2635（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：84（近 12 个月 84 个）

## 中文简介

积极接触情报的Web SDK——事件跟踪、身份分辨率、应用信息、网络推取和投放

## 安装

```sh
npm install @active-reach/web-sdk
```

也可以使用：`pnpm add @active-reach/web-sdk`、`yarn add @active-reach/web-sdk`、`bun add @active-reach/web-sdk`

## README

# @ action-reach/web-sdk (英语)

网络 SDK 用于 **积极接触情报** ——轻量级事件跟踪,身份解析,应用中消息(覆盖,嵌入式卡片,交互式部件),并进行网络推.

**12KB弹出** | **< 1KB 自动加载器** | **对页面负荷的零影响**

* * *

## 先决条件

在整合之前,您需要:

1.  **写入密钥** - 从你的主动接触情报仪表板上取回 **设置 > 开发者 > API 密钥**。 。 。 .
2.  **API 主机** — 您的单元格端点 URL( 在登入时提供) .

> **说明:** 写入密钥为 a **可公布的标识符** (如花纹可发布密钥). 在客户端代码中包含是安全的。 它只能发送事件——它不能读取数据,修改配置,或访问其他租户. 永远不要用你的 **密钥** 在客户端代码.

* * *

## 安装

### 国家预防机制(建议)

```bash
npm install @active-reach/web-sdk
```

### CDN (同步装入器)

将此片段添加到您的 `<head>` 标签。 ASync加载器队列所有调用,直到SDK满载——零屏蔽.

```html
<script>
  !function(){var e=window.aegis=window.aegis||[];if(!e.invoked){e.invoked=!0,e.methods=["init","track","identify","page","group","alias","reset","flush","use","debug","setCell","getCellInfo","getAnonymousId","getUserId","getSessionId","setConsent","grantConsent","denyConsent","hasConsent","getConsentPreferences","onConsentChange"],e.factory=function(t){return function(){var n=Array.prototype.slice.call(arguments);return n.unshift(t),e.push(n),e}};for(var t=0;t<e.methods.length;t++){var n=e.methods[t];e[n]=e.factory(n)}e.load=function(t,n){var o=document.createElement("script");o.type="text/javascript",o.async=!0,o.src=n&&n.cdnUrl?n.cdnUrl:"https://platform.active-reach.ai/sdk/aegis.min.js",o.onerror=function(){window.console&&console.error("Aegis SDK failed to load")};var r=document.getElementsByTagName("script")[0];r.parentNode.insertBefore(o,r),e._loadOptions={key:t,options:n}},e.SNIPPET_VERSION="1.0.0"}}();

  aegis.load('YOUR_WRITE_KEY');
  aegis.init('YOUR_WRITE_KEY', {
    api_host: 'https://YOUR_CELL.activereach.ai'
  });
</script>
```

* * *

## 快速启动

### 国家预防机制/环境单元

```typescript
import aegis from '@active-reach/web-sdk';

await aegis.init('YOUR_WRITE_KEY', {
  api_host: 'https://YOUR_CELL.activereach.ai',
  auto_page_view: true,
});

// Track an event
aegis.track('Purchase Completed', {
  order_id: 'ORD-123',
  revenue: 99.99,
  currency: 'INR',
});

// Identify a user
aegis.identify('user_123', {
  email: 'user@example.com',
  name: 'Priya Sharma',
  plan: 'premium',
});
```

### 反应

```tsx
import { AegisProvider, useAegis, useTrackEvent } from '@active-reach/web-sdk/react';

function App() {
  return (
    <AegisProvider
      writeKey="YOUR_WRITE_KEY"
      config={{ api_host: 'https://YOUR_CELL.activereach.ai', auto_page_view: true }}
    >
      <Dashboard />
    </AegisProvider>
  );
}

function Dashboard() {
  const { isReady } = useAegis();
  const trackEvent = useTrackEvent();

  return (
    <button onClick={() => trackEvent('Button Clicked', { button: 'CTA' })}>
      Track Event
    </button>
  );
}
```

### 下一个.js

```tsx
// app/providers.tsx
'use client';

import { AegisProvider } from '@active-reach/web-sdk/react';

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <AegisProvider
      writeKey={process.env.NEXT_PUBLIC_AEGIS_WRITE_KEY!}
      config={{ api_host: process.env.NEXT_PUBLIC_AEGIS_API_HOST! }}
    >
      {children}
    </AegisProvider>
  );
}
```

* * *

## 配置

```typescript
await aegis.init('YOUR_WRITE_KEY', {
  // Required
  api_host: string;

  // Batching & Performance
  batch_size?: number;           // default: 10
  batch_interval?: number;       // default: 1000ms

  // Data Capture
  capture_utm?: boolean;         // default: true
  capture_referrer?: boolean;    // default: true
  auto_page_view?: boolean;      // default: false

  // Session
  session_timeout?: number;      // default: 1800000 (30 min)

  // Privacy & Consent
  respect_dnt?: boolean;         // default: true
  enable_consent_mode?: boolean; // default: false
  wait_for_consent?: boolean;    // default: false
  default_consent?: {
    analytics?: boolean;         // default: false
    marketing?: boolean;         // default: false
    functional?: boolean;        // default: true
  };
  integrate_onetrust?: boolean;
  integrate_cookiebot?: boolean;
  integrate_google_consent_mode?: boolean;

  // Cookie
  cross_domain_tracking?: boolean; // default: false
  cookie_domain?: string;
  secure_cookie?: boolean;         // default: true

  // Offline & Retry
  enable_offline_mode?: boolean;   // default: true
  max_offline_events?: number;     // default: 100
  retry_failed_requests?: boolean; // default: true
  max_retries?: number;            // default: 3

  // Regional Cell Selection
  cell_endpoints?: CellEndpoint[];
  preferred_region?: string;
  auto_region_detection?: boolean; // default: true

  // Debug
  debug?: boolean;                 // default: false
});
```

* * *

## 核心 API

### `aegis.track(eventName, properties?)`

跟踪自定义事件 .

```typescript
aegis.track('Product Viewed', {
  product_id: 'SKU-12345',
  product_name: 'Leather Jacket',
  price: 199.99,
  category: 'Outerwear',
});
```

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

识别用户和关联特征.

```typescript
aegis.identify('user_123', {
  email: 'user@example.com',
  name: 'John Doe',
  plan: 'premium',
});
```

### `aegis.page(name?, properties?)`

跟踪页面视图 .

```typescript
aegis.page('Product Page', { product_id: 'SKU-12345' });
```

### `aegis.group(groupId, traits?)`

与一个团体(公司、组织)联系用户.

```typescript
aegis.group('company_789', {
  name: 'Acme Corp',
  industry: 'Technology',
  employees: 500,
});
```

### `aegis.alias(newUserId)`

合并两个用户身份.

```typescript
aegis.alias('permanent_user_id');
```

### `aegis.reset()`

登录时清除用户身份 。 生成新的匿名身份 .

```typescript
aegis.reset();
```

### `aegis.flush()`

强制发送所有已排队的事件 .

```typescript
await aegis.flush();
```

* * *

## 电子商务追踪

为标准化电子商务活动搭建的助手 `aegis.ecommerce`数字 :

```typescript
import aegis from '@active-reach/web-sdk';

// Product discovery
aegis.ecommerce.productViewed({
  product_id: 'SKU-123',
  name: 'Leather Jacket',
  price: 4999,
  currency: 'INR',
  category: 'Outerwear',
  brand: 'Acme',
  variant_id: 'black_xl',
  variant_label: 'Black XL',
});

aegis.ecommerce.productListViewed({
  list_name: 'New Arrivals',
  category: 'Outerwear',
  products: [{ product_id: 'SKU-123', name: 'Leather Jacket', price: 4999 }],
});

aegis.ecommerce.searchPerformed({ query: 'leather jacket', results_count: 12 });

// Cart
aegis.ecommerce.addToCart({
  product_id: 'SKU-123',
  name: 'Leather Jacket',
  price: 4999,
  quantity: 1,
});

aegis.ecommerce.removeFromCart({ product_id: 'SKU-123', name: 'Leather Jacket', price: 4999 });

aegis.ecommerce.cartViewed({
  cart_id: 'cart_456',
  value: 4999,
  products: [{ product_id: 'SKU-123', name: 'Leather Jacket', price: 4999, quantity: 1 }],
});

// Checkout
aegis.ecommerce.checkoutStarted({
  value: 4999,
  products: [{ product_id: 'SKU-123', name: 'Leather Jacket', price: 4999, quantity: 1 }],
  coupon: 'WELCOME10',
  shipping: 99,
  tax: 450,
});

aegis.ecommerce.checkoutStep(2, { payment_method: 'UPI' });

// Order
aegis.ecommerce.orderCompleted({
  order_id: 'ORD-789',
  value: 5548,
  revenue: 4999,
  shipping: 99,
  tax: 450,
  payment_method: 'UPI',
  products: [{ product_id: 'SKU-123', name: 'Leather Jacket', price: 4999, quantity: 1 }],
});

aegis.ecommerce.orderRefunded('ORD-789', 4999);

// Coupons
aegis.ecommerce.couponApplied({ coupon_code: 'WELCOME10', discount_value: 500, discount_type: 'fixed' });
aegis.ecommerce.couponRemoved({ coupon_code: 'WELCOME10' });

// Wishlist
aegis.ecommerce.wishlistItemAdded({
  product: { product_id: 'SKU-123', name: 'Leather Jacket', price: 4999 },
});

// Promotions
aegis.ecommerce.promotionViewed({ name: 'Summer Sale', promotion_id: 'promo_1', creative: 'banner_hero' });
aegis.ecommerce.promotionClicked({ name: 'Summer Sale', promotion_id: 'promo_1' });
```

### 所有电子商务方法

| 方法 | 事件名称 | 说明 |
| --- | --- | --- |
| `productViewed(product)` | `product_viewed` | 用户查看一个产品页面 |
| `productListViewed(list)` | `product_list_viewed` | 用户查看一个类别/收藏 |
| `searchPerformed(search)` | `search_performed` | 用户搜索目录 |
| `addToCart(product)` | `cart_item_added` | 添加到推车中的项目 |
| `removeFromCart(product)` | `cart_item_removed` | 从推车取出的项目 |
| `cartViewed(cart)` | `cart_viewed` | 用户查看他们的推车 |
| `checkoutStarted(checkout)` | `checkout_started` | 检查流程开始 |
| `checkoutStep(step, options?)` | `checkout_step` | 退出步骤已完成 |
| `orderCompleted(order)` | `order_completed` | 完成采购 |
| `orderRefunded(orderId, value?, products?)` | `order_refunded` | 已退订 |
| `couponApplied(coupon)` | `coupon_applied` | 折合金/贴现 |
| `couponRemoved(coupon)` | `coupon_removed` | 已删除 |
| `wishlistItemAdded(wishlist)` | `wishlist_item_added` | 添加到希望列表的项目 |
| `promotionViewed(promo)` | `promotion_viewed` | 晋升印象 |
| `promotionClicked(promo)` | `promotion_clicked` | 点击了推广 |

* * *

## 反应钩

从 `@active-reach/web-sdk/react`数字 :

| 钩子 | 回返 | 说明 |
| --- | --- | --- |
| `useAegis()` | `{ aegis, isReady }` | 访问 SDK 实例和准备状态 |
| `useTrackEvent()` | `(name, props?) => void` | 提醒事件追踪回调 |
| `usePageView(name?, props?, deps?)` | —— 说 | 关于挂载/依赖性变化的音轨页面视图 |
| `useIdentifyUser()` | `(userId, traits?) => void` | 提醒身份调用 |

* * *

## 同意管理

建设支持GDPR/CCPA合规.

```typescript
// Set preferences
aegis.setConsent({ analytics: true, marketing: false, functional: true });

// Grant / deny
aegis.grantConsent();           // all categories
aegis.grantConsent('analytics'); // specific category

aegis.denyConsent();
aegis.denyConsent('marketing');

// Query
aegis.hasConsent('analytics');   // boolean
aegis.getConsentPreferences();   // full object

// Listen for changes
const unsubscribe = aegis.onConsentChange((prefs) => {
  console.log('Consent updated:', prefs);
});
```

### 第三方一体化

```typescript
// OneTrust
aegis.init('KEY', { enable_consent_mode: true, integrate_onetrust: true });

// Cookiebot
aegis.init('KEY', { enable_consent_mode: true, integrate_cookiebot: true });

// Google Consent Mode v2
aegis.init('KEY', { enable_consent_mode: true, integrate_google_consent_mode: true });
```

* * *

## 网络推取通知

从 `@active-reach/web-sdk/push`数字 :

```typescript
import { AegisWebPush } from '@active-reach/web-sdk/push';

const push = new AegisWebPush({
  writeKey: 'YOUR_WRITE_KEY',
  apiHost: 'https://YOUR_CELL.activereach.ai',
  vapidPublicKey: 'YOUR_VAPID_PUBLIC_KEY',
  contactId: 'user_123',
  organizationId: 'org_456',
  serviceWorkerPath: '/aegis-sw.js',
});

await push.initialize();
```

复制 `dist/aegis-sw.js` 给您的 `public/` 因此,服务员被服务在根部.

* * *

## 内接通讯和部件

每个应用格式——模式、旗帜、工具提示、全屏接管、底页和交互式部件(平轮、刮卡、核动力源/卫星调查、测验、倒计时、明星评分、民意测验、多步骤表格)——都通过一个系统提供 **单一入口**数字 : `AegisMessageRuntime`。 。 。 .

```typescript
import { AegisMessageRuntime } from '@active-reach/web-sdk';

const runtime = new AegisMessageRuntime({
  writeKey: 'YOUR_WRITE_KEY',
  apiHost: 'https://YOUR_CELL.activereach.ai',
  contactId: 'user_123',     // optional — set once the visitor is known
  organizationId: 'org_456',
  propertyId: 'prop_789',    // the SDK install (website/app) this page is
});

await runtime.initialize();
```

> **从旧版本搬走?** `AegisInAppManager`, (中文(简体) ), `AegisWidgetManager`,以及 `AegisPlacementManager` 不再成为公共API的一部分—— `AegisMessageRuntime` 是一个支持的切入点并制作所有格式。 独立的"放置"系统被移除;内置内容现在作为 **嵌入式卡片** (见下文).

宣传内容、受众、时间表和频率上限在仪表板上配置了服务器侧(**App 个人化**) (中文(简体) ). SDK评价客户端触发器(滚动深度,页面上的时间,退出意向,不活动,自定义事件),并自动使匹配运动.

### 从应用程序驱动触发身份( I)

```typescript
runtime.track('added_to_cart');         // fire event-based display triggers
runtime.notifyConversion('purchase');   // suppress a campaign after it converts
await runtime.updateContactId('contact_42'); // re-evaluate once the visitor signs in
```

### 安置——运动如何惠及客户

每次选一次或多次 **发送模式** 在仪表板上 **安置情况** 选项卡。 它们并非相互排斥:

| 发送模式 | 这是什么 | 在你的网站上做什么 |
| --- | --- | --- |
| **弹出( 覆盖)** | SDK 运行时在页面上制作的模式 / 横幅 /等 | 没什么.. `runtime.initialize()` 当触发匹配时显示 |
| **嵌入式卡片** | 该运动使 _内入_在页面上的插槽内 | 添加为空 `<div data-aegis-slot="…">` 随便你 |
| **独立页面** | 运动获得自己的标志性 URL( 对短消息 / 电子邮件 / QR 来说很大) | 链接到仪表板上显示的 URL |

#### 嵌入式卡片(内置入式)

将空元素丢入要显示的牌中 。 内容 `data-aegis-slot` 价值必须等于运动价值 **类别** (单位:千美元)`widget_category` 在仪表板上。 在加载时, SDK 将填充该类的首个符合条件的运动:

```html
<!-- Renders the active "promo" campaign here, inline in your page -->
<div data-aegis-slot="promo"></div>
```

没有每个片段的脚本和手动注册—— `runtime.initialize()` 每张扫描 `[data-aegis-slot]` 元素并填充。 它在每次SSE/poll刷新上重新扫描,并跳过它已经填充的槽.

#### 槽壳-在运动到来前保留盒子

当它的竞选登陆时,一个空位会增长,这个空位将页面推倒(layout shift),而英雄形象要求等待竞选取来. SDK用一个 **外壳**: 适当大小的占位符, 绘制到每个空位 _在此之前_ 它收集,然后运动完成。 一个没有东西填补的插槽,一旦得到答案,就会崩溃,所以一个框从不显示,而后消失.

SDK从第一个有1个槽的槽取出每个槽的壳:

1.  **内嵌到页面打印形状** (服务器提交的网页): `shapes` 从 `GET /v1/in-app/slot-shapes` (下),以脚本标记. 当这个标记出现时,它所缺失的插槽被视作"不会填满".
    
    ```html
    <script type="application/json" data-aegis-slot-shapes>{"shapes":[ … ]}</script>
    ```
    
2.  **槽本身的属性** (任何地点,用手):
    
    ```html
    <div data-aegis-slot="hero" data-aegis-slot-aspect="8/3"></div>
    <div data-aegis-slot="commerce" data-aegis-slot-min-height="272"></div>
    ```
    
    `data-aegis-slot-aspect` 带 `w/h` (或 `w:h`) (中文(简体) ). `data-aegis-slot-min-height` 使用像素或 CSS 长度(`300`, (中文(简体) ), `20rem`, (中文(简体) ), `45vh`) (中文(简体) ).
3.  **上次拜访的形状**:每次获取后,SDK会将获胜的竞选形状保存在 `localStorage`键是属性加所申报的表面、屏幕和出入口(`locationId`),保存的形状在6小时后失效. 如果存储被屏蔽, 此步骤会被跳过 .

你让自己变成一个人 如果空档已经有子女(a) `data-aegis-slot-default` 倒计时,或者你自己 `<div data-aegis-slot-shell>` 孩子,SDK画什么也没有。 它用竞选来取代你的外壳,或者在槽不能填满时去掉外壳,恰好是它自己做的. SDK从不画出标记的形状 `may_be_empty` (例如,首次访问者可乘回购铁路)。 只有槽的自有属性才能为一个框保留一个框.

**`GET /v1/in-app/slot-shapes`**: 用于服务器渲染器. 它使用相同的 写键头与 `/v1/in-app/active` (单位:千美元)`X-Aegis-Write-Key`选项 `X-User-ID` 编号 : `X-Contact-ID` 编号 : `X-Property-Id`) (中文(简体) ). 查询参数为: `property_id` (当信头缺席时使用), `surface`, (中文(简体) ), `screen`, (中文(简体) ), `page_url` (路径+搜索), `location_id`, (中文(简体) ), `device_type`, (中文(简体) ), `geo` 财务报告和审定财务报表 `is_new_user`反应包括: `Cache-Control: private, max-age=60` 而身体则 `{"shapes": [SlotShape, …]}`,每个插槽一个形状 **将** 填满 空出的时间段将无法填补 。 每个运动在 `/v1/in-app/active` 也带着自己的 `slot_shape`。 。 。 .

**自己打印贝壳的主机.** ACS的店面 让他们从 `display.inapp_slot_shapes`。“ Shopify”主题应用程序扩展名使其来自商店元场 `aegis.slot_shapes`,单元格保持同步(`shopify-plugin/theme-app-extension/snippets/aegis-slot-shell.liquid`) (中文(简体) ). 都标出他们的炮弹 `data-aegis-slot-shell` + 键 `data-aegis-shell-owner="host"` 并打印出内线形状,所以SDK采用上述形状.

`SlotShape`数字 :

| 外地 | 含义 |
| --- | --- |
| `slot` | 插槽键( E)`data-aegis-slot` 值=运动 `widget_category`(中文(简体) ) |
| `campaign_id` | 胜利的竞选 |
| `layout` | `hero`, (中文(简体) ), `rail`, (中文(简体) ), `grid` (单位:千美元)`columns` 清单2或1, `bar` (通知栏/值栏)或 `card` |
| `aspect` | 方框方面 `w/h`。对于英雄来说,这是桌面方面(`8/3`, 768px) (中文(简体) ) |
| `aspect_phone` | 只有英雄:电话(<768px)方面(`chrome.aspect_ratio`,或 `1/1` 当幻灯片有电话图像时)。 无效使用 `min_height` |
| `min_height` 编号 : `max_height` | 像素 / CSS 长度( 英雄被盖上 ) `70vh`(中文(简体) ) |
| `card_aspect`, (中文(简体) ), `card_count`, (中文(简体) ), `title` | 铁路和网格:每张卡片的图像方面,卡片数量,以及标题(缺席时为零) |
| `may_be_empty` | 这个收视器的收视槽可能保持空位(一个没有显示的栏杆,或者一个取决于谁在看的赢家:一个A/B测试或为所有匿名访客计算出形状的坚挺). 仅从数据中绘制无框 。 这种形状没有 `image` 大小 |
| `rotate_count` | 插槽通过这么多的竞选来旋转. 形状是第一个 |
| `image` | 仅英雄: 第一张幻灯片的图像 `{src, src_phone, alt, aspect, aspect_phone, width, height}`把它变成 `<img fetchpriority="high">` 所以这是页面的LCP请求 |

英雄画出幻灯片 0 为 `<img fetchpriority="high" decoding="async" width height>` 懒惰地载着其他的滑行。 铁路卡图像携带 `decoding="async"` 加上明确的 `width`编号 :`height`,然后在一次解码后消失.

### Cart State——一家商店,以CEP标准方式提供

每个电车反应表面—— **免费交货进度卡**,独立 **进度栏**,车价值 **目标设定规则**,以及 **推车回收** 部件 - 读取一车店。 你以同样的方式喂养它 发射 **电子商务活动** 你已经开火了 SDK是活车 禁止召人作客.

```typescript
// 1) Wire the ecommerce tracker into the cart store, once at boot:
runtime.bindEcommerce(aegis.ecommerce);

// 2) Fire ecommerce events as the shopper shops — the cart is derived from these:
aegis.ecommerce.addToCart({ product_id: 'p1', name: 'Cap', price: 499, quantity: 1 });
aegis.ecommerce.cartViewed({ value: 998, currency: 'INR', products: [/* … */] }); // authoritative snapshot
```

**平台安装不需要事件线条** - 插件为你做。 钱是 自动检测并输入同一商店:

| 平台 | 检测方法 | 设置 |
| --- | --- | --- |
| **购买** | `/cart.js` 民意调查+ `cart:updated` (插图) | 安装商店应用程序 |
| **伍商** | `aegis_cart` + WC 存储 API( 插件) | 安装WP 插件 |
| **马根托 2** | `localStorage['mage-cache-storage']` | 安装扩展名 |
| **自定义/ 无头/ 移动** | 开火 `aegis.ecommerce.*` (上文) (中文(简体) ) | `runtime.bindEcommerce(...)` |

**逃逸舱门** ——无头主机不放出电子商务事件可以推动 直接推车; 这写同一个商店:

```typescript
runtime.setCartState({ total: 149.99, itemCount: 2, currency: 'INR' });
```

* * *

## 插件系统

以自定义插件扩展 SDK :

```typescript
import type { Plugin } from '@active-reach/web-sdk';

const myPlugin: Plugin = {
  name: 'my-plugin',
  version: '1.0.0',

  async init(config) { /* called on SDK init */ },

  async beforeEventCapture(event) {
    // Modify or enrich events before capture
    event.properties = { ...event.properties, enriched: true };
    return event;
  },

  async afterEventCapture(event) {
    // Post-capture logic (external forwarding, logging, etc.)
  },
};

aegis.use(myPlugin);
```

* * *

## 类型脚本支持

包括完整类型的定义。 扩展类型安全事件跟踪 :

```typescript
// types/aegis.d.ts
import '@active-reach/web-sdk';

declare module '@active-reach/web-sdk' {
  interface TrackEventProperties {
    'Purchase Completed': {
      order_id: string;
      revenue: number;
      currency: string;
    };
    'Product Viewed': {
      product_id: string;
      product_name: string;
      price: number;
    };
  }
}
```

* * *

## 饼干和存储

| 名称 | 类型 | 目的 | 会期 |
| --- | --- | --- | --- |
| `aegis_anon_id` | 饼干 | 匿名用户标识符 | 365天(1天) |
| `aegis_user_id` | 饼干 | 识别的用户 ID | 365天(1天) |
| `aegis_session_id` | 饼干 | 当前会话编号 | 会议 |
| `aegis_session_time` | 饼干 | 最后活动时间戳 | 会议 |
| `aegis_consent` | 饼干 | 同意优惠 | 365天(1天) |
| `aegis_offline_queue` | 本地图集 | 离线事件队列 | 持久性 |
| `aegis_active_cell` | 本地图集 | 活跃的区域小组 | 7天时间 |

所有饼干 : `SameSite=Lax`, (中文(简体) ), `Secure` (只有HTTPS),域范围(可选).

* * *

## 内容安全政策

如果您的网站使用内容安全政策,请添加这些指令:

```
script-src: 'self' https://platform.active-reach.ai;
connect-src: 'self' https://*.activereach.ai;
style-src: 'self' 'unsafe-inline';
img-src: 'self' https://*.activereach.ai data:;
```

如果通过CDN使用DOMPurify,也添加:

```
script-src: https://cdnjs.cloudflare.com;
```

**CSP 缺失时常见错误 :** `Refused to connect to 'https://...activereach.ai'` ——将域添加到 `connect-src`。 。 。 .

* * *

## 警卫

-   **写入密钥**: 发布客户端标识符. 无法读取数据或修改服务器状态 。 安全嵌入源代码.
-   **HTML 卫生**: 用途 [多维化](https://github.com/cure53/DOMPurify) 当有严格的允许列表时。 返回到仅文本渲染 .
-   **URL 验证**: 所有验证的 URL ─ `javascript:` 财务报告和审定财务报表 `data:` 协议被封锁 .
-   **同意**: 拒绝同意时, 事件被放弃( 不排队) `wait_for_consent` 已启用.
-   **运输**:所有API的呼叫都使用HTTPS并带有无记名符号认证.

### 什么不跟踪

永远不要通过敏感数据作为事件属性 :

```typescript
// Never do this
aegis.track('Login', { password: '...' });
aegis.identify('user_123', { ssn: '...', credit_card: '...' });
```

SDK不过滤或编辑属性. 您负责确保所要收集的物品不包括在有效载荷中.

* * *

## 调试

```typescript
aegis.debug(true);

// Or via init
aegis.init('KEY', { debug: true });
```

控制台输出 :

```
[Aegis] Initializing SDK...
[Aegis] Event queued: track { button_name: 'Sign Up' }
[Aegis] Flushing 5 events
[Aegis] Batch sent successfully
```

* * *

## 子路径导出

| 导入路径 | 说明 |
| --- | --- |
| `@active-reach/web-sdk` | 核心 SDK( 跟踪、 识别、 页面、 组、 化名) |
| `@active-reach/web-sdk/react` | 反应提供者+钩 |
| `@active-reach/web-sdk/push` | Web Push 通知管理器 |
| `@active-reach/web-sdk/cdn` | IIFE 组合 `<script>` 标签 (window.aegis) |
| `@active-reach/web-sdk/snippet` | 已消化的 Aync 加载器片断 |
| `@active-reach/web-sdk/service-worker` | 推动通知服务工作者 |

* * *

## 浏览器支持

Chrome 80+, Firefox 78+, Safari 14+, Edge 80+.

* * *

## 许可证

麻省理工学院

## 常见问题

### @active-reach/web-sdk 是什么？

积极接触情报的Web SDK——事件跟踪、身份分辨率、应用信息、网络推取和投放

### 如何安装 @active-reach/web-sdk？

在项目目录运行 npm install @active-reach/web-sdk，或使用 pnpm add / yarn add / bun add。

### @active-reach/web-sdk 支持 TypeScript 吗？

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

### @active-reach/web-sdk 支持 ESM 还是 CommonJS？

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

### @active-reach/web-sdk 可以商用吗？

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

### @active-reach/web-sdk 的下载量有多少？

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

### @active-reach/web-sdk 还在维护吗？

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