AEM-CIF-Kernkomponenten und Integration mit Adobe Experience Platform aem-cif-aep-integration

Die Kernkomponenten des Commerce Integration Framework (CIF) bieten eine nahtlose Integration mit Adobe Experience Platform, um Storefront-Ereignisse und deren Daten aus Client-seitigen Interaktionen, z. B. zum Warenkorb hinzufügen, weiterzuleiten.

Das Projekt CIF-Kernkomponenten für AEM stellt eine JavaScript-Bibliothek mit dem Namen Adobe Experience Platform Connector für Adobe Commerce zur Verfügung, um Ereignisdaten aus Ihrer Commerce-Storefront zu erfassen. Diese Ereignisdaten werden an Experience Platform gesendet. Dort werden sie in anderen Adobe Experience Cloud-Produkten wie Adobe Analytics und Adobe Target zum Erstellen eines 360-Grad-Profils verwendet, das eine Customer Journey abdeckt. Durch die Verbindung von Commerce-Daten mit anderen Produkten in Adobe Experience Cloud können Sie Aufgaben wie die Analyse des Benutzerverhaltens auf Ihrer Site, AB-Tests und die Erstellung personalisierter Kampagnen durchführen.

Hier finden Sie weitere Informationen zur Experience Platform Data Collection, einer Zusammenstellung von Technologien, mit denen Sie Kundenerlebnisdaten aus Client-seitigen Quellen erfassen können.

Senden von addToCart-Ereignisdaten an Experience Platform send-addtocart-to-aep

Die folgenden Schritte zeigen, wie Sie addToCart-Ereignisdaten von mit AEM gerenderten Produktseiten mithilfe des CIF Experience Platform-Connectors an Experience Platform senden können. Mithilfe der Browser-Erweiterung „Adobe Experience Platform Debugger“ können Sie die gesendeten Daten testen und überprüfen.

Überprüfen der „addToCart“-Ereignisdaten im Adobe Experience Platform Debugger

Voraussetzungen prerequisites

Verwenden Sie eine lokale Entwicklungsumgebung, um diese Demo abzuschließen. Dazu gehört eine laufende Instanz von AEM, die konfiguriert und mit einer Adobe Commerce-Instanz verbunden ist. Überprüfen Sie die Anforderungen und Schritte zum Einrichten einer lokalen Entwicklungsumgebung mit dem AEM as Cloud Service SDK.

Sie benötigen außerdem Zugriff auf Adobe Experience Platform und Berechtigungen zum Erstellen des Schemas, des Datensatzes und der Datenströme für die Datenerfassung. Weitere Informationen finden Sie unter Verwaltung von Berechtigungen.

Einrichten von AEM Commerce as a Cloud Service aem-setup

Um eine funktionierende lokale Umgebung für AEM Commerce as a Cloud Service mit dem notwendigen Code und der richtigen Konfiguration einzurichten, führen Sie die folgenden Schritte aus.

Lokales Setup

Befolgen Sie die unter Lokales Setup angegebenen Schritte, um eine funktionierende Umgebung für AEM Commerce as a Cloud Service zu erhalten.

Projekt-Setup

Befolgen Sie die unter AEM Projektarchetyp angegebenen Schritte, um ein brandneues AEM Commerce(CIF)-Projekt anzulegen.

TIP
Im folgenden Beispiel trägt das AEM Commerce-Projekt den Namen My Demo Storefront. Sie können jedoch Ihren eigenen Projektnamen auswählen.

AEM Commerce-Projekt

Erstellen Sie das angelegte AEM Commerce-Projekt und stellen Sie es im lokalen AEM SDK bereit, indem Sie den folgenden Befehl aus dem Stammverzeichnis des Projekts ausführen.

$ mvn clean install -PautoInstallSinglePackage

Die lokal bereitgestellte Commerce-Site My Demo StoreFront mit Standard-Code und Standardinhalt sieht wie folgt aus:

Standardmäßige AEM Commerce-Site

Installation der Connector-Abhängigkeiten von Peregrine und CIF-AEP

Um die Ereignisdaten von den Kategorie- und Produktseiten dieser AEM Commerce-Site zu erfassen und zu senden, installieren Sie die npm-Schlüsselpakete in das Modul ui.frontend des AEM Commerce-Projekts.

Navigieren Sie zum Modul ui.frontend und installieren Sie die erforderlichen Pakete, indem Sie die folgenden Befehle über die Befehlszeile ausführen.

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
Mitunter ist das Argument --force erforderlich, da PWA Studio gegenüber den unterstützten Peer-Abhängigkeiten restriktiv ist. Normalerweise sollte dies keine Probleme verursachen.

Konfigurieren von Maven für die Verwendung des Arguments --force

