Composants principaux AEM-CIF et intégration à Adobe Experience Platform

Dernière mise à jour : 2023-12-06
  • Créé pour :
  • Beginner
    Developer

Les composants principaux Commerce Integration Framework (CIF) fournissent une intégration transparente à Adobe Experience Platform, ce qui permet de transférer les événements de storefront et leurs données à partir d’interactions côté client, telles que l’ajout au panier.

Le projet de Composants principaux AEM CIF fournit une bibliothèque JavaScript appelée Connecteur Adobe Experience Platform pour Adobe Commerce afin de collecter des données d’événement à partir de votre storefront Commerce. Ces données d’événement sont envoyées à Experience Platform, où elles sont utilisées dans d’autres produits Adobe Experience Cloud, tels qu’Adobe Analytics et Adobe Target, pour créer un profil à 360 degrés couvrant un parcours client. En connectant les données de Commerce à d’autres produits dans Adobe Experience Cloud, vous pouvez exécuter des tâches comme analyser le comportement des utilisateurs et utilisatrices sur votre site, effectuer un AB Testing et créer des campagnes personnalisées.

En savoir plus sur la suite de technologies de Collecte de données Experience Platform, qui vous permet de collecter des données d’expérience client à partir de sources côté client.

Envoer des données d’événement addToCart vers Experience Platform

Les étapes suivantes indiquent comment envoyer les données d’événement addToCart des pages produit générées par AEM vers Experience Platform à l’aide du connecteur Experience Platform - CIF. L’extension de navigateur Adobe Experience Platform Debugger vous permet de tester et de passer en revue les données envoyées.

Passer en revue les données d’événement addToCart dans Adobe Experience Platform Debugger

Prérequis

Vous devez utiliser un environnement de développement local pour mener à bien cette démonstration. Cela inclut une instance AEM en cours d’exécution configurée et connectée à une instance Adobe Commerce. Examinez les exigences et les étapes de la configuration d’un développement local avec le SDK AEM as Cloud Service.

Vous devez également accéder à Adobe Experience Platform et disposer des autorisations pour créer le schéma, le jeu de données et les flux de données pour la collecte de données. Pour plus d’informations, consultez la section Gestion des autorisations.

Configurer AEM Commerce as a Cloud Service

Pour bénéficier d’un environnement local AEM Commerce as a Cloud Service fonctionnel avec le code et la configuration nécessaires, procédez comme suit.

Configuration locale

Suivez les étapes de Configuration locale pour disposer d’un environnement AEM Commerce as a Cloud Service fonctionnel.

Configuration du projet

Suivez les étapes de l’Archétype de projet AEM pour créer un projet AEM Commerce (CIF).

CONSEIL

Dans l’exemple suivant, le projet AEM Commerce se nomme My Demo Storefront. Vous pouvez toutefois choisir votre propre nom de projet.

Projet AEM Commerce

Créez et déployez le projet AEM Commerce créé sur le SDK AEM local en exécutant la commande suivante à partir du répertoire racine du projet.

$ mvn clean install -PautoInstallSinglePackage

Le site Commerce My Demo StoreFront localement déployé avec le code et le contenu par défaut ressemble à ce qui suit :

Site AEM Commerce par défaut

Installer des dépendances du connecteur CIF-AEP et de Peregrine

Pour collecter et envoyer les données d’événement à partir des pages de catégorie et de produit de ce site AEM Commerce, vous devez installer les packages npm clés dans le module ui.frontend du projet AEM Commerce.

Accédez au module ui.frontend et installez les packages requis en exécutant les commandes suivantes à partir de la ligne de commande.

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’argument --force est parfois requis, car PWA Studio est restrictif avec les dépendances de pairs prises en charge. En règle générale, cela ne doit pas poser de problème.

Configurer Maven pour utiliser l’argument --force

Dans le cadre du processus de création Maven, l’installation de nettoyage npm (à l’aide de npm ci) est déclenchée. Cela nécessite également l’argument --force.

