文档AEM as a Cloud Service用户指南

AEM-CIF核心组件与Adobe Experience Platform集成 aem-cif-aep-integration

Last update: Mon May 05 2025 00:00:00 GMT+0000 (Coordinated Universal Time)
  • 适用对象：
  • Experience Manager as a Cloud Service

创建对象：

  • 初学者
  • 开发人员

Commerce integration framework (CIF)核心组件提供与Adobe Experience Platform的无缝集成，以便从客户端交互（如​ 添加到购物车）转发店面事件及其数据。

AEM CIF核心组件项目提供了一个名为Adobe Experience Platform connector for Adobe Commerce的JavaScript库，用于从Commerce店面收集事件数据。 该事件数据会被发送到Experience Platform，并在其他Adobe Experience Cloud产品(如Adobe Analytics和Adobe Target)中使用，以构建涵盖客户历程的360度个人资料。 通过将Commerce数据连接到Adobe Experience Cloud中的其他产品，您可以执行分析网站上的用户行为、执行AB测试以及创建个性化营销活动等任务。

详细了解Experience Platform数据收集成套技术，这些技术允许您从客户端源收集客户体验数据。

将addToCart事件数据发送到Experience Platform send-addtocart-to-aep

以下步骤显示了如何使用CIF - Experience Platform Connector将addToCart事件数据从AEM渲染的产品页面发送到Experience Platform。 通过使用Adobe Experience Platform Debugger浏览器扩展，您可以测试和审查提交的数据。

在Adobe Experience Platform Debugger中查看addToCart事件数据

先决条件 prerequisites

使用本地开发环境完成此演示。 这包括一个AEM正在运行的实例，该实例已配置并连接到Adobe Commerce实例。 查看使用AEM as a Cloud Service SDK设置本地开发的要求和步骤。

您还需要访问Adobe Experience Platform和权限以创建用于数据收集的架构、数据集和数据流。 有关详细信息，请参阅权限管理。

AEM Commerce as a Cloud Service设置 aem-setup

要让具有必要代码和配置的工作中​ AEM Commerce as a Cloud Service ​本地环境，请完成以下步骤。

本地设置

执行本地设置步骤，以便您可以拥有一个有效的AEM Commerce as a Cloud Service环境。

项目设置

执行AEM项目原型步骤，以便创建全新的AEM Commerce (CIF)项目。

TIP
在以下示例中，AEM Commerce项目名为： My Demo Storefront，但您可以选择自己的项目名称。

AEM Commerce项目

通过从项目的根目录运行以下命令，生成已创建的AEM Commerce项目并将其部署到本地AEM SDK。

$ mvn clean install -PautoInstallSinglePackage

本地部署的My Demo StoreFront商业网站具有默认代码和内容，如下所示：

默认AEM Commerce站点

安装Peregrine和CIF-AEP连接器依赖项

要从此AEM Commerce站点的类别和产品页面收集事件数据并将其发送，请将密钥npm包安装到AEM Commerce项目的ui.frontend模块中。

导航到ui.frontend模块，并通过从命令行运行以下命令来安装所需的包。

npm i --save lodash.get@^4.4.2 lodash.set@^4.3.2
npm i --save apollo-cache-persist@^0.1.1
npm i --save redux-thunk@~2.3.0
npm i --save @adobe/apollo-link-mutation-queue@~1.1.0
npm i --save @magento/peregrine@~12.5.0
npm i --save @adobe/aem-core-cif-react-components --force
npm i --save-dev @magento/babel-preset-peregrine@~1.2.1
npm i --save @adobe/aem-core-cif-experience-platform-connector --force
IMPORTANT
--force参数有时是必需的，因为PWA Studio对支持的对等依赖项进行了限制。 通常，这应该不会导致任何问题。

配置Maven以使用--force参数

在Maven构建过程中，会触发npm全新安装（使用npm ci）。 这还需要--force参数。

导航到项目的根POM文件pom.xml并找到<id>npm ci</id>执行块。 更新块，使其类似于以下内容：

<execution>
    <id>npm ci</id>
    <goals>
    <goal>npm</goal>
    </goals>
    <configuration>
    <arguments>ci --force</arguments>
    </configuration>
</execution>

更改Babel配置格式

从默认的.babelrc文件相对配置文件格式切换为babel.config.js格式。 这是项目范围的配置格式，允许将插件和预设应用于具有较大控制权的node_module。

  1. 导航到ui.frontend模块并删除现有.babelrc文件。

  2. 创建使用peregrine预设的babel.config.js文件。

    code language-javascript 
    const peregrine = require('@magento/babel-preset-peregrine');

module.exports = (api, opts = {}) => {
    const config = {
        ...peregrine(api, opts),
        sourceType: 'unambiguous'
    }

    config.plugins = config.plugins.filter(plugin => plugin !== 'react-refresh/babel');

    return config;
}

