@athoscommerce/beacon

中文文档

1.4.0发布于 2026/10/29MITTypeScriptESM + CJS构建来源已验证近 30 天下载 2307

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

文档目录48 节

特征
用法路径
快速启动: CDN
快速启动:国家预防机制
安装
光盘N
国家预防机制
初始化
CDN 初始化
国家防范机制启动
共同属性
响应Id
商品行(Banner ID)
快速查看
跟踪事件
跳跃事件
自动完成事件
搜索事件
类别事件
建议活动
组合事件
聊天活动
产品事件
单元格事件
顺序事件
错误跟踪事件
储存管理
墨盒存储 API
查看产品存储 API
已搜索的查询存储 API
公共 API 方法
setCurrency(currency: Currency)
getContext(): Context
updateContext(key: keyof Context, value: any)
用户ID管理
getPageLoadId(): string
pageLoad(): string
getTimestamp(): string
getLastSearches(siteId?: string): string[]
sendPreflight(overrides?: PreflightOverrides): void
generateId(): string
高级使用
自定义 API 终点
单页应用程序( SPA) 支持
内容更新
追踪
发展模式
许可证

信标.js

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

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

特征

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

用法路径

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

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

快速启动: CDN

<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 .

快速启动:国家预防机制

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> 标签 :

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

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

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

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

国家预防机制

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

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 构造器包含适用于所有跟踪事件所需的全局配置.

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

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

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

灯塔配置

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

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提供参数.

// 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,
  }
});

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

// 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用于常规页面上的互动.

// 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账户时跟踪 .

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

自动完成事件

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

渲染器

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

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

印象

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

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' }
    ]
  }
});

添加到墨盒中

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

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

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

点击通过

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

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

重定向

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

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

搜索事件

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

渲染器

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

印象

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' }]
  }
});

添加到墨盒中

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

点击通过

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

重定向

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

类别事件

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

渲染器

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

印象

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

添加到墨盒中

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

点击通过

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

建议活动

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

渲染器

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

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

印象

对推荐产品的跟踪印象.

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: []
  }
});

添加到墨盒中

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

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
      }
    ]
  }
});

点击通过

音轨点击推荐产品.

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

组合事件

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

渲染器

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

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

印象

对捆绑产品的跟踪印象.

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: []
  }
});

添加到墨盒中

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

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
      }
    ]
  }
});

点击通过

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

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对话联系起来.

印象

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

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' }
    ]
  }
});

添加到墨盒中

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

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
      }
    ]
  }
});

点击通过

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

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

反馈

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

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) 支持),特别是使用以散列为主的路由.

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

单元格事件

添加

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

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 
      }
    ]
  }
});

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

删除

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

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 
      }
    ]
  }
});

顺序事件

交易

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

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 像素执行错误 .

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 执行错误 .

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。。。 .

墨盒存储 API

通过 storage.cart API : (英语)

// 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

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

// 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 只返回过去两周的询问.

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

// 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)`

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

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

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

`getContext(): Context`

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

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

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

更新特定上下文属性 .

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

用户ID管理

`getUserId(): string`

获取或生成当前用户ID .

const userId = beacon.getUserId();

`getSessionId(): string`

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

const sessionId = beacon.getSessionId();

`getShopperId(): string`

设置时获取当前 spopp ID .

const shopperId = beacon.getShopperId();

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

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

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

`getPageLoadId(): string`

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

const pageLoadId = beacon.getPageLoadId();

`pageLoad(): string`

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

const newPageLoadId = beacon.pageLoad();

`getTimestamp(): string`

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

const timestamp = beacon.getTimestamp();

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

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

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。。。 .

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 .

const id = beacon.generateId();

高级使用

自定义 API 终点

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

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. 此功能还重新将产品页面视图分解, 因此返回到先前浏览的产品会发出一个新的页面视图:

// 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' }
  }
});

内容更新

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

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

更新 pageUrl 不启动新页面负荷。在导航方面,也打电话 pageLoad() (见单页应用程序( SPA) 支持) (中文(简体) ).

追踪

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

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

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

发展模式

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

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

许可证

MIT - 详情见LICENSE文件

版本与发布记录

@athoscommerce/beacon 共发布 13 个版本，首次发布于 2026/02/06；过去 12 个月发布了 13 个版本。最新版本附带 npm provenance 构建来源证明，可追溯到公开的 CI 构建记录。

版本	发布日期	距今
`1.4.0`latest	2026/10/29	9 天前
`1.3.0`	2026/07/10	3 个月前
`1.2.3`	2026/06/10	4 个月前
`1.2.2`	2026/05/13	5 个月前
`1.2.1`	2026/05/02	6 个月前
`1.2.0`	2026/05/02	6 个月前

关于 @athoscommerce/beacon 的常见问题