Componentes principais do AEM-CIF e integração com o Adobe Experience Platform aem-cif-aep-integration

Os componentes principais do Commerce integration framework (CIF) fornecem integração perfeita com o Adobe Experience Platform para encaminhar eventos de vitrine e seus dados de interações do lado do cliente, como adicionar ao carrinho.

O projeto Componentes principais do AEM CIF fornece uma biblioteca do JavaScript chamada conector do Adobe Experience Platform para o Adobe Commerce para coletar dados do evento da loja da Commerce. Esses dados do evento são enviados para a Experience Platform, onde são usados em outros produtos da Adobe Experience Cloud, como o Adobe Analytics e o Adobe Target, para criar um perfil de 360 graus que cobre uma jornada do cliente. Conectando os dados do Commerce a outros produtos na Adobe Experience Cloud, você pode executar tarefas como analisar o comportamento do usuário em seu site, executar testes AB e criar campanhas personalizadas.

Saiba mais sobre o conjunto de tecnologias da Coleção de dados da Experience Platform que permite coletar dados de experiência do cliente de fontes do lado do cliente.

Enviar dados do evento addToCart para o Experience Platform send-addtocart-to-aep

As etapas a seguir mostram como enviar os dados do evento addToCart de páginas de produto renderizadas pela AEM para a Experience Platform usando o Conector CIF - Experience Platform. Usando a extensão do navegador Adobe Experience Platform Debugger, você pode testar e revisar os dados enviados.

Revisar dados do evento addToCart no Adobe Experience Platform Debugger

Pré-requisitos prerequisites

Use um ambiente de desenvolvimento local para concluir esta demonstração. Isso inclui uma instância do AEM em execução configurada e conectada a uma instância do Adobe Commerce. Revise os requisitos e as etapas para configurar o desenvolvimento local com o AEM as a Cloud Service SDK.

Você também precisa de acesso ao Adobe Experience Platform e de permissões para criar o esquema, o conjunto de dados e as sequências de dados para a coleta de dados. Para obter mais informações, consulte Gerenciamento de permissões.

Configuração do AEM Commerce as a Cloud Service aem-setup

Para ter um ambiente local de trabalho do AEM Commerce as a Cloud Service com o código e a configuração necessários, conclua as etapas a seguir.

Configuração local

Siga as etapas da Configuração Local para ter um ambiente de trabalho do AEM Commerce as a Cloud Service.

Configuração do projeto

Siga as etapas do Arquétipo de projeto do AEM para criar um novo projeto do AEM Commerce (CIF).

TIP
No exemplo a seguir, o projeto do AEM Commerce é nomeado como: My Demo Storefront, entretanto, você pode escolher seu próprio nome de projeto.

Projeto do AEM Commerce

Crie e implante o projeto AEM Commerce criado no AEM SDK local executando o seguinte comando no diretório raiz do projeto.

$ mvn clean install -PautoInstallSinglePackage

O site de comércio My Demo StoreFront implantado localmente com código e conteúdo padrão é semelhante ao seguinte:

Site Padrão do AEM Commerce

Instalar dependências do conector Peregrine e CIF-AEP

Para coletar e enviar os dados do evento das páginas de categoria e produto deste site do AEM Commerce, instale os pacotes de chaves npm no módulo ui.frontend do projeto do AEM Commerce.

Navegue até o módulo ui.frontend e instale os pacotes necessários executando os seguintes comandos na linha de 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
O argumento --force às vezes é necessário, pois PWA Studio é restritivo com as dependências pares com suporte. Normalmente, isso não deve causar problemas.

Configurar Maven para usar o argumento --force

Como parte do processo de compilação do Maven, a instalação limpa do npm (usando npm ci) é acionada. Isso também requer o argumento --force.

Navegue até o arquivo POM raiz do projeto pom.xml e localize o bloco de execução <id>npm ci</id>. Atualize o bloco para que tenha a seguinte aparência:

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

Alterar formato de configuração do Babel

Alternar do formato de arquivo de configuração relativo de arquivo padrão .babelrc para o formato babel.config.js. Este é um formato de configuração para todo o projeto e permite que plug-ins e predefinições sejam aplicados ao node_module com maior controle.

  1. Navegue até o módulo ui.frontend e exclua o arquivo .babelrc existente.

  2. Crie um arquivo babel.config.js que use a predefinição 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;
    }
    

Configurar o webpack para usar o Babel

Para transcompilar os arquivos JavaScript usando o carregador Babel (babel-loader) e o webpack, edite o arquivo webpack.common.js.

Navegue até o módulo ui.frontend e atualize o arquivo webpack.common.js para que você possa ter a seguinte regra dentro do valor da propriedade module:

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

Configurar cliente Apollo

O Cliente Apollo é usado para gerenciar dados locais e remotos com o GraphQL. Ele também armazena os resultados de consultas do GraphQL em um cache local normalizado na memória.