Accédez au fichier POM racine pom.xml du projet et recherchez le bloc d’exécution <id>npm ci</id>. Mettez à jour le bloc pour qu’il ressemble à ce qui suit :

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

Modifier le format de configuration Babel

Basculez depuis le format par défaut de fichier de configuration relative au fichier .babelrc au format babel.config.js. Il s’agit d’un format de configuration à l’échelle du projet qui permet d’appliquer les modules externes et les paramètres prédéfinis au node_module avec un meilleur contrôle.

  1. Accédez au module ui.frontend et supprimer le fichier .babelrc existant.

  2. Créez un fichier babel.config.js qui utilise le paramètre prédéfini peregrine.

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

Configurer webpack pour l’utilisation de Babel

Pour transférer les fichiers JavaScript à l’aide du chargeur Babel (babel-loader) et de webpack, vous devez modifier le fichier webpack.common.js.

Accédez au module ui.frontend et mettez à jour le fichier webpack.common.js afin que la règle suivante soit incluse dans la valeur de propriété module :

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

Configurer le client Apollo

Le client Apollo est utilisé pour gérer les données locales et distantes avec GraphQL. Il stocke également les résultats des requêtes GraphQL dans un cache local, normalisé et en mémoire.

Pour que InMemoryCache fonctionne efficacement, vous avez besoin d’un fichier possibleTypes.js. Pour générer ce fichier, voir Génération automatique de types possibles. Voir également la section Implémentation de référence PWA Studio et un exemple de fichier possibleTypes.js.

  1. Accédez au module ui.frontend et enregistrez le fichier en tant que ./src/main/possibleTypes.js.

  2. Mettez à jour la section DefinePlugin du fichier webpack.common.js pour remplacer les variables statiques obligatoires pendant la génération.

    const { DefinePlugin } = require('webpack');
    const { POSSIBLE_TYPES } = require('./src/main/possibleTypes');
    
    ...
    
    plugins: [
        ...
        new DefinePlugin({
            'process.env.USE_STORE_CODE_IN_URL': false,
            POSSIBLE_TYPES
        })
    ]
    

Initialiser les composants principaux de Peregrine et CIF

Pour initialiser les composants principaux de CIF et Peregrine basés sur React, créez la configuration et les fichiers JavaScript requis.

  1. Accédez au module ui.frontend et créez le dossier suivant : src/main/webpack/components/commerce/App.

  2. Créez un fichier config.js avec le contenu suivant :

    // 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: {
                commerce: true,
                aep: false,
            }
        }
    };
    
    IMPORTANT

    Bien que vous soyez peut-être déjà familiarisé(e) avec le fichier config.js grâce à AEM Guides - Projet CIF Venia, quelques modifications doivent être apportées à ce fichier. Tout d’abord, passez en revue les commentaires Tâches. Ensuite, à l’intérieur de la propriété eventsCollector, recherchez l’objet eventsCollector > aed et mettez à jour les propriétés orgId et datastreamId avec les valeurs correctes. En savoir plus.

  3. Créez un fichier App.js avec le contenu suivant. Ce fichier ressemble à un fichier de point de départ standard de l’application React et contient des crochets React et personnalisés, ainsi que l’utilisation de contexte React pour faciliter l’intégration d’Experience Platform.

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

    Le EventCollectorContext exporte le contexte React qui :

    • charge la bibliothèque commerce-events-sdk et commerce-events-collector,
    • les initialise avec une configuration donnée pour Experience Platform et/ou ACDS,
    • et s’abonne à tous les événements de Peregrine et les transfère au SDK d’événements.

    Vous pouvez consulter les détails de mise en œuvre du EventCollectorContext ici.

Créez et déployez le projet AEM mis à jour.

Pour vous assurer que les modifications de configuration, de code et d’installation du package ci-dessus sont correctes, recréez et déployez le projet AEM Commerce mis à jour à l’aide de la commande Maven suivante : $ mvn clean install -PautoInstallSinglePackage.

Configurer Experience Platform

