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

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 - Event Connector将addToCart事件数据从AEM渲染的产品Experience Platform发送到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 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包安装到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对象并将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 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 PlatformWed SDK

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

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

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

    Experience Platform的数据集数据统计信息

实施详细信息 implementation-details

CIFExperience Platform连接器构建在Adobe Commerce🔗的数据连接之上,它是PWA Studio项目的一部分。

PWA Studio项目允许您创建由Adobe Commerce或Magento Open Source提供支持的Progressive Web Application(PWA)店面。 该项目还包含一个名为Peregrin的组件库,用于向可视化组件添加逻辑。 Peregrin库还提供了CIFExperience Platform连接器用于与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