# @athoscommerce/beacon 中文文档

规范地址：https://npmcn.com/package/%40athoscommerce/beacon/

版本：1\.4\.0
npm 元数据更新时间：2026-10-28T20:35:01.921Z
中文译文更新时间：2026-11-07T02:05:22.946Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：2.2 MB，776 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-02-05T16:37:47.329Z
- 最新版本发布：2026-10-28T20:35:01.473Z
- 近 30 天下载量：2307（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：13（近 12 个月 13 个）

## 中文简介

使用 Athos 商业信标跟踪的 Javascript 库.

## 安装

```sh
npm install @athoscommerce/beacon
```

也可以使用：`pnpm add @athoscommerce/beacon`、`yarn add @athoscommerce/beacon`、`bun add @athoscommerce/beacon`

## README

# 信标.js

[![npm version](https://badge.fury.io/js/@athoscommerce%2Fbeacon.svg?icon=si%3Anpm&icon_color=%2300aeef)](https://badge.fury.io/js/@athoscommerce%2Fbeacon)

一个用于跟踪用户互动和分析事件的TypeScript库到Athos Commerce's Beacon API. 这个库能够实时跟踪用户行为,包括搜索、建议、自动完成和电子商务互动.

这个软件包可以被Athos Commerce和SearchSpring两个账户使用.

## 特征

-   🎯 **多频道跟踪**: 跟踪搜索、自动完成、建议、捆绑、聊天、分类页面和产品页面中的事件
-   📦 **智能击打**: 自动批出最佳性能请求
-   💾 **当地储存管理**: 管理用户ID,会话ID,卡通状态,并查看产品
-   🔍 **追踪**: 支持追踪归属和运动来源
-   🎨 **弹性配置**: 支持自定义信头、自定义获取执行和多种环境
-   🌍 **多频**: 支持以不同货币跟踪交易
-   ⚡ **生产准备**: 优化性能,具有持续请求和高效分批处理等特征

## 用法路径

Beacon.js有两条具有相同跟踪能力的集成道:

-   CDN 路径: 在自动创建的全局上包含 CDN 脚本和调用方法 `window.athos.tracker`。 。 。 .
-   国家预防机制路径:即时 `Beacon` 在您自己的应用程序/运行时间中,并按您的情况调用方法.

### 快速启动: CDN

```html
<script siteId="[REPLACE WITH ACCOUNT SITEID]" src="https://cdn.athoscommerce.net/analytics/beacon.js"></script>
<script>
  window.athos.tracker.setCurrency({ code: 'USD' });
  window.athos.tracker.events.autocomplete.render({
    data: {
      responseId: '35e5ea31-a537-471b-ba2b-6eea9caebe62'
    }
  });
</script>
```

替换 `siteId` 在部署前使用您的 Athos 或搜索泉站点ID .

### 快速启动:国家预防机制

```typescript
import { Beacon } from '@athoscommerce/beacon';

// Initialize Beacon with required siteId
const beacon = new Beacon({ siteId: '[REPLACE WITH ACCOUNT SITEID]' });

// Optionally set currency for transaction tracking
beacon.setCurrency({ code: 'USD' });

// Track an autocomplete render event
beacon.events.autocomplete.render({
  data: {
    // ... render data
  }
});

// Track a product page view
beacon.events.product.pageView({
  data: {
    result: {
      uid: 'variant-123',
      sku: 'SKU-123',
      parentId: 'product-123'
    }
  }
});
```

替换 `siteId` 在部署前使用您的 Athos 或搜索泉站点ID .

产品活动需要 `uid` 财务报告和审定财务报表 `parentId`; 包含 `sku` 当您从 API 回复中获取时。 用于父目录/变量目录 `parentId` 作为母产品ID和 `uid` 作为变体ID. 对于没有变种的简单产品,设置 `uid` 财务报告和审定财务报表 `parentId` 以同样价值计算.

## 安装

### 光盘N

通过我们的CDN架构使用信标,在页面关闭前放出以下脚本 `</head>` 标签 :

```html
<script siteId="[REPLACE WITH ATHOS OR SEARCHSPRING SITEID]" src="https://cdn.athoscommerce.net/analytics/beacon.js"></script>
```

在此脚本成功执行后, `window.athos.tracker` 用于事件和方法调用.

```html
<script>
  window.athos.tracker.events.search.render({ data: { responseId: '35e5ea31-a537-471b-ba2b-6eea9caebe62' } });
</script>
```

CDN安装路径是为平台模板集成(例如: BigCommerce, Magento, 或 Shopify)而设计的,您会在存储前端模板/主题文件中添加脚本.

### 国家预防机制

当您的整合运行在 JavaScript/ TypeScript 应用程序中时, 请使用国家防范机制软件包, 您希望将Beacon 直接导入到您的代码库中 。 此路径会给您输入的输入, 版本的依赖性管理, 以及构建时间与您现有的工具集成 .

```bash
npm install --save @athoscommerce/beacon
```

## 初始化

### CDN 初始化

当使用 CDN 脚本时(`https://cdn.athoscommerce.net/analytics/beacon.js`),灯塔自动初始化并指定 `window.athos.tracker`。 。 。 .

预期行为 :

-   缺少或无法读取 `siteId` 防止初始化并记录出错.
-   如果Snap跟踪已经在页面上,则脚本会记录一个警告并跳过初始化.
-   如果将Beacon包含多次,则会以警告而忽略第二次初始化.

初始化后,使用 `window.athos.tracker` 所有活动和公共方法.

### 国家防范机制启动

使用 `Beacon` 通过国家防范机制一揽子计划整合时的构建器.

#### 灯塔全球

第一个参数 `Beacon` 构造器包含适用于所有跟踪事件所需的全局配置.

```typescript
import { Beacon } from '@athoscommerce/beacon';

const beacon = new Beacon({ siteId: 'abc123' });
```

| 选项 | 类型 | 说明 | 需求 |
| --- | --- | --- | --- |
| `siteId` | `string` | 您的 Athos 站点 ID | ✔️ |

#### 灯塔配置

第二个参数 `Beacon` 构造器提供 _选项_ aPI行为和请求处理的配置.

```typescript
const beacon = new Beacon(
  { siteId: 'abc123' },
  {
    mode: 'development',
    initiator: 'my-app/1.0.0',
    requesters: {
      beacon: {
        origin: 'https://custom-beacon.example.com/beacon/v2',
        headers: { 'Authorization': 'Bearer token' }
      },
      personalization: {
        origin: 'https://custom-personalization.example.com',
        headers: { 'X-Custom-Header': 'value' }
      }
    },
    apis: {
      fetch: customFetchImplementation
    },
    href: 'https://example.com/page',
    userAgent: 'Custom User Agent'
  }
);
```

| 选项 | 类型 | 说明 | 默认 |
| --- | --- | --- | --- |
| `mode` | `'production' | 'development'` | 应用模式. 在开发模式中,错误会被登录到控制台 | `'production'` |
| `initiator` | `string` | 信标实例标识符 | `{athos|searchspring}/beaconjs/{version}` |
| `apis.fetch` | `FetchAPI` | 自定义获取执行 | 全球 `fetch` (如有) |
| `requesters.beacon.origin` | `string` | 自定义信标 API 端点 | 亚多斯: `https://analytics.athoscommerce.net/beacon/v2`,搜索弹簧 : `https://analytics.searchspring.net/beacon/v2` |
| `requesters.beacon.headers` | `HTTPHeaders` | 信标 API 请求的自定义信头 | `{ 'Content-Type': 'text/plain' }` |
| `requesters.personalization.origin` | `string` | 自定义个人化飞行前来源( SDK 附加件) `/v1/preflight`(中文(简体) ) | `https://{siteId}.a.{athoscommerce.net|searchspring.io}` |
| `requesters.personalization.headers` | `HTTPHeaders` | 个人化请求自定义标题 |  |
| `href` | `string` | 覆盖跟踪的页面 URL | `window.location.href` |
| `userAgent` | `string` | 覆盖用户代理字符串 | `navigator.userAgent` |

## 共同属性

### 响应Id

Athos 搜索、自动完成和建议 API 将返回 a `responseId` 大多数信标事件的有效载荷需要的属性。 只有在 `beacon=true` 向每个API提供参数.

```typescript
// Search API Example Response
const response = {
  "breadcrumbs": [...],
  "merchandising": {...},
  "pagination": {...},
  "query": {...},
  "responseId": "f70594d2-c360-4292-8711-b256567099d3",
  "results": [...],
  "sorting": {...},
}

beacon.events.search.render({ 
  data: {
    responseId: response.responseId,
  }
});
```

### 商品行(Banner ID)

在建立数据有效载荷时 `banners`,则 `uid` 属性是交易内容的横幅标识符(不是产品) `uid`) (中文(简体) ). 以下是你如何选择提取的例子.

```typescript
// Search API Example Response
const response = {
  "merchandising": {
    "content": {
      "header": [
            "<script data-banner-id=\"440998\" data-banner-type=\"html\" data-banner-html=\"<div style=&quot;width: 100%; background: #ADD8E6; text-align: center; padding: 20px;&quot;>On Sale</div>\" type=\"text/widget\"></script><div style=\"width: 100%; background: #ADD8E6; text-align: center; padding: 20px;\">On Sale</div>"
      ],
      "banner": [],
      "footer": [],
      "left": [],
      "inline": []
    }
  }
}
function getMerchandisingBannerUid(response, type) {
  // Extract data-banner-id from the HTML string
  const htmlString = response.merchandising?.content?.[type]?.[0] || '';
  const match = typeof htmlString === 'string' && htmlString.match(/data-banner-id="(\d+)"/);
  const uid = match ? match[1] : '';
  return uid;
}
beacon.events.search.impression({ 
  data: {
    responseId: response.responseId,
    results: [],
    banners: [
      { uid: getMerchandisingBannerUid(response, 'header') } // { uid: '440998' }
    ]
  }
});
```

### 快速查看

快速取景(英語:快取景)是一款弹出或模式,可以预览一出产品而无需浏览到其完整的产品页面. 设置可选 `quickView` 旗为 `true` 在活动上 `data` 当在快速视图中发生相互作用时,有效载荷会弹出,因此报告可以将其与正常的页面相互作用区分开来.

旗子上是支持的 `impression`, (中文(简体) ), `addToCart`,以及 `clickThrough` 联 合 国 `autocomplete`, (中文(简体) ), `search`, (中文(简体) ), `category`, (中文(简体) ), `recommendations`,以及 `bundles` 频道。 它是可选的——省略(或设定为 `false`用于常规页面上的互动.

```typescript
// Example: a click on a product surfaced inside a search quick view popup
beacon.events.search.clickThrough({ 
  data: {
    responseId: response.responseId,
    quickView: true,
    results: [
      {
        type: 'product',
        uid: 'variant-1',
        parentId: 'product-1',
        sku: 'SKU-1'
      }
    ]
  }
});
```

## 跟踪事件

每个事件方法都接受有效载荷。 可选 `siteId` 可以提供覆盖特定事件的全球站点ID.

用于产品有效载荷 `uid` 作为变体/项目标识符和 `parentId` 作为母产品标识符。 对于没有变种的简单产品,设置 `uid` 财务报告和审定财务报表 `parentId` 以同样价值计算。 对于横幅有效载荷, `uid` 指的是横幅标识符.

以下代码样本使用a `beacon` 变量——取而代之的是适当的切入点:

| 路径 | 入境点 |
| --- | --- |
| 光盘N | `const beacon = window.athos.tracker;` |
| 国家预防机制 | `const beacon = new Beacon({ siteId: 'abc123' });` |

### 跳跃事件

#### 登录

当用户登录到他们的shopper账户时跟踪 .

```typescript
beacon.events.shopper.login({ 
  data: { id: 'shopper-12345' }
});
```

### 自动完成事件

自动完成事件跟踪自动完成/搜索建议界面内的用户交互.

#### 渲染器

自动完成向用户提出的建议时的音轨 .

```typescript
beacon.events.autocomplete.render({ 
  data: {
    responseId: response.responseId
  }
});
```

#### 印象

自动补全建议的音轨印象(可见性).

```typescript
beacon.events.autocomplete.impression({ 
  data: {
    responseId: response.responseId,
    results: [
      { type: 'product', uid: 'variant-1', parentId: 'product-1', sku: 'SKU-1' },
      { type: 'banner', uid: 'banner-1' }
    ],
    banners: [
      { uid: 'banner-1' }
    ]
  }
});
```

#### 添加到墨盒中

跟踪当用户从自动完成结果中将产品添加到推车中时 .

```typescript
beacon.events.autocomplete.addToCart({ 
  data: {
    responseId: response.responseId,
    results: [
      { 
        uid: 'variant-1', 
        parentId: 'product-1',
        sku: 'SKU-1', 
        qty: 1, 
        price: 29.99 
      }
    ]
  }
});
```

这种方法会自动管理存储的手推车状态.

#### 点击通过

当用户点击自动完成建议时跟踪 .

```typescript
beacon.events.autocomplete.clickThrough({ 
  data: {
    responseId: response.responseId,
    results: [
      { 
        type: 'product', 
        uid: 'variant-1', 
        parentId: 'product-1',
        sku: 'SKU-1'
      }
    ]
  }
});
```

#### 重定向

当自动补全建议导致页面重定向时跟踪 .

```typescript
const redirectUrl = response.merchandising?.redirect; // 'https://example.com/sale-page'
beacon.events.autocomplete.redirect({ 
  data: {
    redirect: redirectUrl,
    responseId: response.responseId
  }
});
```

### 搜索事件

搜索事件跟踪搜索结果页面中的用户互动.

#### 渲染器

```typescript
beacon.events.search.render({ 
  data: {
    responseId: response.responseId
  }
});
```

#### 印象

```typescript
beacon.events.search.impression({ 
  data: {
    responseId: response.responseId,
    results: [
      { type: 'product', uid: 'variant-1', parentId: 'product-1', sku: 'SKU-1' },
      { type: 'product', uid: 'variant-2', parentId: 'product-2', sku: 'SKU-2' }
    ],
    banners: [{ uid: 'banner-1' }]
  }
});
```

#### 添加到墨盒中

```typescript
beacon.events.search.addToCart({ 
  data: {
    responseId: response.responseId,
    results: [
      { 
        uid: 'variant-1', 
        parentId: 'product-1',
        sku: 'SKU-1', 
        qty: 1, 
        price: 29.99 
      }
    ]
  }
});
```

#### 点击通过

```typescript
beacon.events.search.clickThrough({ 
  data: {
    responseId: response.responseId,
    results: [
      {
        type: 'product',
        uid: 'variant-1',
        parentId: 'product-1',
        sku: 'SKU-1'
      }
    ]
  }
});
```

#### 重定向

```typescript
beacon.events.search.redirect({ 
  data: {
    redirect: 'https://example.com/promo',
    responseId: response.responseId
  }
});
```

### 类别 事件

类别事件跟踪用户在类别/列表页面上的互动.

#### 渲染器

```typescript
beacon.events.category.render({ 
  data: {
    responseId: response.responseId
  }
});
```

#### 印象

```typescript
beacon.events.category.impression({ 
  data: {
    responseId: response.responseId,
    results: [
      { type: 'product', uid: 'variant-1', parentId: 'product-1', sku: 'SKU-1' }
    ],
    banners: []
  }
});
```

#### 添加到墨盒中

```typescript
beacon.events.category.addToCart({ 
  data: {
    responseId: response.responseId,
    results: [
      {
        uid: 'variant-1',
        parentId: 'product-1',
        sku: 'SKU-1',
        qty: 1,
        price: 49.99
      }
    ]
  }
});
```

#### 点击通过

```typescript
beacon.events.category.clickThrough({ 
  data: {
    responseId: response.responseId,
    results: [
      {
        type: 'product',
        uid: 'variant-1',
        parentId: 'product-1',
        sku: 'SKU-1'
      }
    ]
  }
});
```

### 建议 活动

建议活动跟踪与个性化产品建议的互动.

#### 渲染器

跟踪向用户提供建议集时的情况.

```typescript
beacon.events.recommendations.render({ 
  data: {
    tag: 'homepage-recommendations',
    responseId: response.responseId
  }
});
```

#### 印象

对推荐产品的跟踪印象.

```typescript
beacon.events.recommendations.impression({ 
  data: {
    tag: 'homepage-recommendations',
    responseId: response.responseId,
    results: [
      { type: 'product', uid: 'variant-1', parentId: 'product-1', sku: 'SKU-1' },
      { type: 'product', uid: 'variant-2', parentId: 'product-2', sku: 'SKU-2' }
    ],
    banners: []
  }
});
```

#### 添加到墨盒中

跟踪用户在推车中添加推荐产品时.

```typescript
beacon.events.recommendations.addToCart({ 
  data: {
    tag: 'homepage-recommendations',
    responseId: response.responseId,
    results: [
      {
        uid: 'variant-1',
        parentId: 'product-1',
        sku: 'SKU-1',
        qty: 1,
        price: 39.99
      }
    ]
  }
});
```

#### 点击通过

音轨点击推荐产品.

```typescript
beacon.events.recommendations.clickThrough({ 
  data: {
    tag: 'homepage-recommendations',
    responseId: response.responseId,
    results: [
      {
        type: 'product',
        uid: 'variant-1',
        parentId: 'product-1',
        sku: 'SKU-1'
      }
    ]
  }
});
```

### 组合事件

Bundles事件跟踪与个性化产品捆绑的互动.

#### 渲染器

向用户提供捆绑集时跟踪 .

```typescript
beacon.events.bundles.render({ 
  data: {
    tag: 'pdp-bundles',
    responseId: response.responseId
  }
});
```

#### 印象

对捆绑产品的跟踪印象.

```typescript
beacon.events.bundles.impression({ 
  data: {
    tag: 'pdp-bundles',
    responseId: response.responseId,
    results: [
      { type: 'product', uid: 'variant-1', parentId: 'product-1', sku: 'SKU-1' },
      { type: 'product', uid: 'variant-2', parentId: 'product-2', sku: 'SKU-2' }
    ],
    banners: []
  }
});
```

#### 添加到墨盒中

当用户将捆绑的产品添加到手推车时会跟踪.

```typescript
beacon.events.bundles.addToCart({ 
  data: {
    tag: 'pdp-bundles',
    responseId: response.responseId,
    results: [
      {
        uid: 'variant-1',
        parentId: 'product-1',
        sku: 'SKU-1',
        qty: 1,
        price: 39.99
      }
    ]
  }
});
```

#### 点击通过

对被捆绑的产品进行跟踪点击.

```typescript
beacon.events.bundles.clickThrough({ 
  data: {
    tag: 'pdp-bundles',
    responseId: response.responseId,
    results: [
      {
        type: 'product',
        uid: 'variant-1',
        parentId: 'product-1',
        sku: 'SKU-1'
      }
    ]
  }
});
```

### 聊天活动

聊天事件跟踪与产品在聊天会话中浮出水面的互动. 每个聊天活动都需要一个 `chatSessionId` 将事件与特定的shopper对话联系起来.

#### 印象

对产品在聊天结果中浮出水面的跟踪印象.

```typescript
beacon.events.chat.impression({ 
  data: {
    chatSessionId: 'chat-session-12345',
    responseId: response.responseId,
    results: [
      { type: 'product', uid: 'variant-1', parentId: 'product-1', sku: 'SKU-1' },
      { type: 'product', uid: 'variant-2', parentId: 'product-2', sku: 'SKU-2' }
    ]
  }
});
```

#### 添加到墨盒中

跟踪用户从聊天结果中添加出一个产品到推车时.

```typescript
beacon.events.chat.addToCart({ 
  data: {
    chatSessionId: 'chat-session-12345',
    responseId: response.responseId,
    results: [
      {
        uid: 'variant-1',
        parentId: 'product-1',
        sku: 'SKU-1',
        qty: 1,
        price: 29.99
      }
    ]
  }
});
```

#### 点击通过

跟踪点击在聊天结果中浮出水面的产品.

```typescript
beacon.events.chat.clickThrough({ 
  data: {
    chatSessionId: 'chat-session-12345',
    responseId: response.responseId,
    results: [
      {
        type: 'product',
        uid: 'variant-1',
        parentId: 'product-1',
        sku: 'SKU-1'
      }
    ]
  }
});
```

#### 反馈

跟踪“ 积极” 或“ 消极” 聊天会话反馈 .

```typescript
beacon.events.chat.feedback({ 
  data: {
    chatSessionId: 'chat-session-12345',
    feedback: 'positive' // or ChatFeedbackSchemaDataFeedbackEnum.Positive for TypeScript
  }
});
```

### 产品事件

#### 页面视图

轨迹产品页面浏览. 这自动更新了已查看的产品历史 .

页面视图按单个变体发送一次`parentId`, (中文(简体) ), `uid`, (中文(简体) ), `sku`),每页加载和URL路径. 通话 `pageView` 再次使用已跟踪到当前变体 `pageLoadId` 和路径(例如,在变体之间互换,即使变体在查询字符串或散列中)不会发送重复事件。 导航到新路径或呼叫 `pageLoad()` 重置此跟踪 。 单页应用程序应调用 `pageLoad()` 导航(见 [单页应用程序( SPA) 支持](https://npmcn.com/package/%40athoscommerce/beacon/#readme-single-page-application-spa-support)),特别是使用以散列为主的路由.

```typescript
beacon.events.product.pageView({ 
  data: {
    result: {
      uid: 'variant-123',
      parentId: 'product-123',
      sku: 'SKU-123'
    }
  }
});
```

### 单元格事件

#### 添加

将产品添加到推车时跟踪.

```typescript
beacon.events.cart.add({ 
  data: {
    results: [
      { 
        uid: 'variant-1', 
        parentId: 'product-1',
        sku: 'SKU-1', 
        qty: 1, 
        price: 29.99 
      }
    ],
    cart: [
      { 
        uid: 'variant-1', 
        parentId: 'product-1',
        sku: 'SKU-1', 
        qty: 1, 
        price: 29.99 
      },
      { 
        uid: 'variant-2', 
        parentId: 'product-2',
        sku: 'SKU-2', 
        qty: 2, 
        price: 19.99 
      }
    ]
  }
});
```

车站状态是自动管理并与存储同步的.

#### 删除

产品从推车中取出时跟踪.

```typescript
beacon.events.cart.remove({ 
  data: {
    results: [
      { uid: 'variant-1', parentId: 'product-1', sku: 'SKU-1', qty: 1, price: 29.99 }
    ],
    cart: [
      { 
        uid: 'variant-2', 
        parentId: 'product-2',
        sku: 'SKU-2', 
        qty: 2, 
        price: 19.99 
      }
    ]
  }
});
```

### 顺序事件

#### 交易

追踪已完成的交易/订单.

```typescript
beacon.events.order.transaction({ 
  data: {
    orderId: 'order-12345',
    transactionTotal: 119.97,
    total: 129.97,
    vat: 0.20,
    city: 'New York',
    state: 'NY',
    country: 'US',
    results: [
      { 
        uid: 'variant-1', 
        parentId: 'product-1',
        sku: 'SKU-1', 
        qty: 2, 
        price: 29.99 
      },
      { 
        uid: 'variant-2', 
        parentId: 'product-2',
        sku: 'SKU-2', 
        qty: 1, 
        price: 60.00 
      }
    ]
  }
});
```

这种方法在跟踪交易后自动清除了存储的手推车.

### 错误跟踪事件

#### 保存像素出错

跟踪来自 Shopify 像素执行错误 .

```typescript
beacon.events.error.shopifypixel({ 
  data: {
    message: 'Product not found',
    stack: 'Error: Product not found\n  at fetchProduct (app.js:45)',
    details: { 
      productId: 'abc-123',
      endpoint: '/api/products/abc-123'
    }
  }
});
```

#### SNAP 错误

跟踪 SNAP 执行错误 .

```typescript
beacon.events.error.snap({ 
  data: {
    message: 'Failed to load recommendations',
    stack: 'Error: Network timeout\n  at loadRecs (snap.js:120)',
    details: { 
      tag: 'homepage-recs',
      timeout: 5000
    }
  }
});
```

## 储存管理

Beacon会自动管理本地存储和cookie,以保持整个会话的用户状态. 两个集成路径的存储 API 相同 —— `beacon` 从您的国家预防机制实例或 `window.athos.tracker` 从CDN.

-   **用户标识**: 持续18个月
-   **会话标识**: 持续30分钟
-   **圆筒**: 用户推车中的当前项目
-   **视图产品**:最近观看的产品(最多20个物品,每个母产品一个——最近观看的变种保存). 如果本地存储不可用, cookie倒置只存储产品ID, 因此同一父公司的变体不合并
-   **归属**: 运动/分配来源跟踪

灯塔也存储 **已搜索的查询** (最近每个站点Id的搜索查询,最多可有10个项,最近的第一个项),但搜索事件不携带查询,因此信标本身不添加. 一体化必须意味着 `storage.searched.add` 在每次搜索中查询( Snap 自动这样做); 否则 `lastSearches` 从未发送。 见 [已搜索的查询存储 API](https://npmcn.com/package/%40athoscommerce/beacon/#readme-searched-queries-storage-api)。 。 。 .

### 墨盒存储 API

通过 `storage.cart` API : (英语)

```typescript
// Get current cart
const cartItems = beacon.storage.cart.get();

// Set cart to specific items
beacon.storage.cart.set([
  { uid: 'variant-1-blue-m', parentId: 'product-1', sku: 'SKU-1', qty: 2, price: 29.99 }
]);

// Add items to cart
beacon.storage.cart.add([
  { uid: 'variant-2-red-l', parentId: 'product-2', sku: 'SKU-2', qty: 1, price: 19.99 }
]);

// Remove items from cart
beacon.storage.cart.remove([
  { uid: 'variant-1-blue-m', parentId: 'product-1', sku: 'SKU-1', qty: 1, price: 29.99 }
]);

// Clear cart
beacon.storage.cart.clear();
```

### 查看产品存储 API

访问和操纵已查看的产品历史 :

```typescript
// Get viewed products
const viewedItems = beacon.storage.viewed.get();

// Set viewed products
beacon.storage.viewed.set([
  { uid: 'variant-1-blue-m', parentId: 'product-1', sku: 'SKU-1' }
]);

// Add to viewed products
beacon.storage.viewed.add([
  { uid: 'variant-2-red-l', parentId: 'product-2', sku: 'SKU-2' }
]);
```

### 已搜索的查询存储 API

访问和操纵最近的搜索查询历史 。 每个查询都作为 `SearchedQuery` (单位:千美元)`{ query, timestamp }`何处 `timestamp` 是搜索时的ISO字符串。 查询被保留在最近的第一个,去重复(案件不敏感),并且仅限于最近的一个10个。 存储不因年龄而过期;消费者决定使用哪种查询. 譬如说, [`getLastSearches`](https://npmcn.com/package/%40athoscommerce/beacon/#readme-getlastsearchessiteid-string-string) 只返回过去两周的询问.

查询为每个站点单独存储 `athosSearchedQueries-<siteId>` (单位:千美元)`ssSearchedQueries-<siteId>` 用于不从开始的站点ID `at`),使用站点Id小写. 每个方法都接受可选 `siteId` 作为它最后一个参数和默认的站点Id,信标是用它创建的。 当 `lastSearches` 信标位置的更改,发送飞行前请求;为其他地点存储的查询,除非 `sendPreflight` 使用此名称 `siteId`。 。 。 .

```typescript
// Get searched queries
const searchedQueries = beacon.storage.searched.get();
// Returns: [{ query: 'boots', timestamp: '2026-09-23T14:00:00.000Z' }, ...]

// Add searched queries (most recent first; a query already present is moved to the front with a new timestamp)
beacon.storage.searched.add(['boots']);
beacon.storage.searched.add(['hats', 'gloves']);
// get() now returns the queries: 'hats', 'gloves', 'boots'

// Set searched queries directly (most recent first)
beacon.storage.searched.set([
  { query: 'boots', timestamp: '2026-09-23T14:00:00.000Z' },
  { query: 'shoes', timestamp: '2026-09-22T14:00:00.000Z' },
]);

// Remove searched queries (case insensitive)
beacon.storage.searched.remove(['Boots']);

// Clear searched queries
beacon.storage.searched.clear();

// Use the queries of another siteId
beacon.storage.searched.add(['bottes'], 'at1234');
beacon.storage.searched.get('at1234');
// Returns: [{ query: 'bottes', timestamp: '...' }]
```

## 公共 API 方法

以下方法在两种整合途径上均可使用. 在这些例子中, `beacon` 可能是你的国家预防机制实例,或者 `window.athos.tracker` 当使用CDN时.

### `setCurrency(currency: Currency)`

设置或更改用于跟踪交易的货币.

```typescript
beacon.setCurrency({ code: 'EUR' });
```

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `currency.code` | `string` | ISO 4217 货币编码 |

### `getContext(): Context`

获取当前跟踪上下文, 包括用户、 会话和页面信息 .

```typescript
const context = beacon.getContext();
// Returns: {
//   userId: 'uuid-...',
//   sessionId: 'uuid-...',
//   pageLoadId: 'uuid-...',
//   pageUrl: 'https://...',
//   userAgent: '...',
//   timestamp: '2024-01-01T...',
//   ...
// }
```

### `updateContext(key: keyof Context, value: any)`

更新特定上下文属性 .

```typescript
beacon.updateContext('userId', 'custom-user-id');
beacon.updateContext('dev', 'development');
beacon.updateContext('pageUrl', 'https://example.com/new-page');
```

### 用户ID管理

#### `getUserId(): string`

获取或生成当前用户ID .

```typescript
const userId = beacon.getUserId();
```

#### `getSessionId(): string`

获取或生成当前会话ID(在30分钟无活性后终止).

```typescript
const sessionId = beacon.getSessionId();
```

#### `getShopperId(): string`

设置时获取当前 spopp ID .

```typescript
const shopperId = beacon.getShopperId();
```

#### `setShopperId(shopperId: string): string | void`

设定shopper ID,触发登录事件到信标,并发送飞行前个人化请求.

```typescript
const result = beacon.setShopperId('shopper-12345');
```

### `getPageLoadId(): string`

获取当前页面加载ID 。 生成一个新的 `pageLoad()`。 。 。 .

```typescript
const pageLoadId = beacon.getPageLoadId();
```

### `pageLoad(): string`

生成新的页面加载ID 。 在单页应用程序内跟踪页面过渡或导航时,调用这种方法.

```typescript
const newPageLoadId = beacon.pageLoad();
```

### `getTimestamp(): string`

以 ISO 8601 格式获取当前时间戳 .

```typescript
const timestamp = beacon.getTimestamp();
```

### `getLastSearches(siteId?: string): string[]`

获取过去两周搜索到的查询( 最近的一次) 。 这是送来的 `lastSearches` 在飞行前的请求.

```typescript
const lastSearches = beacon.getLastSearches();
// Returns: ['boots', 'shoes', ...]
```

### `sendPreflight(overrides?: PreflightOverrides): void`

将飞行前数据发送到个性化API. 这是自动调用 当推车,查看的产品, `lastSearches` (指信标站点Id)或shopper状态变化,但需要时可以手动触发. 每个覆盖都是可选的,并回到存储值: `userId`, (中文(简体) ), `siteId` 财务报告和审定财务报表 `shopper` 是绳子, `cart` 是一个 `Product[]`, (中文(简体) ), `lastViewed` 是一个 `ProductPageviewSchemaDataResult[]` 财务报告和审定财务报表 `lastSearches` 是一个 `string[]`时 `lastSearches` 未提供, `getLastSearches` 用于飞行前 `siteId`。 。 。 .

```typescript
beacon.sendPreflight();

// With overrides
beacon.sendPreflight({
  userId: 'custom-user-id',
  siteId: 'custom-site-id',
  shopper: 'shopper-123',
  cart: [{ uid: 'variant-1', parentId: 'product-1', sku: 'SKU-1', qty: 1, price: 29.99 }],
  lastViewed: [{ uid: 'variant-2', parentId: 'product-2', sku: 'SKU-2' }],
  lastSearches: ['boots', 'shoes']
});
```

### `generateId(): string`

生成并返回一个新的 UUID .

```typescript
const id = beacon.generateId();
```

## 高级使用

### 自定义 API 终点

覆盖内部代理或自定义基础设施的默认 API 端点 :

```typescript
const beacon = new Beacon(
  { siteId: 'abc123' },
  {
    requesters: {
      beacon: {
        origin: 'https://internal-api.example.com/beacon/v2',
        headers: { 'X-Internal-Key': 'secret' }
      },
      personalization: {
        origin: 'https://internal-api.example.com/personalization',
        headers: { 'X-Internal-Key': 'secret' }
      }
    }
  }
);
```

### 单页应用程序( SPA) 支持

对于单页应用程序,当页面/视图改变时生成一个新的页面负载ID. 此功能还重新将产品页面视图分解, 因此返回到先前浏览的产品会发出一个新的页面视图:

```typescript
// On navigation
beacon.pageLoad();

// Track that we're now viewing a new product
beacon.events.product.pageView({ 
  data: { 
    result: { uid: 'variant-123', sku: 'SKU-123', parentId: 'product-123' }
  }
});
```

### 内容更新

作为用户行为或应用程序状态变化动态更新上下文 :

```typescript
// Update page URL for client-side routing
beacon.updateContext('pageUrl', window.location.href);
```

更新 `pageUrl` 不启动新页面负荷。 在导航方面,也打电话 `pageLoad()` (见 [单页应用程序( SPA) 支持](https://npmcn.com/package/%40athoscommerce/beacon/#readme-single-page-application-spa-support)) (中文(简体) ).

### 追踪

从 `athos_attribution` URL参数并包含在每个跟踪事件的上下文中. 不需要手动配置 .

```
https://example.com/products?athos_attribution=email:campaign-123
```

值格式为 `channel:campaign-id`启用 `beacon.getContext()` 检查当前属性状态.

## 发展模式

启用开发模式可防止灯塔事件出现在Athos控制台的报告上.

```typescript
const beacon = new Beacon(
  { siteId: 'abc123' },
  { mode: 'development' }
);
```

## 许可证

MIT - 详情见LICENSE文件

## 常见问题

### @athoscommerce/beacon 是什么？

使用 Athos 商业信标跟踪的 Javascript 库\.

### 如何安装 @athoscommerce/beacon？

在项目目录运行 npm install @athoscommerce/beacon，或使用 pnpm add / yarn add / bun add。

### @athoscommerce/beacon 支持 TypeScript 吗？

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

### @athoscommerce/beacon 支持 ESM 还是 CommonJS？

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

### @athoscommerce/beacon 可以商用吗？

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

### @athoscommerce/beacon 的下载量有多少？

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

### @athoscommerce/beacon 还在维护吗？

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