Im Rahmen des Build-Prozesses von Maven wird die bereinigte npm-Installation (mithilfe von npm ci) ausgelöst. Dies erfordert auch das Arument --force.

Navigieren Sie zur POM-Datei pom.xml im Stammverzeichnis des Projekts und suchen Sie nach dem Ausführungsblock <id>npm ci</id>. Aktualisieren Sie den Block so, dass er wie folgt aussieht:

<execution>
    <id>npm ci</id>
    <goals>
    <goal>npm</goal>
    </goals>
    <configuration>
    <arguments>ci --force</arguments>
    </configuration>
</execution>

Ändern des Babel-Konfigurationsformats

Wechseln Sie von der standardmäßigen Datei .babelrc für das Konfigurationsdateiformat zum Format babel.config.js. Dies ist ein projektweit gültiges Konfigurationsformat, das ermöglicht, die Plug-ins und Vorgaben mit besserer Steuerungsmöglichkeit auf node_module anzuwenden.

  1. Navigieren Sie zum ui.frontend-Modul und löschen Sie die vorhandene Datei .babelrc.

  2. Erstellen Sie eine Datei babel.config.js, die die Voreinstellung peregrine verwendet.

    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;
    }
    

Konfigurieren von Webpack für die Verwendung von Babel

Um die JavaScript-Dateien mit dem Babel-Lader (babel-loader) und Webpack zu transpilieren, bearbeiten Sie die Datei webpack.common.js.

Navigieren Sie zum Modul ui.frontend und aktualisieren Sie die Datei webpack.common.js so, dass die folgende Regel im module-Eigenschaftswert eingeschlossen ist:

{
    test: /\.jsx?$/,
    exclude: /node_modules\/(?!@magento\/)/,
    loader: 'babel-loader'
}

Konfigurieren des Apollo-Clients

Der Apollo-Client wird verwendet, um sowohl lokale Daten als auch Remote-Daten mit GraphQL zu verwalten. Außerdem speichert er die Ergebnisse von GraphQL-Abfragen in einem lokalen, normalisierten Arbeitsspeichercache.

Damit InMemoryCache effektiv arbeitet, benötigen Sie eine Datei possibleTypes.js. Informationen zum Generieren dieser Datei finden Sie unter Automatisches Generieren möglicher Typen. Siehe auch PWA Studio-Referenzimplementierung, wo Sie ein Beispiel für eine Datei possibleTypes.js finden.

  1. Navigieren Sie zum ui.frontend-Modul und speichern Sie die Datei als ./src/main/possibleTypes.js

  2. Aktualisieren Sie den Abschnitt DefinePlugin der Datei webpack.common.js, um die erforderlichen statischen Variablen zum Zeitpunkt der Erstellung zu ersetzen.

    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
        })
    ]
    

Initialisieren der Peregrine- und CIF-Kernkomponenten

Um die React-basierten Peregrine- und CIF-Kernkomponenten zu initialisieren, erstellen Sie die erforderlichen Konfigurations- und JavaScript-Dateien.

  1. Navigieren Sie zum ui.frontend-Modul und erstellen Sie den folgenden Ordner: src/main/webpack/components/commerce/App

  2. Erstellen Sie eine config.js-Datei mit folgendem Inhalt:

    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
    Vielleicht kennen Sie bereits die Datei config.js aus AEM Guides – CIF Venia Project. An dieser Datei müssen Sie einige Änderungen vornehmen. Überprüfen Sie zunächst alle TODO-Kommentare. Anschließend suchen Sie innerhalb der Eigenschaft eventsCollector nach dem eventsCollector > aep-Objekt und aktualisieren die Eigenschaften orgId und datastreamId auf die korrekten Werte. Weitere Informationen
  3. Erstellen Sie eine Datei App.js mit folgendem Inhalt. Diese Datei ähnelt einer typischen React-App-Startpunktdatei und enthält React- und benutzerdefinierte Hooks sowie die Verwendung von React Context, um die Integration von Experience Platform zu erleichtern.

    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 exportiert den React Context, der

    • die Bibliotheken „commerce-events-sdk“ und „commerce-events-collection“ lädt,
    • sie mit einer bestimmten Konfiguration für Experience Platform und/oder ACDS initialisiert,
    • alle Ereignisse von Peregrine abonniert und an den Ereignis-SDK weiterleitet.

    Die Details der Implementierung von EventCollectorContext können Sie hier anschauen.

Erstellen und Bereitstellen des aktualisierten AEM-Projekts

Um sicherzustellen, dass die vorstehend angegebenen Änderungen an Paketinstallation, Code und Konfiguration korrekt sind, erstellen Sie das aktualisierte AEM Commerce-Projekt neu und stellen Sie es mithilfe des folgenden Maven-Befehls bereit: $ mvn clean install -PautoInstallSinglePackage.

