Utilisation de la couche de données client Adobe avec les composants principaux

L’objectif de la couche de données client Adobe est de réduire les efforts d’instrumentalisation des sites web en fournissant une méthode normalisée afin d’exposer et d’accéder à tout type de données pour tout script.

La couche de données client Adobe est indépendante de la plate-forme, mais elle est entièrement intégrée aux composants principaux pour l’utilisation avec AEM.

Tout comme les composants principaux, le code de la couche de données client Adobe est disponible sur GitHub avec sa documentation destinée aux développeurs. Ce document donne un aperçu de la façon dont les composants principaux interagissent avec la couche de données ; les détails techniques complets sont disponibles dans la documentation GitHub.

ASTUCE

Pour plus d’informations sur la couche de données client Adobe, reportez-vous aux ressources de son référentiel GitHub.

Pour obtenir des détails techniques sur l’intégration de la couche de données client Adobe avec les composants principaux, voir le fichier DATA_LAYER_INTEGRATION.md dans le référentiel des composants principaux.

Installation et activation

Depuis la version 2.9.0 des composants principaux, la couche de données est distribuée avec les composants principaux sous la forme d’une bibliothèque cliente AEM et aucune installation n’est nécessaire. Tous les projets générés par l’archétype de projets AEM v. 24+ incluent par défaut une couche de données activée.

Pour activer manuellement la couche de données, vous devez créer une configuration contextuelle :

  1. Créez la structure suivante dans le dossier /conf/<mySite>, où <mySite> est le nom du projet de votre site :

    • /conf/<mySite>/sling:configs/com.adobe.cq.wcm.core.components.internal.DataLayerConfig
    • Où chaque nœud a une valeur jcr:primaryType définie sur nt:unstructured.
  2. Ajoutez une propriété booléenne appelée enabled et définissez-la sur true.

    Emplacement de DataLayerConfig dans le site de référence WKND

    Emplacement de DataLayerConfig dans le site de référence WKND

  3. Ajoutez une propriété sling:configRef sur le nœud jcr:content de votre site ci-dessous /content (par exemple, /content/<mySite>/jcr:content) et définissez-la sur /conf/<mySite> par rapport à l’étape précédente.

  4. Une fois activée, vous pouvez vérifier l’activation en chargeant une page du site en dehors de l’éditeur. Inspectez la source de la page. La balise <body> doit contenir un attribut data-cmp-data-layer-enabled.

    <body class="page basicpage" id="page-id" data-cmp-data-layer-enabled>
        <script>
          window.adobeDataLayer = window.adobeDataLayer || [];
          adobeDataLayer.push({
              page: JSON.parse("{\x22page\u002D6c5d4b9fdd\x22:{\x22xdm:language\x22:\x22en\x22,\x22repo:path\x22:\x22\/content\/wknd\/language\u002Dmasters\/en.html\x22,\x22xdm:tags\x22:[],\x22xdm:template\x22:\x22\/conf\/wknd\/settings\/wcm\/templates\/landing\u002Dpage\u002Dtemplate\x22,\x22@type\x22:\x22wknd\/components\/page\x22,\x22dc:description\x22:\x22WKND is a collective of outdoors, music, crafts, adventure sports, and travel enthusiasts that want to share our experiences, connections, and expertise with the world.\x22,\x22dc:title\x22:\x22WKND Adventures and Travel\x22,\x22repo:modifyDate\x22:\x222020\u002D09\u002D29T07:50:13Z\x22}}"),
              event:'cmp:show',
              eventInfo: {
                  path: 'page.page\u002D6c5d4b9fdd'
              }
          });
        </script>
    
  5. Vous pouvez également ouvrir les outils de développement de votre navigateur. Dans la console, l’objet JavaScript adobeDataLayer doit être disponible. Saisissez la commande suivante pour obtenir l’état de la couche de données de votre page actuelle :

    window.adobeDataLayer.getState();
    

Schémas de données des composants principaux

Voici une liste de schémas que les composants principaux utilisent avec la couche de données.

Schéma d’élément de composant/conteneur

Le schéma d’élément de composant/conteneur est utilisé dans les composants suivants :

Le schéma d’élément de composant/conteneur est défini comme suit.

id: {                   // component ID
    @type               // resource type
    repo:modifyDate     // last modified date
    dc:title            // title
    dc:description      // description
    xdm:text            // text
    xdm:linkURL         // link URL
    parentId            // parent component ID
}

L’événement suivant correspond au schéma d’élément de composant/conteneur :

  • cmp:click

Schéma de page

Le schéma de page est utilisé par le composant suivant :

Le schéma de page est défini comme suit.