Para que InMemoryCache funcione efetivamente, você precisa de um arquivo possibleTypes.js. Para gerar este arquivo, consulte Gerando possibleTypes automaticamente.

Além disso, consulte a implementação de referência do PWA Studio e um exemplo de um arquivo possibleTypes.js.

  1. Navegue até o módulo ui.frontend e salve o arquivo como ./src/main/possibleTypes.js

  2. Atualize a seção webpack.common.js do arquivo DefinePlugin para que você possa substituir as variáveis estáticas necessárias durante o tempo de compilação.

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

Inicializar os componentes principais do Peregrine e do CIF

Para inicializar os componentes principais do React-based Peregrine e do CIF, crie os arquivos de configuração e JavaScript necessários.

  1. Navegue até o módulo ui.frontend e crie a seguinte pasta: src/main/webpack/components/commerce/App

  2. Criar um arquivo config.js com o seguinte conteúdo:

    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
    Embora você já esteja familiarizado com o arquivo config.js do AEM Guides - Projeto CIF Venia, há algumas alterações que você deve fazer nesse arquivo. Primeiro, revise quaisquer comentários de TODO. Em seguida, dentro da propriedade eventsCollector, localize o objeto eventsCollector > aep e atualize as propriedades orgId e datastreamId para os valores corretos. Saiba mais.
  3. Crie um arquivo App.js com o conteúdo a seguir. Esse arquivo se parece com um arquivo de ponto de partida típico do aplicativo React e contém ganchos React e personalizados e o uso de Contexto React para facilitar a integração com o 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
        );
    };
    

    O EventCollectorContext exporta o Contexto do React que:

    • carrega a biblioteca commerce-events-sdk e commerce-events-collector,
    • inicializa com uma determinada configuração para o Experience Platform e/ou ACDS
    • assina todos os eventos de Peregrine e os encaminha para a SDK de eventos

    Você pode revisar os detalhes de implementação de EventCollectorContext. Consulte aem-core-CIF-components no GitHub.

Criar e implantar o projeto do AEM atualizado build-and-deploy

Para garantir que as alterações de instalação, código e configuração do pacote acima estejam corretas, recrie e implante o projeto atualizado do AEM Commerce usando o seguinte comando Maven: $ mvn clean install -PautoInstallSinglePackage.

Configuração do Experience Platform aep-setup

Para receber e armazenar os dados do evento provenientes das páginas do Commerce do AEM, como categoria e produto, conclua as seguintes etapas:

AVAILABILITY
Verifique se você faz parte dos Perfis de produto corretos em Adobe Experience Platform e Coleção de dados da Adobe Experience Platform. Se necessário, peça ao administrador do sistema para criar, atualizar ou atribuir Perfis de Produto no Admin Console.

Criar esquema com o grupo de campos Commerce create-schema

Para definir a estrutura para dados de evento de comércio, você deve criar um esquema do Experience Data Model (XDM). Um esquema é um conjunto de regras que representam e validam a estrutura e o formato dos dados.

  1. No navegador, navegue até a página inicial do produto Adobe Experience Platform. Por exemplo, https://experience.adobe.com/#/@YOUR-ORG-NAME/sname:prod/platform/home.

  2. Localize o menu Esquemas na seção de navegação esquerda, clique no botão Criar Esquema na seção superior direita e selecione XDM ExperienceEvent.

    Criar Esquema do AEP

  3. Nomeie seu esquema usando o campo Propriedades do esquema > Nome de exibição e adicione grupos de campos usando o botão Composição > Grupos de campos > Adicionar.

    Definição de Esquema do AEP

  4. Na caixa de diálogo Adicionar grupos de campos, procure Commerce, marque a caixa de seleção Detalhes do Commerce e clique em Adicionar grupos de campos.

    Definição de Esquema do AEP

TIP
Consulte as Noções básicas sobre a composição de esquema para obter mais informações.

Criar conjunto de dados create-dataset

Para armazenar os dados do evento, você deve criar um Conjunto de dados que esteja em conformidade com a definição do esquema. Um conjunto de dados é uma construção de armazenamento e gerenciamento para uma coleção de dados — normalmente uma tabela — que contém um esquema (colunas) e campos (linhas).

  1. No navegador, navegue até a página inicial do produto Adobe Experience Platform. Por exemplo, https://experience.adobe.com/#/@YOUR-ORG-NAME/sname:prod/platform/home.

  2. Localize o menu Conjuntos de dados na seção de navegação esquerda e clique no botão Criar conjunto de dados na seção superior direita.

    Criar Conjuntos de Dados do AEP

  3. Na nova página, selecione Criar conjunto de dados do cartão de esquema.

    Opção Criar Esquema De Conjuntos De Dados Do AEP

    Na nova página, pesquise e selecione o esquema criado na etapa anterior e clique no botão Avançar.

    Criar Conjunto de Dados AEP: Selecionar Esquema

  4. Nomeie seu Conjunto de Dados usando o campo Configurar conjunto de dados > Nome e clique no botão Concluir.

    Nome de Criação de Conjuntos de Dados do AEP