Pour recevoir et stocker les données d’événement provenant des pages d’AEM Commerce telles que la catégorie et le produit, effectuez les étapes suivantes :

DISPONIBILITÉ

Assurez-vous que vous faites partie des Profils de produit corrects sous Adobe Experience Platform et Collecte de données Adobe Experience Platform. Si nécessaire, contactez votre administrateur ou administratrice système pour créer, mettre à jour ou attribuer les Profils de produit sous l’Admin Console.

Créer un schéma avec un groupe de champs Commerce

Pour définir la structure des données d’événement de Commerce, vous devez créer un schéma de modèle de données d’expérience (XDM). Un schéma est un ensemble de règles qui représente et valide la structure et le format des données.

  1. Dans le navigateur, accédez à la page d’accueil du produit Adobe Experience Platform. Par exemple, https://experience.adobe.com/#/@YOUR-ORG-NAME/sname:prod/platform/home.

  2. Recherchez le menu Schémas dans la section de navigation de gauche, cliquez sur le bouton Créer un schéma dans la section supérieure droite, puis sélectionnez XDM ExperienceEvent.

    Créer un schéma AEP

  3. Donnez un nom à votre schéma à l’aide du champ Propriétés du schéma > Nom d’affichage et ajoutez des groupes de champs à l’aide du bouton Composition > Groupes de champs > Ajouter.

    Définition d’un schéma AEP

  4. Dans la boîte de dialogue Ajouter des groupes de champs, recherchez Commerce, cochez la case Détails de Commerce, puis cliquez sur Ajouter des groupes de champs.

    Définition d’un schéma AEP

CONSEIL

Consultez la section Principes de base de la composition des schémas pour plus d’informations.

Créer un jeu de données

Pour stocker les données d’événement, vous devez créer un jeu de données conforme à la définition de schéma. Un jeu de données est une structure de stockage et de gestion pour une collecte de données, qui se présente généralement sous la forme d’un tableau comportant un schéma (colonnes) et des champs (lignes).

  1. Dans le navigateur, accédez à la page d’accueil du produit Adobe Experience Platform. Par exemple, https://experience.adobe.com/#/@YOUR-ORG-NAME/sname:prod/platform/home.

  2. Recherchez le menu Jeux de données dans la section de navigation de gauche, puis cliquez sur le bouton Créer un jeu de données dans la section supérieure droite.

    Créer des jeux de données AEP

  3. Sur la nouvelle page, sélectionnez la vignette Créer un jeu de données à partir d’un schéma.

    Option Créer un jeu de données à partir d’un schéma AEP

  • Sur la nouvelle page, recherchez et sélectionnez le schéma que vous avez créé à l’étape précédente, puis cliquez sur le bouton Suivant.

    Sélectionner un schéma pour créer des jeux de données AEP

  1. Nommez votre jeu de données à l’aide du champ Configurer le jeu de données > Nom, puis cliquez sur le bouton Terminer.

    Nom de jeux de données créés AEP

CONSEIL

Consultez la Présentation des jeux de données pour plus d’informations.

Créer un flux de données

Pour créer un flux de données dans Experience Platform, procédez comme suit.

  1. Dans le navigateur, accédez à la page d’accueil du produit Adobe Experience Platform. Par exemple, https://experience.adobe.com/#/@YOUR-ORG-NAME/sname:prod/platform/home.

  2. Recherchez le menu Flux de données dans la section de navigation de gauche, puis cliquez sur le bouton Nouveau flux de données dans la section supérieure droite.

    Créer des flux de données AEP

  3. Nommez votre flux de données à l’aide du champ Nom obligatoire. Sous , Schéma d’événement , sélectionnez le schéma créé et cliquez sur Enregistrer.

    Définir des flux de données AEP

  4. Ouvrez le flux de données créé, puis cliquez sur Ajouter un service.

    Ajouter un service aux flux de données AEP

  5. Sous le champ Service, sélectionnez l’option Adobe Experience Platform. Sous le champ Jeu de données d’événement, sélectionnez le nom du jeu de données de l’étape précédente et cliquez sur Enregistrer.

    Détails d’ajout de service aux flux de données AEP