配置webpack以使用Babel

要使用Babel加载器(babel-loader)和Webpack传输JavaScript文件，请编辑webpack.common.js文件。

导航到ui.frontend模块并更新webpack.common.js文件，以便您可以在module属性值内使用以下规则：

{
    test: /\.jsx?$/,
    exclude: /node_modules\/(?!@magento\/)/,
    loader: 'babel-loader'
}

配置Apollo客户端

Apollo客户端用于通过GraphQL管理本地和远程数据。 它还会将GraphQL查询的结果存储在本地的规范化内存缓存中。

为了使InMemoryCache有效工作，您需要一个possibleTypes.js文件。 要生成此文件，请参阅自动生成possibleTypes。 另请参阅PWA Studio引用实现和possibleTypes.js文件示例。

  1. 导航到ui.frontend模块并将文件另存为./src/main/possibleTypes.js

  2. 更新webpack.common.js文件的DefinePlugin部分，以便在生成期间替换所需的静态变量。

    code language-javascript 
    const { DefinePlugin } = require('webpack');
const { POSSIBLE_TYPES } = require('./src/main/possibleTypes');

...

plugins: [
    ...
    new DefinePlugin({
        'process.env.USE_STORE_CODE_IN_URL': false,
        POSSIBLE_TYPES
    })
]

初始化Peregrine和CIF核心组件

要初始化基于React的Peregrine和CIF核心组件，请创建所需的配置和JavaScript文件。

  1. 导航到ui.frontend模块并创建以下文件夹： src/main/webpack/components/commerce/App

  2. 创建包含以下内容的config.js文件：

    code language-javascript 
    // get and parse the CIF store configuration from the <head>
const storeConfigEl = document.querySelector('meta[name="store-config"]');
const storeConfig = storeConfigEl ? JSON.parse(storeConfigEl.content) : {};

// the following global variables are needed for some of the peregrine features
window.STORE_VIEW_CODE = storeConfig.storeView || 'default';
window.AVAILABLE_STORE_VIEWS = [
    {
        code: window.STORE_VIEW_CODE,
        base_currency_code: 'USD',
        default_display_currency_code: 'USD',
        id: 1,
        locale: 'en',
        secure_base_media_url: '',
        store_name: 'My Demo StoreFront'
    }
];
window.STORE_NAME = window.STORE_VIEW_CODE;
window.DEFAULT_COUNTRY_CODE = 'en';

export default {
    storeView: window.STORE_VIEW_CODE,
    graphqlEndpoint: storeConfig.graphqlEndpoint,
    // Can be GET or POST. When selecting GET, this applies to cache-able GraphQL query requests only.
    // Mutations will always be executed as POST requests.
    graphqlMethod: storeConfig.graphqlMethod,
    headers: storeConfig.headers,

    mountingPoints: {
        // TODO: define the application specific mount points as they may be used by <Portal> and <PortalPlacer>
    },
    pagePaths: {
        // TODO: define the application specific paths/urls as they may be used by the components
        baseUrl: storeConfig.storeRootUrl
    },
    eventsCollector: {
        eventForwarding: {
            acds: true,
            aep: false,
        }
    }
};
    note important
    IMPORTANT
    您可能已经熟悉​__AEM Guides - CIF Venia项目__​中的config.js文件，但必须对此文件进行一些更改。 首先，查看任何​__TODO__​备注。 然后，在eventsCollector属性内，查找eventsCollector > aep对象并将orgId和datastreamId属性更新为正确的值。 了解详情。

  3. 创建包含以下内容的App.js文件。 此文件类似于典型的React应用程序起点文件，包含React和自定义挂接以及React Context用法，可促进Experience Platform集成。

    code language-javascript 
    import config from './config';

import React, { useEffect } from 'react';
import ReactDOM from 'react-dom';
import { IntlProvider } from 'react-intl';
import { BrowserRouter as Router } from 'react-router-dom';
import { combineReducers, createStore } from 'redux';
import { Provider as ReduxProvider } from 'react-redux';
import { createHttpLink, ApolloProvider } from '@apollo/client';
import { ConfigContextProvider, useCustomUrlEvent, useReferrerEvent, usePageEvent, useDataLayerEvents, useAddToCartEvent } from '@adobe/aem-core-cif-react-components';
import { EventCollectorContextProvider, useEventCollectorContext } from '@adobe/aem-core-cif-experience-platform-connector';
import { useAdapter } from '@magento/peregrine/lib/talons/Adapter/useAdapter';
import { customFetchToShrinkQuery } from '@magento/peregrine/lib/Apollo/links';
import { BrowserPersistence } from '@magento/peregrine/lib/util';
import { default as PeregrineContextProvider } from '@magento/peregrine/lib/PeregrineContextProvider';
import { enhancer, reducers } from '@magento/peregrine/lib/store';

