AEM-CIF核心元件與Adobe Experience Platform整合 aem-cif-aep-integration

Commerce integration framework(CIF)核心元件提供與Adobe Experience Platform的緊密整合,以從使用者端互動(例如​ 加入購物車)轉寄店面事件及其資料。

AEM CIF核心元件專案為Adobe Commerce🔗提供名為Adobe Experience Platform聯結器的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

使用本機開發環境來完成此示範。 這包括已設定並連線至Adobe Commerce執行個體的AEM執行個體。 檢閱使用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 Project Archetype步驟操作,以建立全新的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. 使用​ 名稱 ​必要欄位來命名您的資料流。 在​ 事件結構描述 ​欄位下,選取已建立的結構描述,然後按一下​ 儲存

    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作者。

  1. 從Sites頁面,選取​ My Demo StoreFront >我們> en ​頁面,然後按一下頂端動作列中的​ 編輯

  2. 在頂端動作列中,按一下​ 以發佈的形式檢視,然後按一下店面導覽中任何偏好的類別。

  3. 按一下​ 產品頁面 ​中任何偏好的產品卡,然後選取​ 顏色,大小 ​以啟用​ 加入購物車 ​按鈕。

  4. 從瀏覽器的擴充功能面板開啟​ Snowplow Inspector ​擴充功能,並在左側邊欄中選取​ Experience PlatformWed 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

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