TIP
Consulte a Visão geral dos conjuntos de dados para obter mais informações.

Criar sequência de dados create-datastream

Conclua as etapas a seguir para criar uma sequência de dados na Experience Platform.

  1. No navegador, navegue até a página inicial do produto Adobe Experience Platform. Por exemplo, https://experience.adobe.com/#/@YOUR-ORG-NAME/sname:prod/platform/home.

  2. Localize o menu Datastreams na seção de navegação esquerda e clique no botão Novo Datastream na seção superior direita.

    Criar Datastreams do AEP

  3. Nomeie sua Sequência de Dados usando o campo obrigatório Nome. No campo Esquema de evento, selecione o esquema criado e clique em Salvar.

    Definir Datastreams da AEP

  4. Abra a Sequência de Dados criada e clique em Adicionar Serviço.

    Serviço de Adição de Sequências de Dados do AEP

  5. No campo Serviço, selecione a opção Adobe Experience Platform. No campo Conjunto de Dados do Evento, selecione o nome do conjunto de dados na etapa anterior e clique em Salvar.

    Detalhes de Adição de Serviços às Sequências de Dados do AEP

TIP
Consulte a Visão geral da sequência de dados para obter mais informações.

Adicionar valor de sequência de dados à configuração do AEM Commerce add-aep-values-to-aem

Após concluir a configuração do Experience Platform acima, você deve ter datastreamId no painel esquerdo dos detalhes da sequência de dados e orgId no canto superior direito do modal Imagem de perfil > Informações da conta > Informações do usuário.

ID de Fluxos de Dados do AEP

  1. No módulo ui.frontend do projeto AEM Commerce, atualize o arquivo config.js e especificamente as propriedades do objeto eventsCollector > aep.

  2. Criar e implantar o projeto atualizado do AEM Commerce

Acione o evento addToCart e verifique a coleta de dados event-trigger-verify

As etapas acima concluem a configuração do AEM Commerce e do Experience Platform. Agora você pode acionar um evento addToCart e verificar a coleta de dados usando a extensão do Google Chrome Inspetor do Snowplow e a opção Métricas e gráficos do conjunto de dados na interface do usuário do produto.

Para acionar o evento, você pode usar o autor do AEM ou o serviço de publicação da configuração local. Neste exemplo, use o AEM author para fazer logon em sua conta.

  1. Na página Sites, selecione a página My Demo StoreFront > br > en e clique em Editar na barra de ações superior.

  2. Na barra de ações superior, clique em Exibir como Publicado e, em seguida, clique em qualquer categoria preferencial na navegação da loja.

  3. Clique em qualquer cartão de produto preferencial na Página de Produto e selecione cor, tamanho para habilitar o botão Adicionar ao Carrinho.

  4. Abra a extensão Inspetor do Snowplow no painel de extensão do navegador e selecione Experience Platform Wed SDK no painel esquerdo.

  5. Retorne à Página do Produto e clique no botão Adicionar ao Carrinho. Isso envia dados para a Experience Platform. A extensão Adobe Experience Platform Debugger mostra os detalhes do evento.

    Dados De Evento De Adição Ao Carrinho Do AEP Debugger

  6. Na interface do usuário do produto Experience Platform, navegue até Conjuntos de dados > My Demo StoreFront, na guia Atividade do conjunto de dados. Se Métricas e gráficos estiverem habilitados, as estatísticas de dados de evento serão exibidas.

    Estatísticas de Dados do Conjunto de Dados Experience Platform

Detalhes da implementação implementation-details

O CIF Experience Platform Connector foi criado sobre a Conexão de Dados para o Adobe Commerce, que faz parte do projeto PWA Studio.

O projeto do PWA Studio permite criar vitrines do Progressive Web Application (PWA) alimentadas pela Adobe Commerce ou Magento Open Source. O projeto também contém uma biblioteca de componentes chamada Peregrin para adicionar lógica aos componentes visuais. A biblioteca Peregrin também fornece os ganchos React personalizados usados pelo CIF Experience Platform Connector para integrar-se perfeitamente ao Experience Platform.

Eventos suportados supported-events

A partir de agora, os seguintes eventos serão compatíveis:

Experiência de Eventos XDM :

  1. Adicionar ao carrinho (AEM)
  2. Página Exibir (AEM)
  3. Exibir produto (AEM)
  4. Solicitação de pesquisa enviada (AEM)
  5. Resposta de pesquisa recebida (AEM)

Quando Componentes Peregrine são reutilizados no projeto do AEM Commerce:

Experiência de Eventos XDM :

  1. Remover do carrinho
  2. Abrir carrinho
  3. Exibir carrinho
  4. Compra instantânea
  5. Iniciar check-out
  6. Concluir check-out

Eventos XDM de Perfil :

  1. Fazer logon
  2. Criar conta
  3. Editar conta

Recursos adicionais additional-resources

Para obter mais informações, consulte os seguintes recursos:

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