const storage = new BrowserPersistence();
const store = createStore(combineReducers(reducers), enhancer);

storage.setItem('store_view_code', config.storeView);

const App = () => {
    const [{ sdk: mse }] = useEventCollectorContext();

    // trigger page-level events
    useCustomUrlEvent({ mse });
    useReferrerEvent({ mse });
    usePageEvent({ mse });
    // listen for add-to-cart events and enable forwarding to the magento storefront events sdk
    useAddToCartEvent(({ mse }));
    // enable CIF specific event forwarding to the Adobe Client Data Layer
    useDataLayerEvents();

    useEffect(() => {
        // implement a proper marketing opt-in, for demo purpose you hard-set the consent cookie
        if (document.cookie.indexOf('mg_dnt') < 0) {
            document.cookie += '; mg_dnt=track';
        }
    }, []);

    // TODO: use the App to create Portals and PortalPlaceholders to mount the CIF / Peregrine components to the server side rendered markup
    return <></>;
};

const AppContext = ({ children }) => {
    const { storeView, graphqlEndpoint, graphqlMethod = 'POST', headers = {}, eventsCollector } = config;
    const { apolloProps } = useAdapter({
        apiUrl: new URL(graphqlEndpoint, window.location.origin).toString(),
        configureLinks: (links, apiBase) =>
            // reconfigure the HTTP link to use the configured graphqlEndpoint, graphqlMethod and storeView header

            links.set('HTTP', createHttpLink({
                fetch: customFetchToShrinkQuery,
                useGETForQueries: graphqlMethod !== 'POST',
                uri: apiBase,
                headers: { ...headers, 'Store': storeView }
            }))
    });

    return (
        <ApolloProvider {...apolloProps}>
            <IntlProvider locale='en' messages={{}}>
                <ConfigContextProvider config={config}>
                    <ReduxProvider store={store}>
                        <PeregrineContextProvider>
                            <EventCollectorContextProvider {...eventsCollector}>
                                {children}
                            </EventCollectorContextProvider>
                        </PeregrineContextProvider>
                    </ReduxProvider>
                </ConfigContextProvider>
            </IntlProvider>
        </ApolloProvider>
    );
};

window.onload = async () => {
    const root = document.createElement('div');
    document.body.appendChild(root);

    ReactDOM.render(
        <Router>
            <AppContext>
                <App />
            </AppContext>
        </Router>,
        root
    );
};

    EventCollectorContext导出React上下文，其中：

    • 加载commerce-events-sdk和commerce-events-collector库，
    • 使用Experience Platform和/或ACDS的给定配置初始化它们
    • 从Peregrine订阅所有事件并将它们转发到SDK事件

    您可以查看EventCollectorContext的实施详细信息。 请参阅GitHub🔗上的aem-core-cif-components。

生成和部署更新的AEM项目

要确保上述软件包安装、代码和配置更改正确，请使用以下Maven命令重新生成和部署更新的AEM Commerce项目： $ mvn clean install -PautoInstallSinglePackage。

Experience Platform设置 aep-setup

要接收并存储来自AEM Commerce页面（如类别和产品）的事件数据，请完成以下步骤：

AVAILABILITY
确保您属于​__Adobe Experience Platform__​和​__Adobe Experience Platform数据收集__​下的正确​__产品配置文件__。 如果需要，请与系统管理员合作以在Admin Console下创建、更新或分配​__产品配置文件__。

使用Commerce字段组创建架构

要定义商务事件数据的结构，您必须创建体验数据模型(XDM)架构。 架构是一组规则，用于表示和验证数据的结构和格式。

  1. 在浏览器中，导航到​ Adobe Experience Platform ​产品主页。 例如 https://experience.adobe.com/#/@YOUR-ORG-NAME/sname:prod/platform/home。

  2. 在左侧导航部分找到​ 架构 ​菜单，单击右上角的​ 创建架构 ​按钮，然后选择​ XDM ExperienceEvent。

    AEP创建架构

  3. 使用​ 架构属性>显示名称 ​字段命名您的架构，并使用​ 组合>字段组>添加 ​按钮添加字段组。

    AEP架构定义

  4. 在​ 添加字段组 ​对话框中，搜索Commerce，选中​ Commerce详细信息 ​复选框，然后单击​ 添加字段组。

    AEP架构定义

TIP
有关详细信息，请参阅架构组合🔗的基础知识。

创建数据集

