Documentatie AEM as a Cloud Service Handboek

AEM-CIF-kerncomponenten en Adobe Experience Platform-integratie

Last update: Sun Mar 23 2025 00:00:00 GMT+0000 (Coordinated Universal Time)

Onderwerpen:
Commerce Integration Framework

Gemaakt voor:

Beginner
Ontwikkelaar

De Commerce integration framework (CIF)kerncomponenten verstrekken naadloze integratie met Adobe Experience Platformom storefront gebeurtenissen en hun gegevens van cliënt-zijinteractie zoals toe te voegen aan wagentje.

Het 🔗 project van de Componenten van de Kern van AEM CIF verstrekt een bibliotheek van JavaScript genoemd schakelaar van Adobe Experience Platform voor Adobe Commerceom gebeurtenisgegevens van uw Commerce storefront te verzamelen. Deze gebeurtenisgegevens worden naar de Experience Platform verzonden waar ze worden gebruikt in andere Adobe Experience Cloud-producten, zoals Adobe Analytics en Adobe Target, om een profiel van 360 graden te maken dat een klantentraject bestrijkt. Door Commerce-gegevens aan te sluiten op andere producten in de Adobe Experience Cloud, kunt u taken uitvoeren zoals het gebruikersgedrag op uw site analyseren, AB-tests uitvoeren en gepersonaliseerde campagnes maken.

Leer meer over de 🔗 reeks van de Gegevensverzameling van 0} Experience Platform van technologieën die u toestaan om gegevens van de klantenervaring van cliënt-zijbronnen te verzamelen.

`addToCart` -gebeurtenisgegevens verzenden naar Experience Platform

In de volgende stappen wordt getoond hoe u de gebeurtenisgegevens van addToCart van door AEM gerenderde productpagina's naar de Experience Platform verzendt via de CIF - Experience Platform Connector. Met de Adobe Experience Platform Debugger-browserextensie kunt u de verzonden gegevens testen en bekijken.

de gebeurtenisgegevens van de Overzicht addToCart in Adobe Experience Platform Debugger

Vereisten

Gebruik een lokale ontwikkelomgeving om deze demo te voltooien. Dit omvat een lopende instantie van AEM die wordt gevormd en met een instantie van Adobe Commerce verbonden. Herzie de vereisten en de stappen voor vestiging lokale ontwikkeling met AEM as a Cloud Service SDK.

U hebt ook toegang tot Adobe Experience Platformen toestemmingen nodig om het schema, de dataset, en de gegevensstromen voor gegevensinzameling tot stand te brengen. Voor meer informatie, zie het beheer van de Toestemming.

AEM Commerce as a Cloud Service instellen

Om een werkende AEM Commerce as a Cloud Service lokaal milieu met de noodzakelijke code en config te hebben, voltooi de volgende stappen.

Lokale instellingen

