Componenti core AEM-CIF e integrazione con Adobe Experience Platform aem-cif-aep-integration

I componenti core Commerce integration framework (CIF) forniscono un'integrazione perfetta con Adobe Experience Platform per inoltrare gli eventi storefront e i relativi dati dalle interazioni lato client, ad esempio aggiungi al carrello.

Il progetto AEM CIF Core Components fornisce una libreria JavaScript denominata Connettore Adobe Experience Platform per Adobe Commerce per raccogliere i dati evento dalla vetrina Commerce. I dati dell’evento vengono inviati all’Experience Platform in cui vengono utilizzati in altri prodotti Adobe Experience Cloud, come Adobe Analytics e Adobe Target, per creare un profilo a 360 gradi che copre un percorso di clienti. Collegando i dati di Commerce ad altri prodotti in Adobe Experience Cloud, puoi eseguire attività come analizzare il comportamento degli utenti sul tuo sito, eseguire test AB e creare campagne personalizzate.

Ulteriori informazioni sulla suite di tecnologie Experience Platform Data Collection che consente di raccogliere i dati sull'esperienza del cliente da origini lato client.

Invia dati evento addToCart ad Experience Platform send-addtocart-to-aep

Nei passaggi seguenti viene illustrato come inviare i dati dell'evento addToCart dalle pagine di prodotto sottoposte a rendering AEM all'Experience Platform utilizzando il connettore CIF - Experience Platform. Utilizzando l’estensione del browser Adobe Experience Platform Debugger, puoi verificare e rivedere i dati inviati.

Rivedi i dati dellevento addToCart in Adobe Experience Platform Debugger

Prerequisiti prerequisites

Utilizza un ambiente di sviluppo locale per completare questa demo. Ciò include un’istanza in esecuzione dell’AEM configurata e connessa a un’istanza Adobe Commerce. Rivedi i requisiti e i passaggi per configurare lo sviluppo locale con AEM as a Cloud Service SDK.

È inoltre necessario accedere a Adobe Experience Platform e alle autorizzazioni per creare schemi, set di dati e flussi di dati per la raccolta dati. Per ulteriori informazioni, vedere Gestione autorizzazioni.

Configurazione dell’as a Cloud Service di AEM Commerce aem-setup

Per avere un ambiente locale di AEM Commerce as a Cloud Service funzionante con il codice e la configurazione necessari, completa i passaggi seguenti.

Configurazione locale

Segui i passaggi Configurazione locale per avere un ambiente as a Cloud Service AEM Commerce funzionante.

Configurazione del progetto

Segui i passaggi di Archetipo progetto AEM per creare un nuovo progetto AEM Commerce (CIF).

TIP
Nell'esempio seguente, il progetto Commerce dell'AEM è denominato: My Demo Storefront, tuttavia, è possibile scegliere il nome del progetto desiderato.

Progetto Commerce AEM

Crea e distribuisci il progetto Commerce per AEM creato nell’SDK AEM locale eseguendo il seguente comando dalla directory principale del progetto.

$ mvn clean install -PautoInstallSinglePackage

Il sito di commerce My Demo StoreFront distribuito localmente con codice e contenuto predefiniti è simile al seguente:

Sito Commerce predefinito per AEM

Installare le dipendenze dei connettori Peregrine e CIF-AEP

Per raccogliere e inviare i dati dell'evento dalle pagine delle categorie e dei prodotti di questo sito Commerce AEM, installare i pacchetti chiave npm nel modulo ui.frontend del progetto AEM Commerce.

Passare al modulo ui.frontend e installare i pacchetti richiesti eseguendo i seguenti comandi dalla riga di comando.

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
L'argomento --force è obbligatorio a volte perché PWA Studi è restrittivo con le dipendenze dei peer supportate. Di solito, questo non dovrebbe causare alcun problema.

Configura Maven per utilizzare l’argomento --force

Come parte del processo di compilazione Maven, viene attivata l'installazione npm clean (utilizzando npm ci). È necessario anche l'argomento --force.

Passare al file POM radice del progetto pom.xml e individuare il blocco di esecuzione <id>npm ci</id>. Aggiorna il blocco come segue:

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

Cambia il formato di configurazione di Babel

Passa dal formato predefinito del file di configurazione relativo .babelrc al formato babel.config.js. Si tratta di un formato di configurazione a livello di progetto che consente di applicare i plug-in e i predefiniti a node_module con un controllo maggiore.

  1. Passare al modulo ui.frontend ed eliminare il file .babelrc esistente.

  2. Creare un file babel.config.js che utilizza il predefinito 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;
    }
    

Configurare il webpack per l'utilizzo di Babel

Per eseguire la transpilazione dei file JavaScript utilizzando Babel loader (babel-loader) e Webpack, modificare il file webpack.common.js.

Passare al modulo ui.frontend e aggiornare il file webpack.common.js in modo da poter avere la regola seguente all'interno del valore della proprietà module:

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

Configura client Apollo

Il client Apollo viene utilizzato per gestire dati locali e remoti con GraphQL. Memorizza inoltre i risultati delle query GraphQL in una cache locale normalizzata in memoria.