Setup von Experience Platform aep-setup

Um die von den AEM Commerce-Seiten kommenden Ereignisdaten, wie etwa Kategorie und Produkt, zu empfangen und zu speichern, führen Sie die folgenden Schritte vollständig aus:

AVAILABILITY
Stellen Sie sicher, dass Sie Teil der korrekten Produktprofile unter Adobe Experience Platform und Adobe Experience Platform-Datenerfassung sind. Arbeiten Sie bei Bedarf mit Ihrem Systemadministrator zusammen, um Produktprofile unter der Admin Console zu erstellen, zu aktualisieren oder zuzuweisen.

Erstellen eines Schemas mit einer Commerce-Feldergruppe

Um die Struktur für Commerce-Ereignisdaten zu definieren, müssen Sie ein Schema für ein Experience-Datenmodell (XDM) erstellen. Ein Schema ist ein Set von Regeln, das die Datenstruktur und das Datenformat darstellt und validiert.

  1. Navigieren Sie im Browser zur Produkt-Startseite von Adobe Experience Platform. Beispiel: https://experience.adobe.com/#/@YOUR-ORG-NAME/sname:prod/platform/home.

  2. Suchen Sie das Menü Schemata im linken Navigationsbereich. Klicken Sie dann oben rechts auf die Schaltfläche Schema erstellen und wählen Sie XDM ExperienceEvent.

    Erstellen eines AEP-Schemas

  3. Benennen Sie Ihr Schema mithilfe von Schemaeigenschaften > Anzeigename und fügen Sie über die Schaltfläche Komposition > Feldergruppen > Hinzufügen Feldergruppen hinzu.

    AEP-Schemadefinition

  4. Suchen Sie im Dialogfeld Feldergruppen hinzufügen nach Commerce, aktivieren Sie das Kontrollkästchen Commerce-Details und klicken Sie auf Feldergruppen hinzufügen.

    AEP-Schemadefinition

TIP
Weiter Informationen finden Sie unter Grundlagen der Schemakomposition.

Erstellen eines Datensatzes

Um die Ereignisdaten zu speichern, müssen Sie einen Datensatz erstellen, der der Schemadefinition entspricht. Ein Datensatz ist ein Speicher- und Verwaltungskonstrukt für eine Sammlung von Daten, normalerweise eine Tabelle, die ein Schema (Spalten) und Felder (Zeilen) enthält.

  1. Navigieren Sie im Browser zur Produkt-Startseite von Adobe Experience Platform. Beispiel: https://experience.adobe.com/#/@YOUR-ORG-NAME/sname:prod/platform/home.

  2. Suchen Sie das Menü Datensätze im linken Navigationsbereich und klicken Sie oben rechts auf die Schaltfläche Datensatz erstellen.

    AEP – Datensätze erstellen

  3. Wählen Sie auf der neuen Seite die Karte Datensatz aus Schema erstellen aus.

    AEP-Option – Datensatzschema erstellen

    Suchen und wählen Sie auf der neuen Seite das Schema aus, dass Sie im vorherigen Schritt erstellt haben, und klicken Sie auf Weiter.

    AEP – Datensatz erstellen, Schema auswählen

  4. Benennen Sie Ihren Datensatz, indem Sie das Feld Datensatz konfigurieren > Name benutzen, und klicken Sie auf Beenden.

    AEP – Datensatznamen erstellen

TIP
Weitere Informationen finden Sie unter Datensätze – Übersicht.

Datenstrom erstellen

Führen Sie die folgenden Schritte aus, um einen Datenstrom in Experience Platform zu erstellen.

  1. Navigieren Sie im Browser zur Produkt-Startseite von Adobe Experience Platform. Beispiel: https://experience.adobe.com/#/@YOUR-ORG-NAME/sname:prod/platform/home.

  2. Suchen Sie das Menü Datenströme im linken Navigationsbereich und klicken Sie oben rechts auf Neuer Datenstrom.

    AEP – Datenströme erstellen

  3. Benennen Sie Ihren Datenstrom mithilfe des erforderlichen Feldes Name. Wählen Sie das erstellte Schema unter dem Feld Ereignisschema aus und wählen Sie dann Speichern.

    AEP – Datenströme definieren

  4. Öffnen Sie den erstellten Datenstrom und klicken Sie auf Service hinzufügen.

    AEP-Datenströme – Service hinzufügen

  5. Wählen Sie unter dem Feld Service die Option Adobe Experience Platform aus. Wählen Sie unter dem Feld Datensatzereignis den Datensatznamen aus dem vorherigen Schritt aus und klicken Sie auf Speichern.

    AEP-Datenströme – Service-Details hinzufügen

