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 事件資料會從AEM呈現的產品頁面使用CIF -Experience Platform聯結器傳送到Experience Platform。 使用Adobe Experience Platform Debugger瀏覽器擴充功能,即可測試和檢閱提交的資料。

在Adobe Experience Platform Debugger中檢閱addToCart事件資料

先決條件 prerequisites

使用本機開發環境來完成此示範。 這包括已設定並連線至Adobe Commerce執行個體的AEM執行個體。 檢閱的需求和步驟 使用AEMas a Cloud ServiceSDK設定本機開發.

您還需要下列專案的存取權: Adobe Experience Platform 以及建立資料收集之結構、資料集和資料流的許可權。 如需詳細資訊,請參閱 許可權管理.

AEM Commerceas a Cloud Service設定 aem-setup

讓工作正常進行 AEM商務as 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全新安裝(使用 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 檔案。 若要產生此檔案,請參閱 自動產生possibleType. 另請參閱 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作者。

  1. 從網站頁面,選取 我的示範StoreFront >我們> en 頁面並按一下 編輯 在頂端動作列中。

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

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

  4. 開啟 雪鏟檢測器 從瀏覽器的擴充功能面板選取「 」 Experience Platform週三SDK 在左側邊欄中。

  5. 返回 產品頁面 並按一下 加入購物車 按鈕。 這會將資料傳送至Experience Platform。 此 Adobe Experience Platform Debugger 擴充功能會顯示事件詳細資訊。

    AEP Debugger Add-To-Cart事件資料

  6. 在Experience Platform產品UI中,導覽至 資料集>我的示範StoreFront,位於 資料集活動 標籤。 如果 度量與圖表 已啟用,則會顯示事件資料統計資料。

    Experience Platform資料集資料統計資料

實作詳細資料 implementation-details

CIFExperience Platform聯結器 建立在 Adobe Commerce的資料連線,屬於 PWA Studio 專案。

PWA Studio專案可讓您建立由Adobe Commerce或Magento Open Source支援的Progressive Web Application(PWA)店面。 專案也包含元件程式庫,稱為 Peregrin 用於新增邏輯至視覺元件。 此 Peregrin程式庫 也提供以下使用者使用的自訂React鉤點: CIFExperience Platform聯結器 與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