Affinché InMemoryCache funzioni correttamente, è necessario un file possibleTypes.js. Per generare questo file, vedere Generazione automatica di possibleTypes. Inoltre, vedere l'implementazione di riferimento di PWA Studi e un esempio di un file possibleTypes.js.

  1. Passare al modulo ui.frontend e salvare il file come ./src/main/possibleTypes.js

  2. Aggiornare la sezione DefinePlugin del file webpack.common.js in modo da poter sostituire le variabili statiche richieste durante il tempo di compilazione.

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

Inizializzare i componenti core Peregrine e CIF

Per inizializzare i componenti core Peregrine e CIF basati su React, crea la configurazione richiesta e i file JavaScript.

  1. Passare al modulo ui.frontend e creare la cartella seguente: src/main/webpack/components/commerce/App

  2. Crea un file config.js con il seguente contenuto:

    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
    È possibile che tu abbia già familiarità con il file config.js di AEM Guides - CIF Venia Project, ma è necessario apportare alcune modifiche a questo file. Rivedi innanzitutto eventuali commenti di TODO. Quindi, all'interno della proprietà eventsCollector, trovare l'oggetto eventsCollector > aep e aggiornare le proprietà orgId e datastreamId ai valori corretti. Ulteriori informazioni.
  3. Creare un file App.js con il contenuto seguente. Questo file è simile a un tipico file del punto di avvio dell’applicazione React e contiene gli hook React e personalizzati e l’utilizzo di React Context per facilitare l’integrazione 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 esporta il contesto di React che:

    • carica la libreria commerce-events-sdk e commerce-events-collector,
    • li inizializza con una determinata configurazione, ad Experience Platform e/o ACDS
    • si abbona a tutti gli eventi da Peregrine e li inoltra all’SDK degli eventi

    È possibile rivedere i dettagli di implementazione di EventCollectorContext qui.

Creare e distribuire il progetto AEM aggiornato

Per verificare che l'installazione del pacchetto, il codice e le modifiche di configurazione siano corretti, ricompilare e distribuire il progetto Commerce AEM aggiornato utilizzando il comando Maven seguente: $ mvn clean install -PautoInstallSinglePackage.

Configurazione Experience Platform aep-setup

La procedura seguente illustra come ricevere e memorizzare i dati dell’evento provenienti dalle pagine Commerce dell’AEM, ad esempio categoria e prodotto:

AVAILABILITY
Assicurati di far parte dei profili di prodotto corretti in Adobe Experience Platform e Raccolta dati di Adobe Experience Platform. Se necessario, rivolgiti all'amministratore di sistema per creare, aggiornare o assegnare profili di prodotto nell'Admin Console 3}.

Crea schema con gruppo di campi Commerce

Per definire la struttura per i dati dell’evento Commerce, devi creare uno schema Experience Data Model (XDM). Uno schema è un insieme di regole che rappresentano e convalidano la struttura e il formato dei dati.

  1. Nel browser passare alla home page del prodotto Adobe Experience Platform. Esempio: https://experience.adobe.com/#/@YOUR-ORG-NAME/sname:prod/platform/home.

  2. Individua il menu Schemi nella sezione di navigazione a sinistra, fai clic sul pulsante Crea schema nella sezione in alto a destra e seleziona XDM ExperienceEvent.

    Crea schema AEP

  3. Denomina lo schema utilizzando il campo Proprietà schema > Nome visualizzato e aggiungi gruppi di campi utilizzando il pulsante Composizione > Gruppi di campi > Aggiungi.

    Definizione schema AEP

  4. Nella finestra di dialogo Aggiungi gruppi di campi, cerca Commerce, seleziona la casella di controllo Dettagli Commerce e fai clic su Aggiungi gruppi di campi.

    Definizione schema AEP

TIP
Per ulteriori informazioni, vedere le nozioni di base sulla composizione dello schema.

Crea set di dati

Per memorizzare i dati dell’evento, è necessario creare un set di dati conforme alla definizione dello schema. Un set di dati è un costrutto di archiviazione e gestione per una raccolta di dati, in genere una tabella, che contiene uno schema (colonne) e dei campi (righe).

  1. Nel browser passare alla home page del prodotto Adobe Experience Platform. Esempio: https://experience.adobe.com/#/@YOUR-ORG-NAME/sname:prod/platform/home.

  2. Individua il menu Set di dati nella sezione di navigazione a sinistra e fai clic sul pulsante Crea set di dati nella sezione in alto a destra.

    Crea set di dati AEP

  3. Nella nuova pagina, seleziona Crea set di dati dalla scheda schema.

    Opzione schema per creazione set di dati AEP

    Nella nuova pagina, cerca e seleziona lo schema creato nel passaggio precedente, quindi fai clic sul pulsante Successivo.

    Crea set di dati AEP Seleziona schema

  4. Assegna un nome al set di dati utilizzando il campo Configura set di dati > Nome e fai clic sul pulsante Fine.

    Nome set di dati di creazione AEP

TIP
Per ulteriori informazioni, vedere Panoramica sui set di dati.