Volg de Lokale 1} stappen van de Opstelling {zodat kunt u het werkende milieu van AEM as a Cloud Service hebben.

Projectinstelling

Volg de 🔗 stappen van de Archetype van het Project van 0} AEM {zodat kunt u een gloednieuw project van AEM Commerce (CIF) tot stand brengen.

TIP

In het volgende voorbeeld krijgt het AEM Commerce-project de naam: My Demo Storefront , maar u kunt uw eigen projectnaam kiezen.

AEM Commerce Project

Bouw en stel het gecreeerde project van AEM Commerce aan de lokale SDK van AEM door het volgende bevel van de wortelfolder van het project in werking te stellen.

$ mvn clean install -PautoInstallSinglePackage

De lokaal opgestelde My Demo StoreFront handelsplaats met standaardcode en inhoud kijkt als het volgende:

Standaard AEM Commerce Plaats

Afhankelijkheden van Peregrine- en CIF-AEP-connectors installeren

Als u de gebeurtenisgegevens van de categorie- en productpagina's van deze AEM Commerce-site wilt verzamelen en verzenden, installeert u de npm -sleutelpakketten in de module ui.frontend van het AEM Commerce-project.

Navigeer naar de module ui.frontend en installeer de vereiste pakketten door de volgende opdrachten vanaf de opdrachtregel uit te voeren.

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

Het --force argument wordt vereist soms aangezien PWA Studiomet de gesteunde peer gebiedsdelen restrictief is. Gewoonlijk zou dit geen problemen mogen veroorzaken.

Maven configureren voor gebruik van argument `--force`

Als onderdeel van het Maven-ontwikkelproces wordt de npm clean install (using npm ci ) geactiveerd. Hiervoor is ook het argument --force vereist.

Navigeer naar het basis-POM-bestand van het project pom.xml en zoek het <id>npm ci</id> -uitvoeringsblok. Werk het blok bij zodat het als het volgende kijkt:

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

Babel-configuratieopmaak wijzigen

Schakel van de standaard .babelrc bestands relatieve configuratie bestandsindeling naar babel.config.js indeling. Dit is een configuratieformaat voor het hele project en staat de stop-ins en de voorinstellingen toe om op node_module met grotere controle worden toegepast.

Navigeer naar de module ui.frontend en verwijder het bestaande .babelrc -bestand.

Maak een babel.config.js -bestand waarin de peregrine -voorinstelling wordt gebruikt.

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 configureren voor gebruik van Babel

Bewerk het webpack.common.js -bestand als u de JavaScript-bestanden wilt omzetten met behulp van Babel loader ( babel-loader ) en webpack.

Navigeer naar de module ui.frontend en werk het bestand webpack.common.js bij, zodat u de volgende regel binnen de waarde van de eigenschap module kunt gebruiken:

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

Apollo-client configureren

De Cliënt van Apollowordt gebruikt om zowel lokale als verre gegevens met GraphQL te beheren. De resultaten van GraphQL-query's worden ook opgeslagen in een lokale, genormaliseerde cache in het geheugen.

InMemoryCachewerken effectief, hebt u een possibleTypes.js dossier nodig. Om dit dossier te produceren, zie het Genereren van possibleTypes automatisch. Ook, zie de de verwijzingsimplementatie van PWA Studioen een voorbeeld van a possibleTypes.js dossier.

Ga naar de module ui.frontend en sla het bestand op als ./src/main/possibleTypes.js

Werk de sectie webpack.common.js file DefinePlugin bij zodat u de vereiste statische variabelen tijdens bouwtijd kunt vervangen.

const { DefinePlugin } = require('webpack');
const { POSSIBLE_TYPES } = require('./src/main/possibleTypes');

...

plugins: [
    ...
    new DefinePlugin({
        'process.env.USE_STORE_CODE_IN_URL': false,
        POSSIBLE_TYPES
    })
]

Basiscomponenten van Peregrine en CIF initialiseren

Als u de op React gebaseerde Peregrine- en CIF-kerncomponenten wilt initialiseren, maakt u de vereiste configuratie- en JavaScript-bestanden.

Navigeer naar de module ui.frontend en maak de volgende map: src/main/webpack/components/commerce/App

Maak een config.js -bestand met de volgende inhoud:

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

IMPORTANT

Terwijl u reeds met het config.jsdossier van AEM Guides - het Project van CIF Venia zou kunnen vertrouwd zijn, zijn er een paar veranderingen u aan dit dossier moet aanbrengen. Eerst, herzie om het even welke TODO commentaren. Zoek vervolgens binnen de eigenschap eventsCollector het object eventsCollector > aep en werk de eigenschappen orgId en datastreamId bij naar de juiste waarden. leer meer.

Maak een App.js -bestand met de volgende inhoud. Dit bestand lijkt op een typisch React-startpuntbestand en bevat React en aangepaste haken en React-contextgebruik om de Experience Platform-integratie te vergemakkelijken.

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

De EventCollectorContext exporteert de context React die:

laadt de bibliotheek commerce-events-sdk en commerce-events-collector;
initialiseert hen met een bepaalde configuratie voor Experience Platform en/of ACDS
schrijft zich in voor alle gebeurtenissen uit Peregrine en stuurt ze door naar de gebeurtenissen in SDK

U kunt de implementatiedetails van EventCollectorContext controleren. Zie aem-core-cif-componenten op GitHub.

Het bijgewerkte AEM-project bouwen en implementeren

Om ervoor te zorgen dat de bovenstaande pakketinstallatie, de code, en config veranderingen correct zijn, herbouwt, en stelt het bijgewerkte project van AEM Commerce op gebruikend het volgende Geweven bevel: $ mvn clean install -PautoInstallSinglePackage.

Experience Platform instellen

Voer de volgende stappen uit om de gebeurtenisgegevens die afkomstig zijn van de AEM Commerce-pagina's, zoals categorie en product, te ontvangen en op te slaan:

AVAILABILITY

Zorg ervoor u deel van de correcte Profielen van het Product onder Adobe Experience Platform en de Inzameling van Gegevens van Adobe Experience Platform uitmaakt. Indien nodig, werk met uw systeembeheerder om, Profielen van het Product onder Admin Consoletot stand te brengen bij te werken of toe te wijzen.

Schema maken met Commerce-veldgroep

Om de structuur voor de gegevens van de handelsgebeurtenis te bepalen, moet u een schema van de Gegevens van de Ervaring van het Model (XDM) tot stand brengen. Een schema is een set regels die de structuur en indeling van gegevens vertegenwoordigen en valideren.

In browser, navigeer aan de Adobe Experience Platform pagina van het producthuis. Bijvoorbeeld https://experience.adobe.com/#/@YOUR-ORG-NAME/sname:prod/platform/home .
Bepaal de plaats van het menu van Schema's in de linkernavigatiesectie, klik creeer Schema knoop van de top-right sectie, en selecteer XDM ExperienceEvent.
Geef uw schema een naam gebruikend het gebied van de Eigenschappen van het Schema > van de Naam van de Vertoning en voeg de groepen van het Gebied toe door de Samenstelling > van het Gebied > knoop toe te gebruiken.
In voeg de dialoog van de Groepen van het Gebied toe, onderzoek naar Commerce, selecteer Commerce Details checkbox, en klik voeg de groepen van het Gebied toe.

TIP

Zie de Grondbeginselen van schemacompositievoor meer informatie.

Gegevensset maken

Om de gebeurtenisgegevens op te slaan, moet u een Dataset tot stand brengen die aan de schemadefinitie voldoet. Een dataset is een opslag en beheersconstructie voor een inzameling van gegevens - typisch een lijst-die een schema (kolommen) en gebieden (rijen) bevat.

In browser, navigeer aan de Adobe Experience Platform pagina van het producthuis. Bijvoorbeeld https://experience.adobe.com/#/@YOUR-ORG-NAME/sname:prod/platform/home .
Bepaal de plaats van het menu van Datasets in de linkernavigatiesectie en klik creëren dataset knoop van de top-right sectie.
Voor de nieuwe pagina, creeer dataset van schema kaart.

Voor de nieuwe pagina, onderzoek en selecteer het schema u in de vorige stap creeerde, en klik de Volgende knoop.
Naam uw Dataset gebruikend vormt dataset > het gebied van de Naam en klikt de Afwerking knoop.

TIP

Zie het overzicht van Datasetsvoor meer informatie.

DataStream maken

Voer de volgende stappen uit zodat u een DataStream kunt maken in de Experience Platform.

In browser, navigeer aan de Adobe Experience Platform pagina van het producthuis. Bijvoorbeeld https://experience.adobe.com/#/@YOUR-ORG-NAME/sname:prod/platform/home .
Bepaal de plaats van het menu van Gegevensstromen in de linkernavigatiesectie en klik de Nieuwe knoop DataStream van de top-juiste sectie.
Noem uw DataStream gebruikend het Naam vereiste gebied. Onder het gebied van het Schema van de Gebeurtenis 0}, selecteer het gecreeerde schema en klik sparen .
Open gecreeerde DataStream, en klik voegt de Dienst toe.