CONSEIL

Consultez la Présentation des flux de données pour plus d’informations.

Ajouter de la valeur du flux de données dans la configuration AEM Commerce

Une fois que vous avez terminé la configuration d’Experience Platform présentée ci-dessus, datastreamId doit apparaître dans le rail de gauche des détails du flux de données et orgId dans le coin supérieur droit de la fenêtre modale Photo de profil > Informations du compte > Informations utilisateur.

Identifiant de flux de données AEP

  1. Dans le module ui.frontend du projet AEM Commerce, mettez à jour le fichier config.js et, plus précisément, les propriétés de l’objet eventsCollector > aep.

  2. Créez et déployez le projet AEM Commerce mis à jour.

Déclencher l’événement addToCart et vérifier la collecte de données

Les étapes ci-dessus terminent la configuration d’AEM Commerce et d’Experience Platform. Vous pouvez désormais déclencher une addToCart et vérifier la collecte des données à l’aide de l’événement Inspecteur de déploiement de neige et jeu de données Mesures et graphiques dans l’interface utilisateur du produit.

Pour déclencher l’événement, vous pouvez utiliser le service de création ou de publication d’AEM à partir de votre configuration locale. Pour cet exemple, utilisez le service de création d’AEM en vous connectant à votre compte.

  1. Sur la page Sites, sélectionnez la page My Demo StoreFront > us > en et cliquez sur Modifier dans la barre d’action supérieure.

  2. Dans la barre d’actions supérieure, cliquez sur Afficher comme publié(e), puis cliquez sur une catégorie préférée dans la navigation du storefront.

  3. Cliquez sur n’importe quelle carte de produit préférée dans la Page de produit, puis sélectionnez couleur, taille pour activer la variable Ajouter au panier bouton .

  4. Ouvrez le Inspecteur de déploiement de neige dans le panneau d’extension du navigateur et sélectionnez SDK Experience Platform Wed dans le rail de gauche.

  5. Revenez à la Page produit et cliquez sur le bouton Ajouter au panier. Cela envoie les données à Experience Platform. L’extension Adobe Experience Platform Debugger affiche les détails de l’événement.

    Données d’événement d’ajout au panier AEP Debugger

  6. Dans l’interface utilisateur du produit Experience Platform, accédez à Jeux de données > My Demo StoreFront sous l’onglet Activité du jeu de données. Si le bouton (bascule) Mesures et graphiques est activé, les statistiques des données d’événement s’affichent.

    Statistiques des données du jeu de données Experience Platform

Détails d’implémentation

La variable CIF Experience Platform Connector repose sur la fonction Connexion aux données pour Adobe Commerce, qui fait partie de la fonction PWA Studio projet.

Le projet PWA Studio vous permet de créer des storefronts de Progressive Web Application (PWA) alimentés par Adobe Commerce ou Magento Open Source. Le projet contient également une bibliothèque de composants appelée Peregrin pour ajouter une logique aux composants visuels. La variable Bibliothèque de pré-génération fournit également les hooks React personnalisés utilisés par CIF Experience Platform Connector pour une intégration transparente avec Experience Platform.

Événements pris en charge

À ce jour, les événements suivants sont pris en charge :

Événements XDM d’expérience :

  1. Ajouter au panier (AEM)
  2. Afficher la page (AEM)
  3. Afficher le produit (AEM)
  4. Requête de recherche envoyée (AEM)
  5. Réponse de recherche reçue (AEM)

Quand les composants Peregrine sont réutilisés dans le projet AEM Commerce :

Événements XDM d’expérience :

  1. Supprimer du panier
  2. Ouvrir le panier
  3. Afficher le panier
  4. Achat instantané
  5. Commencer le passage en caisse
  6. Terminer le passage en caisse

Événements XDM de profil :

  1. Se connecter
  2. Créer un compte
  3. Modifier le compte

Ressources supplémentaires

Pour plus d’informations, consultez les ressources suivantes :

Sur cette page