Crea stream di dati

Completa i passaggi seguenti per creare uno stream di dati nell’Experience Platform.

  1. Nel browser passare alla home page del prodotto Adobe Experience Platform. Esempio: https://experience.adobe.com/#/@YOUR-ORG-NAME/sname:prod/platform/home.

  2. Individua il menu Datastreams nella sezione di navigazione a sinistra e fai clic sul pulsante New Datastream nella sezione in alto a destra.

    AEP Crea flussi di dati

  3. Denomina lo stream di dati utilizzando il campo obbligatorio Name. Nel campo Schema evento, seleziona lo schema creato e fai clic su Salva.

    AEP Definisci flussi di dati

  4. Aprire lo stream di dati creato e fare clic su Aggiungi servizio.

    Servizio aggiunta flussi di dati AEP

  5. Nel campo Servizio, seleziona l'opzione Adobe Experience Platform. Nel campo Set di dati evento, seleziona il nome del set di dati del passaggio precedente e fai clic su Salva.

    Dettagli servizio aggiunta flussi di dati AEP

TIP
Per ulteriori informazioni, vedere Panoramica sullo stream di dati.

Aggiungere valore dello stream di dati nella configurazione AEM Commerce add-aep-values-to-aem

Dopo aver completato la configurazione dell'Experience Platform precedente, dovresti disporre di datastreamId nella barra a sinistra dei dettagli dello stream di dati e di orgId nell'angolo in alto a destra della finestra modale Immagine profilo > Informazioni account > Informazioni utente.

ID flussi di dati AEP

  1. Nel modulo ui.frontend del progetto Commerce AEM, aggiornare il file config.js e in particolare le proprietà dell'oggetto eventsCollector > aep.

  2. Creare e distribuire il progetto Commerce dell’AEM aggiornato

Attiva l'evento addToCart e verifica la raccolta dati event-trigger-verify

I passaggi precedenti completano la configurazione di AEM Commerce e Experience Platform. Ora puoi attivare un evento addToCart e verificare la raccolta dati utilizzando l'estensione Google Chrome Ispettore snowplow e il set di dati Metriche e grafici nell'interfaccia utente del prodotto.

Per attivare l’evento, puoi utilizzare il servizio di creazione AEM o il servizio di pubblicazione dalla configurazione locale. Per questo esempio, utilizza AEM Author effettuando l’accesso al tuo account.

  1. Dalla pagina Sites, seleziona la pagina My Demo StoreFront > us > en e fai clic su Modifica nella barra delle azioni superiore.

  2. Dalla barra delle azioni superiore, fai clic su Visualizza come pubblicato, quindi fai clic su una categoria preferita nell'area di navigazione della vetrina.

  3. Fai clic su una scheda prodotto preferita nella pagina prodotto, quindi seleziona colore, dimensione per abilitare il pulsante Aggiungi al carrello.

  4. Apri l'estensione Snowplow Inspector dal pannello delle estensioni del browser e seleziona Experience Platform Wed SDK nella barra a sinistra.

  5. Torna alla pagina prodotto e fai clic sul pulsante Aggiungi al carrello. In questo modo i dati vengono inviati all’Experience Platform. L'estensione Adobe Experience Platform Debugger mostra i dettagli dell'evento.

    Dati Evento Del Componente Aggiuntivo Del Debugger Di AEP

  6. Nell'interfaccia utente del prodotto di Experience Platform, passa a Set di dati > My Demo StoreFront, nella scheda Attività set di dati. Se Metriche e grafici è abilitato, vengono visualizzate le statistiche dei dati evento.

    Statistiche dei dati del set di dati di Experience Platform

Dettagli di implementazione implementation-details

Il connettore di Experience Platform CIF è basato sulla connessione dati per Adobe Commerce, che fa parte del progetto PWA Studi.

Il progetto PWA Studio consente di creare vetrine di Progressive Web Application (PWA) basate su Adobe Commerce o Magento Open Source. Il progetto contiene anche una libreria di componenti denominata Peregrin per l'aggiunta di logica ai componenti visivi. La libreria Peregrin fornisce anche gli hook React personalizzati utilizzati da Connettore Experience Platform CIF per l'integrazione con Experience Platform senza problemi.

Eventi supportati supported-events

Al momento, sono supportati i seguenti eventi:

Eventi Experience XDM:

  1. Aggiungi al carrello (AEM)
  2. Visualizza pagina (AEM)
  3. Visualizza prodotto (AEM)
  4. Richiesta di ricerca inviata (AEM)
  5. Risposta di ricerca ricevuta (AEM)

Quando Componenti peregrini vengono riutilizzati nel progetto Commerce AEM:

Eventi Experience XDM:

  1. Rimuovi dal carrello
  2. Apri carrello
  3. Visualizza carrello
  4. Acquisto immediato
  5. Avvia estrazione
  6. Completa il checkout

Eventi XDM profilo:

  1. Accedi
  2. Crea account
  3. Modifica account

Risorse aggiuntive additional-resources

Per ulteriori informazioni, consulta le risorse seguenti:

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