# @adobe/magento-storefront-event-collector 中文文档

规范地址：https://npmcn.com/package/%40adobe/magento-storefront-event-collector/

版本：1\.18\.0
npm 元数据更新时间：2026-10-01T01:34:31.876Z
中文译文更新时间：2026-11-05T20:26:59.200Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40adobe/magento-storefront-event-collector
原文对照：https://npmcn.com/package/%40adobe/magento-storefront-event-collector/?lang=original
项目主页：https://github.com/adobe/commerce-events/tree/main/packages/commerce-events-collectors#readme
源码仓库：https://github.com/adobe/commerce-events

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

- 包体积（解压后）：364 kB，221 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：6 个
- 首次发布：2021-03-18T13:44:58.156Z
- 最新版本发布：2026-08-11T14:52:20.193Z
- 近 30 天下载量：28296（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：310（近 12 个月 9 个）

## 中文简介

Adobe 商务商店前端事件收集器

## 安装

```sh
npm install @adobe/magento-storefront-event-collector
```

也可以使用：`pnpm add @adobe/magento-storefront-event-collector`、`yarn add @adobe/magento-storefront-event-collector`、`bun add @adobe/magento-storefront-event-collector`

## README

# Adobe 商务事件收集器

[![version](https://img.shields.io/npm/v/@adobe/magento-storefront-event-collector.svg?style=flat-square)](https://npmjs.com/package/@adobe/commerce-events-collectors) [![downloads](https://img.shields.io/npm/dt/@adobe/magento-storefront-event-collector?style=flat-square)](https://npmjs.com/package/@adobe/commerce-events-collectors) [![size](https://img.shields.io/bundlephobia/minzip/@adobe/magento-storefront-event-collector?style=flat-square)](https://bundlephobia.com/result?p=@adobe/magento-storefront-event-collector) [![build](https://img.shields.io/github/workflow/status/adobe/magento-storefront-event-collector/merge-to-main?style=flat-square)](https://github.com/adobe/commerce-events/actions) [![typescript](https://img.shields.io/npm/types/@adobe/commerce-events-collectors?style=flat-square)](https://typescriptlang.org/dt/search?search=%40adobe%2Fcommerce-events-collectors) [![contributing](https://img.shields.io/badge/PRs-welcome-success?style=flat-square)](https://github.com/adobe/commerce-events/blob/main/.github/CONTRIBUTING.md)

## 概览

此软件包会收听和处理由 KTC 发布的事件 [Adobe 商务活动 SDK](https://npmjs.com/package/@adobe/magento-storefront-events-sdk) 转到 adobeDataLayer[缩写](https://github.com/adobe/adobe-client-data-layer)。它作为副作用运行,意在为想要向Adobe Commerce发送事件数据的用户提供方便.

## 安装

收集器可以用作主机脚本,也可以被捆绑在JavaScript应用程序中. 脚本版本托管于 [兹德利夫尔](https://cdn.jsdelivr.net/npm/@adobe/magento-storefront-event-collector/dist/index.js),则捆绑的版本在 [无](https://npmjs.com/package/@adobe/commerce-events-collectors)。 。 。 .

要将收集器装入脚本, 请使用以下片段 .

```
<script src="https://cdn.jsdelivr.net/npm/@adobe/commerce-events-collectors/dist/index.js"></script>
```

要将脚本安装为依赖, 请运行此命令 .

```shell
npm install @adobe/commerce-events-collectors
```

## 快开始

在加载收集器脚本后,或导入下面显示的包后,没有其他需要做的事情.

```javascript
import "@adobe/commerce-events-collectors";
```

## 使用量

收藏家为以下事件聆听.

-   `pageView`
-   `addToCart`
-   `productPageView`
-   `shoppingCartView`
-   `initiateCheckout`
-   `openCart`
-   `placeOrder`
-   `recsItemAddToCartClick`
-   `recsItemClick`
-   `recsRequestSent`
-   `recsResponseReceived`
-   `recsUnitRender`
-   `recsUnitView`
-   `removeFromCart`
-   `searchCategoryClick`
-   `searchProductClick`
-   `searchRequestSent`
-   `searchResponseReceived`
-   `searchResultsView`
-   `categoryResultsView`
-   `searchSuggestionClick`
-   `createAccount`
-   `editAccount`
-   `signIn`
-   `signOut`
-   `custom`

B2B事件

-   `createRequisitionList`
-   `deleteRequisitionList`
-   `addToRequisitionList`
-   `removeFromRequisitionList`

处理器将事件推进到两个边缘:

-   Adobe Commerce Data Services (由Adobe Engineering维护并用于为商家的性能仪表板提供动力) 互联网档案馆的存檔,存档日期2013-12-21
    
    所需上下文 :
    
    -   `StorefrontInstance`
    
    未转交 Adobe Commerce 的事件 :
    
    -   `createAccount`
    -   `editAccount`
    -   `openCart`
    -   `removeFromCart`
    -   `signIn`
    -   `signOut`
    -   `custom`
    
    B2B事件:
    
    -   `createRequisitionList`
    -   `deleteRequisitionList`
    -   `addToRequisitionList`
    -   `removeFromRequisitionList`
-   [Adobe 体验平台](https://business.adobe.com/products/experience-platform/adobe-experience-platform.html) (需要订阅和额外商户) [设置](https://experienceleague.adobe.com/docs/experience-platform/edge/fundamentals/datastreams.html?lang=en);数据可以被Adobe体验平台内的商人用来进行详细的分析,有针对性地进行交易,实时客户数据简介等)
    
    所需上下文 :
    
    -   `AEP`
    -   `EventForwarding.aep: true`
    
    未转发到 AEP 边缘的事件 :
    
    -   `recsItemAddToCartClick`
    -   `recsItemClick`
    -   `recsRequestSent`
    -   `searchResponseReceived`
    -   `searchCategoryClick`
    -   `searchProductClick`
    -   `searchResultsView`
    -   `categoryResultsView`
    -   `searchSuggestionClick`

### 每个边缘关闭收藏

事件默认会发送给Adobe Commerce Data Services. 要关闭收藏, 设置 `EventForwarding.commerce: false`。 。 。 .

除非明确配置,否则事件不会被设定为AEP边缘(`EventForwarding.aep: true`(三);

### 处理自定义事件

自定义事件只为Adobe体验平台所支持. 自定义数据不会被传送到Adobe商业仪表板和度量衡跟踪器.

对于任何 `custom` 事件,收藏者:

-   添加`identityMap` 与 `ECID` 作为主要身份
-   包含 `email` 内 `identityMap` 作为次要身份 _若为_ `personalEmail.address` 设置在事件
-   将全部事件覆盖在 `xdm` 对象在转发到边缘之前

示例

通过 MSE SDK 发布的自定义事件 :

```javascript
mse.publish.custom({
    commerce: {
        saveForLaters: {
            value: 1,
        },
    },
});
```

在AEP边缘:

```javascript
{
  xdm: {
    identityMap: {
      ECID: [
        {
          id: 'ecid1234',
          primary: true
        }
      ],
      email: [
        {
          id: "runs@safari.ke",
          primary: false
        }
      ]
    },
    commerce: {
        saveForLaters: {
            value: 1
        }
    }
  }
}
```

**说明** 使用自定义事件可能影响OOTB Adobe Analytics报告.

### 处理事件覆盖( 自定义属性)

只支持经验平台的标准活动属性覆盖。 自定义数据不会被传送到商务仪表板和度量衡跟踪器.

对于任何有设定的事件 `customContext`中,收藏器将连接在相关背景中设置的字段与在 `customContext`。超接的用例是开发者想要在已经支持的事件中重新使用并扩展页面其他部分设定的上下文.

_说明_ 当超过自定义事件时,向 AEP 转发的事件应当为该事件类型而关闭,以避免重复计算.

示例

Adobe Commerce 的产品视图覆盖了通过 MSE SDK 发布的 :

产品上下文( 由页面上的另一个脚本设置) :

```javascript
{
}
```

```javascript
mse.publish.productPageView({
    productListItems: [
        {
            productCategories: [
                {
                    categoryID: "cat_15",
                    categoryName: "summer pants",
                    categoryPath: "pants/mens/summer",
                },
            ],
        },
    ],
});
```

在AEP边缘:

```javascript
{
  xdm: {
    eventType: 'commerce.productViews',
    identityMap: {
      ECID: [
        {
          id: 'ecid1234',
          primary: true,
        }
      ]
    },
    commerce: {
      productViews: {
        value : 1,
      }
    },
    productListItems: [{
        SKU: "1234",
        name: "leora summer pants",
        productCategories: [{
            categoryID: "cat_15",
            categoryName: "summer pants",
            categoryPath: "pants/mens/summer",
        }],
    }],
  }
}
```

**说明** 覆盖带有自定义属性的事件可能影响OOTB Adobe Analytics报告.

## Shopper 同意和数据收集

"mg dnt"饼干被"产品建议"用来限制数据收集.

当 [饼干限制模式](https://experienceleague.adobe.com/docs/commerce-admin/start/compliance/privacy/compliance-cookie-law.html) 启用后,数据服务将设置“ mg dnt” cookie 为正版 .

```javascript
const listenForCookieEvents = ($) => {
    const DNT_COOKIE = "mg_dnt";
    let userAllowedSaveCookie = !!$.mage.cookies.get("user_allowed_save_cookie");

    if (userAllowedSaveCookie) {
        $.mage.cookies.clear(DNT_COOKIE);
    } else {
        $.mage.cookies.set(DNT_COOKIE, true);
    }
};
```

默认情况下,AEP中的用户同意优先被设定为"opt in",除非启用了cookie限制模式并存在"mg dnt"cookie.

脚本会保持投票,以检查任何更改,并将更新后的优先选择发送到AEP.

```javascript
const doNotTrackCookie = document.cookie.indexOf("mg_dnt") !== -1;
alloy("setConsent", {
    consent: [
        {
            standard: "Adobe",
            version: "1.0",
            value: {
                general: doNotTrackCookie ? "out" : "in",
            },
        },
    ],
});
setInterval(setConsent, 1000);
```

## PII 数据收集

以下事件将用户的电子邮件作为 PII 数据转发给 AEP :

`createAccount`

`editAccount`

`signIn`

## 支助

如果您有任何问题或遇到任何问题,请联系这些地点.

-   [GitHub 图像](https://github.com/adobe/commerce-events/issues)

## 常见问题

### @adobe/magento-storefront-event-collector 是什么？

Adobe 商务商店前端事件收集器

### 如何安装 @adobe/magento-storefront-event-collector？

在项目目录运行 npm install @adobe/magento-storefront-event-collector，或使用 pnpm add / yarn add / bun add。

### @adobe/magento-storefront-event-collector 支持 TypeScript 吗？

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

### @adobe/magento-storefront-event-collector 支持 ESM 还是 CommonJS？

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

### @adobe/magento-storefront-event-collector 可以商用吗？

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

### @adobe/magento-storefront-event-collector 的下载量有多少？

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

### @adobe/magento-storefront-event-collector 还在维护吗？

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