TIP
Weitere Informationen finden Sie unter Datenströme – Übersicht.

Hinzufügen des Datenstromwerts in die AEM Commerce-Konfiguration add-aep-values-to-aem

Nach Abschluss des oben genannten Experience Platform-Setups sollten Sie datastreamId in der linken Leiste der Datenstromdetails und orgId in der oberen rechten Ecke des Modals Profilbild > Kontoinformationen > Benutzerinformationen sehen.

AEP – Datenstrom-ID

  1. Aktualisieren Sie im Modul ui.frontend des AEM Commerce-Projekts die Datei config.js und insbesondere die Eigenschaften des Objekts eventsCollector > aep.

  2. Erstellen und Bereitstellen des aktualisierten AEM Commerce-Projekts

Triggern des addToCart-Ereignisses und Überprüfen der Datenerfassung event-trigger-verify

Mit den obigen Schritten ist die Einrichtung von AEM Commerce und Experience Platform abgeschlossen. Sie können jetzt ein Ereignis addToCart auslösen und die Datenerfassung mit der Google Chrome-Erweiterung Snowplow Inspector sowie mit dem Datensatz-Umschalter Metriken und Diagramme in der Produkt-Benutzeroberfläche überprüfen.

Um das Ereignis zu triggern, können Sie den AEM-Autor oder den Veröffentlichungs-Service Ihrer lokalen Einrichtung verwenden. Verwenden Sie für dieses Beispiel den AEM-Autor, indem Sie sich bei Ihrem Konto anmelden.

  1. Wählen Sie auf der Sites-Seite die Seite My Demo StoreFront > us > en und klicken Sie auf Bearbeiten in der oberen Aktionsleiste.

  2. Klicken Sie in der oberen Aktionsleiste auf Als veröffentlicht anzeigen und klicken Sie dann in der Navigation der Storefront auf eine beliebige bevorzugte Kategorie.

  3. Klicken Sie auf eine beliebige Produktkarte auf der Produktseite und wählen Sie Farbe, Größe, um die Schaltfläche Zum Warenkorb hinzufügen zu aktivieren.

  4. Öffnen Sie im Erweiterungsbedienfeld des Browsers die Erweiterung Snowplow Inspector und wählen Sie in der linken Leiste die Option Experience Platform Web SDK aus.

  5. Kehren Sie zur Produktseite zurück und klicken Sie auf die Schaltfläche Zum Warenkorb hinzufügen. Dadurch werden Daten an die Experience Platform gesendet. Die Erweiterung Adobe Experience Platform Debugger zeigt die Ereignisdetails an.

    AEP Debugger für „Zum Warenkorb hinzufügen“-Ereignisdaten

  6. Navigieren Sie in der Experience Platform-Produktoberfläche unter der Registerkarte Datensatzaktivität zu Datensätze > My Demo StoreFront. Wenn  Metriken und Diagramme  aktiviert ist, werden die Statistiken für Ereignisdaten angezeigt.

    Statistiken zu Datensatzdaten in Experience Platform

Implementierungsdetails implementation-details

Der CIF Experience Platform Connector basiert auf Data Connection für Adobe Commerce, was Teil des PWA Studio-Projekts ist.

Mit dem PWA Studio-Projekt können Sie Storefronts als Progressive Web Applications (PWA) erstellen, die von Adobe Commerce oder Magento Open Source unterstützt werden. Das Projekt enthält auch eine Komponentenbibliothek mit dem Namen Peregrin für das Hinzufügen von Logiken zu visuellen Komponenten. Die Peregrin-Bibliothek stellt auch die benutzerdefinierten React-Hooks bereit, die von CIF Experience Platform Connector zur nahtlosen Integration in Experience Platform verwendet werden.

Unterstützte Ereignisse supported-events

Ab sofort werden die folgenden Ereignisse unterstützt:

Experience-XDM-Ereignisse:

  1. Zum Warenkorb hinzufügen (AEM)
  2. Anzeigen der Seite (AEM)
  3. Anzeigen des Produkts (AEM)
  4. Suchanfrage gesendet (AEM)
  5. Suchantwort erhalten (AEM)

Wann Peregrine-Komponenten im AEM Commerce-Projekt wiederverwendet werden:

Experience-XDM-Ereignisse:

  1. Entfernen aus Warenkorb
  2. Öffnen des Warenkorbs
  3. Anzeigen des Warenkorbs
  4. Sofortkauf
  5. Start des Checkouts
  6. Abschließen des Checkouts

Profile-XDM-Ereignisse:

  1. Anmelden
  2. Konto erstellen
  3. Konto bearbeiten

Zusätzliche Ressourcen additional-resources

Weitere Informationen finden Sie in den folgenden Ressourcen:

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