文件AEM as a Cloud Service使用手冊

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

Last update: Thu Aug 15 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

建立對象：

  • 初學者
  • 開發人員

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物件並將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. 使用​ 名稱 ​必要欄位來命名您的資料流。 在​ 事件結構描述 ​欄位下，選取已建立的結構描述，然後按一下​ 儲存。

    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