toe
Onder het gebied van de Dienst, selecteer de Adobe Experience Platform optie. Onder Dataset van de Gebeurtenis gebied, selecteer de datasetnaam van de vorige stap en klik sparen.

toe

TIP

Zie het Overzicht DataStreamvoor meer informatie.

Gegevensstroomwaarde toevoegen aan AEM Commerce-configuratie

Na de voltooiing van de bovengenoemde opstelling van Experience Platform, zou u datastreamId in het linkerspoor van de gegevens moeten hebben DataStream en orgId in de hoger-juiste hoek van het Beeld van het Profiel > de informatie van de Rekening > de modaal van de Informatie van de Gebruiker.

identiteitskaart van Gegevens van AEP

Werk in de module ui.frontend van het AEM Commerce-project het config.js -bestand bij en specifiek de objecteigenschappen eventsCollector > aep .
Het bijgewerkte AEM Commerce-project bouwen en implementeren

Trigger `addToCart` -gebeurtenis activeren en gegevensverzameling controleren

De bovenstaande stappen voltooien de installatie van AEM Commerce en Experience Platform. U kunt een addToCart gebeurtenis nu teweegbrengen en gegevensinzameling verifiëren gebruikend de de uitbreiding van Google Chrome Inspecteur van de Snowplow en dataset Metriek en grafieken knevel in product UI.