id: {
    @type
    repo:modifyDate
    dc:title
    dc:description
    xdm:text
    xdm:linkURL
    parentId
    xdm:tags            // page tags
    repo:path           // page path
    xdm:template        // page template
    xdm:language        // page language
}

Un événement cmp:show est déclenché au chargement de la page. Cet événement est distribué à partir du code JavaScript intégré immédiatement au-dessous de la balise d’ouverture <body>, ce qui en fait le premier événement de la file d’attente des événements de la couche de données.

Schéma de conteneur

Le schéma de conteneur est utilisé par les composants suivants :

Le schéma de conteneur est défini comme suit.

id: {
    @type
    repo:modifyDate
    dc:title
    dc:description
    xdm:text
    xdm:linkURL
    parentId
    shownItems          // array of the displayed item IDs
}

Les événements suivants correspondent au schéma de conteneur :

  • cmp:click
  • cmp:show
  • cmp:hide

Schéma d’image

Le schéma d’image est utilisé par le composant suivant :

Le schéma d’image est défini comme suit.

id: {
    @type
    repo:modifyDate
    dc:title
    dc:description
    xdm:text
    xdm:linkURL
    parentId
    image               // asset detail (see below section)
}

L’événement suivant correspond au schéma d’image :

  • cmp:click

Schéma de ressource

Le schéma de ressource est utilisé dans le composant Image.

Le schéma de ressource est défini comme suit.

id: {
    repo:id             // asset UUID
    repo:path           // asset path
    @type               // asset resource type
    xdm:tags            // asset tags
    repo:modifyDate
}

L’événement suivant correspond au schéma de ressource :

  • cmp:click

Événements des composants principaux

Un certain nombre d’événements sont déclenchés par les composants principaux au moyen de la couche de données. La bonne pratique pour interagir avec la couche de données consiste à enregistrer un listener d’événement, puis à effectuer une action en fonction du type d’événement et/ou du composant qui a déclenché l’événement. Il est ainsi possible d’éviter les conditions de concurrence potentielle avec des scripts asynchrones.

Vous trouverez ci-dessous les événements prêts à l’emploi fournis par les composants principaux d’AEM :

  • cmp:click - Lorsque vous cliquez sur un élément cliquable (élément doté d’un attribut data-cmp-clickable), la couche de données déclenche un événement cmp:click.
  • cmp:show et cmp:hide - Manipuler l'accordéon (développer/réduire), le carrousel (boutons Suivant/Précédent) et les composants des onglets (sélection par onglets) provoque le déclenchement des événements cmp:show et cmp:hide, respectivement, par la couche de données. Un événement cmp:show est également distribué au chargement de la page et devrait être le premier.
  • cmp:loaded - Dès que la couche de données est remplie avec les composants principaux sur la page, elle déclenche un événement cmp:loaded.

Événements déclenchés par le composant

Les tableaux suivants répertorient les composants principaux standard qui déclenchent des événements avec ces événements.

Composant Événement(s)
Accordéon cmp:show et cmp:hide
Bouton cmp:click
Chemin de navigation cmp:click
Carrousel cmp:show et cmp:hide
Navigation par langue cmp:click
Navigation cmp:click
Page cmp:show
Onglets cmp:show et cmp:hide
Teaser cmp:click

Infos sur le chemin de l’événement

Chaque événement de la couche de données déclenché par un composant principal d’AEM inclura une charge utile associée à l’objet JSON suivant :

eventInfo: {
    path: '<component-path>'
}

<component-path> est le chemin JSON vers le composant de la couche de données qui a déclenché l’événement. La valeur, disponible dans event.eventInfo.path, est importante, car il est possible de l’utiliser comme paramètre pour adobeDataLayer.getState(<component-path>). Elle sert à récupérer l’état actuel du composant qui a déclenché l’événement, ce qui permet au code personnalisé d’accéder à des données supplémentaires et de les ajouter à la couche de données.

Par exemple :

function logEventObject(event) {
    if(event.hasOwnProperty("eventInfo") && event.eventInfo.hasOwnProperty("path")) {
        var dataObject = window.adobeDataLayer.getState(event.eventInfo.path);
        console.debug("The component that triggered this event: ");
        console.log(dataObject);
    }
}

window.adobeDataLayer = window.adobeDataLayer || [];
window.adobeDataLayer.push(function (dl) {
     dl.addEventListener("cmp:show", logEventObject);
});

Tutoriel

Souhaitez-vous explorer plus en détail la couche de données et les composants principaux ? Consultez ce tutoriel pratique.

ASTUCE

Pour explorer plus avant la flexibilité de la couche de données, passez en revue les options d’intégration, y compris la façon d’activer la couche de données pour vos composants personnalisés.

Sur cette page