要存储事件数据，您必须创建符合架构定义的数据集。 数据集是用于数据集合的存储和管理结构，通常是包含架构（列）和字段（行）的表。

  1. 在浏览器中，导航到​ Adobe Experience Platform ​产品主页。 例如 https://experience.adobe.com/#/@YOUR-ORG-NAME/sname:prod/platform/home。

  2. 在左侧导航部分中找到​ 数据集 ​菜单，然后单击右上角部分的​ 创建数据集 ​按钮。

    AEP创建数据集

  3. 在新页面上，选择​ 从架构 ​信息卡创建数据集。

    AEP创建数据集架构选项

    在新页面上，搜索并选择 ​您在上一步中创建的架构，然后单击​ 下一步 ​按钮。

    AEP创建数据集选择架构

  4. 使用​ 配置数据集>名称 ​字段命名您的数据集，然后单击​ 完成 ​按钮。

    AEP创建数据集名称

TIP
有关详细信息，请参阅数据集概述。

创建数据流

完成以下步骤，以便在Experience Platform中创建数据流。

  1. 在浏览器中，导航到​ Adobe Experience Platform ​产品主页。 例如 https://experience.adobe.com/#/@YOUR-ORG-NAME/sname:prod/platform/home。

  2. 在左侧导航部分中找到​ 数据流 ​菜单，然后单击右上角部分的​ 新建数据流 ​按钮。

    AEP创建数据流

  3. 使用​ Name ​必填字段命名您的数据流。 在​ 事件架构 ​字段下，选择已创建的架构，然后单击​ 保存。

    AEP定义数据流

  4. 打开创建的数据流，然后单击​ 添加服务。

    AEP数据流添加服务

  5. 在​ 服务 ​字段下，选择​ Adobe Experience Platform ​选项。 在​ 事件数据集 ​字段下，从上一步中选择数据集名称，然后单击​ 保存。

    AEP数据流添加服务详细信息

TIP
有关详细信息，请参阅数据流概述。

将数据流值添加到AEM Commerce配置 add-aep-values-to-aem

完成上述Experience Platform设置后，数据流详细信息的左边栏中应该有datastreamId，并且​ 配置文件图片>帐户信息>用户信息 ​模式窗口的右上角应该有orgId。

AEP数据流ID

  1. 在AEM Commerce项目的ui.frontend模块中，更新config.js文件并具体更新eventsCollector > aep对象属性。

  2. 生成和部署更新的AEM Commerce项目

触发addToCart事件并验证数据收集 event-trigger-verify

上述步骤已完成AEM Commerce和Experience Platform的设置。 您现在可以在产品UI中使用Google Chrome扩展​ 雪铲检查器 ​和数据集​ 量度和图形 ​切换触发addToCart事件并验证数据收集。

要触发该事件，您可以从本地设置使用AEM创作或发布服务。 对于此示例，请通过登录到您的帐户来使用AEM author。

  1. 从Sites页面中，选择​ 我的演示StoreFront >我们> en ​页面，然后单击顶部操作栏中的​ 编辑。

  2. 在顶部操作栏中，单击​ 以发布的形式查看，然后单击店面导航中的任意首选类别。

  3. 单击​ 产品页 ​中任何首选的产品卡，然后选择​ 颜色，大小 ​以启用​ 添加到购物车 ​按钮。

  4. 从浏览器的扩展面板中打开​ Snowplow Inspector ​扩展，然后在左边栏中选择​ Experience Platform Wed SDK。

  5. 返回​ 产品页 ​并单击​ 添加到购物车 ​按钮。 这会向Experience Platform发送数据。 Adobe Experience Platform Debugger ​扩展显示事件详细信息。

    AEP Debugger Add-To-Cart Event-Data

  6. 在Experience Platform产品UI中的​ 数据集活动 ​选项卡下，导航到​ 数据集> My Demo StoreFront。 如果启用了​ 量度和图形，则会显示事件数据统计信息。

    Experience Platform数据集数据统计信息

实施详细信息 implementation-details

CIF Experience Platform Connector基于Adobe Commerce🔗的数据连接而构建，后者是PWA Studio项目的一部分。

PWA Studio项目允许您创建由Adobe Commerce或Magento Open Source提供支持的Progressive Web Application (PWA)店面。 该项目还包含一个名为Peregrin的组件库，用于向可视化组件添加逻辑。 Peregrin库还提供了CIF Experience Platform Connector用于与Experience Platform无缝集成的自定义React挂接。

支持的事件 supported-events

截至目前，支持以下事件：

体验XDM事件：

  1. 添加到购物车(AEM)
  2. 查看页面(AEM)
  3. 查看产品(AEM)
  4. 已发送搜索请求(AEM)
  5. 搜索响应已收到(AEM)

在AEM Commerce项目中重用Peregrine组件时：

体验XDM事件：

  1. 从购物车中移除
  2. 打开购物车
  3. 查看购物车
  4. 即时购买
  5. 开始结帐
  6. 完成签出

配置文件XDM事件：

  1. 登录
  2. 创建帐户
  3. 编辑帐户

其他资源 additional-resources

有关更多信息，请参阅以下资源：

recommendation-more-help
fbcff2a9-b6fe-4574-b04a-21e75df764ab