Als u de gebeurtenis wilt activeren, kunt u de AEM-auteur of de publicatieservice gebruiken vanuit uw lokale instellingen. In dit voorbeeld gebruikt u de AEM-auteur door u aan te melden bij uw account.

Van de pagina van Plaatsen, selecteer Mijn Demo StoreFront > ons > en pagina en klik uitgeven in hoogste actiebar.
Van de hoogste actiebar, klik Mening zoals Gepubliceerd, dan om het even welke aangewezen categorie van de navigatie van de opslag.
Klik om het even welke aangewezen productkaart in de Pagina van het Product, dan uitgezochte kleur, grootte om toe te laten voeg aan Kar knoop toe.
Open de uitbreiding van de Inspecteur van de Snowplow van het browser uitbreidingspaneel en selecteer Experience Platform Wed SDK in het linkerspoor.
Terugkeer aan de Pagina van het Product en klik toevoegen aan de knoop van de Kar. Hiermee worden gegevens naar de Experience Platform verzonden. De Adobe Experience Platform Debugger uitbreiding toont de gebeurtenisdetails.
Binnen het product UI van Experience Platform, navigeer aan Datasets > Mijn Demo StoreFront, onder de activiteit van de Dataset tabel. Als Metriek en grafieken wordt toegelaten, worden de gebeurtenis-gegevens stats getoond.

Implementatiedetails

De Schakelaar van CIF Experience Platformwordt voortgebouwd bovenop de Verbinding van Gegevens voor Adobe Commerce, die deel van het PWA Studioproject uitmaakt.

Met het PWA Studio-project kunt u Progressive Web Application (PWA)-winkels maken die worden aangedreven door Adobe Commerce of Magento Open Source. Het project bevat ook een componentenbibliotheek genoemd Peregrinvoor het toevoegen van logica aan visuele componenten. De bibliotheek Peregrinverstrekt ook de haken van het douaneantwoord die door de Schakelaar van CIF Experience Platformworden gebruikt om met Experience Platform naadloos te integreren.

Ondersteunde gebeurtenissen

Vanaf nu worden de volgende gebeurtenissen ondersteund:

Ervaring XDM Gebeurtenissen:

Toevoegen aan winkelwagentje (AEM)
Pagina weergeven (AEM)
Product weergeven (AEM)
Zoekaanvraag verzonden (AEM)
Respons zoekopdracht ontvangen (AEM)

Wanneer Peregrine componentenin het project van AEM Commerce opnieuw worden gebruikt: