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

Commerce integration framework(CIF) 核心组件提供与 Adobe Experience Platform 通过客户端交互(例如 添加到购物车.

AEM CIF核心组件 项目提供了一个名为的JavaScript库 适用于Adobe Commerce的Adobe Experience Platform连接器 以从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

以下步骤显示如何发送 addToCart 使用CIF — 事件连接器将AEM渲染的产品Experience Platform中的事件数据发送到Experience Platform。 通过使用Adobe Experience Platform Debugger浏览器扩展,您可以测试和查看提交的数据。

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

先决条件 prerequisites

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

您还需要访问 Adobe Experience Platform 和创建用于数据收集的模式、数据集和数据流的权限。 有关更多信息,请参阅 权限管理.

AEM Commerceas a Cloud Service设置 aem-setup

让一个工作 AEM Commerceas a Cloud Service 本地环境中具有必需的代码和配置,请完成以下步骤。

本地设置

请遵循 本地设置 步骤以使您拥有一个有效的AEM Commerceas 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 将包打包到 ui.frontend AEM Commerce项目模块。

导航至 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 clean install(使用 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. 创建 babel.config.js 使用 peregrine 预设。

    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加载器传输JavaScript文件(babel-loader)和webpack,编辑 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 文件。 要生成此文件,请参阅 自动生成可能的类型. 另外,请参见 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
    您可能已经熟悉 config.js 文件来源 AEM Guides - CIF Venia项目,您必须对此文件进行一些更改。 首先,查看任意 任务 注释。 然后,在内部 eventsCollector 属性,查找 eventsCollector > aep 对象并更新 orgIddatastreamId 属性到正确的值。 了解详情
  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 此处.

生成和部署更新的AEM项目

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

Experience Platform设置 aep-setup

要接收并存储来自AEM Commerce页面(如类别和产品)的事件数据,请完成以下步骤:

AVAILABILITY
确保您属于正确的组 产品配置文件Adobe Experience PlatformAdobe Experience Platform数据收集. 如果需要,请与系统管理员合作以创建、更新或分配 产品配置文件Admin Console.

使用商务字段组创建架构

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

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

  2. 找到 架构 菜单的左侧导航部分,单击 创建架构 按钮,然后选择 XDM ExperienceEvent.

    AEP创建架构

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

    AEP架构定义

  4. 添加字段组 对话框,搜索 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. 使用命名数据流 名称 必填字段。 在 事件架构 字段中,选择创建的架构并单击 保存.

    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的设置。 您现在可以触发 addToCart 事件并使用Google Chrome扩展验证数据收集 雪铲检查器 和数据集 量度和图形 在产品UI中进行切换。

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

  1. 从“站点”页面中,选择 我的演示StoreFront >我们> en 页面并单击 编辑 在顶部操作栏中。

  2. 在顶部操作栏中,单击 查看已发布的项目,然后单击店面导航中的任意首选类别。

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

  4. 打开 雪铲检查器 扩展选项,然后选择 Experience Platform周三SDK 在左边栏中。

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

    AEP调试器添加到购物车事件数据

  6. 在Experience Platform产品UI中,导航到 数据集>我的演示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库 还提供了由使用的自定义React挂钩 CIF Experience Platform Connector 以实现与Experience Platform的无缝集成。

支持的事件 supported-events

截至目前,支持以下事件:

体验XDM事件:

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

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

体验XDM事件:

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

配置文件XDM事件:

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

其他资源 additional-resources

有关更多信息,请参阅以下资源:

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