Documentation Experience Platform Guide du SDK web

Journalisation côté client pour les données A4T dans Experience Platform Web SDK

Last update: Mon May 05 2025 00:00:00 GMT+0000 (Coordinated Universal Time)

Rubriques :

Créé pour :

Développeur

Vue d’ensemble overview

Adobe Experience Platform Web SDK vous permet de collecter des données Adobe Analytics for Target (A4T) côté client de votre application web.

La journalisation côté client signifie que les données Target pertinentes sont renvoyées côté client, ce qui vous permet de les collecter et de les partager avec Analytics. Cette option doit être activée si vous envisagez d’envoyer manuellement des données à Analytics à l’aide de l’API Data Insertion.

NOTE

Une méthode pour effectuer cette opération à l’aide de AppMeasurement.js est actuellement en cours de développement et sera disponible prochainement.

Ce document décrit les étapes de configuration de la journalisation A4T côté client pour le SDK web et fournit quelques exemples d’implémentation pour les cas d’utilisation courants.

Conditions préalables prerequisites

Ce tutoriel suppose que vous connaissez les concepts et processus fondamentaux relatifs à l’utilisation de Web SDK à des fins de personnalisation. Veuillez consulter la documentation suivante si vous avez besoin d’une introduction :

Configurer la journalisation côté client Analytics set-up-client-side-logging

Les sous-sections suivantes décrivent comment activer la journalisation côté client Analytics pour votre implémentation de Web SDK.

Activer la journalisation côté client d’Analytics enable-analytics-client-side-logging

Pour que la journalisation côté client d’Analytics soit activée pour votre implémentation, vous devez désactiver la configuration Adobe Analytics dans votre flux de données.

Configuration du flux de données Analytics désactivée

Récupérer des données A4T du SDK et les envoyer à Analytics a4t-to-analytics

Pour que cette méthode de création de rapports fonctionne correctement, vous devez envoyer les données liées au A4T récupérées à partir de la commande sendEvent dans l’accès Analytics.

Lorsque Target Edge calcule une réponse aux propositions, il vérifie si la journalisation côté client Analytics est activée (c’est-à-dire si Analytics est désactivé dans votre flux de données). Si la journalisation côté client est activée, le système ajoute un jeton Analytics à chaque proposition dans la réponse.

Le flux ressemble à ceci :

Flux de journalisation côté client

Voici un exemple de réponse interact lorsque la journalisation côté client Analytics est activée. Si la proposition concerne une activité qui génère des rapports Analytics, elle possède une propriété scopeDetails.characteristics.analyticsToken.

{
  "requestId": "1234",
  "handle": [
    {
      "payload": [
        {
          "id": "AT:eyJhY3Rpdml0eUlkIjoiNDM0Njg5IiwiZXhwZXJpZW5jZUlkIjoiMCJ9",
          "scope": "a4t-test",
          "scopeDetails": {
            "decisionProvider": "TGT",
            "activity": {
              "id": "434689"
            },
            "experience": {
              "id": "0"
            },
            "strategies": [
              {
                "algorithmID": "0",
                "trafficType": "0"
              }
            ],
            "characteristics": {
              "eventToken": "2lTS5KA6gj4JuSjOdhqUhGqipfsIHvVzTQxHolz2IpTMromRrB5ztP5VMxjHbs7c6qPG9UF4rvQTJZniWgqbOw==",
              "analyticsToken": "434689:0:0|2,434689:0:0|1"
            }
          },
          "items": [
            {
              "id": "1184844",
              "schema": "https://ns.adobe.com/personalization/html-content-item",
              "meta": {
                "geo.state": "bucuresti",
                "activity.id": "434689",
                "experience.id": "0",
                "activity.name": "a4t test form based activity",
                "offer.id": "1184844",
                "profile.tntId": "04608610399599289452943468926942466370-pybgfJ"
              },
              "data": {
                "id": "1184844",
                "format": "text/html",
                "content": "<div> analytics impressions </div>"
              }
            }
          ]
        },
        {
          "id": "AT:eyJhY3Rpdml0eUlkIjoiNDM0Njg5IiwiZXhwZXJpZW5jZUlkIjoiMCJ9",
          "scope": "a4t-test",
          "scopeDetails": {
            "decisionProvider": "TGT",
            "activity": {
              "id": "434689"
            },
            "characteristics": {
              "eventToken": "E0gb6q1+WyFW3FMbbQJmrg==",
              "analyticsToken": "434689:0:0|32767"
            }
          },
          "items": [
            {
              "id": "434689",
              "schema": "https://ns.adobe.com/personalization/measurement",
              "data": {
                "type": "click",
                "format": "application/vnd.adobe.target.metric"
              }
            }
          ]
        }
      ],
      "type": "personalization:decisions",
      "eventIndex": 0
    }
  ]
}

Les propositions des activités du compositeur d’expérience d’après les formulaires peuvent contenir du contenu et des éléments de mesure de clic sous la même proposition. Ainsi, au lieu d’avoir un seul jeton d’analyse pour l’affichage du contenu dans scopeDetails.characteristics.analyticsToken propriété , ceux-ci peuvent avoir à la fois un jeton d’affichage et un jeton d’analyse de clic spécifiés dans les propriétés scopeDetails.characteristics.analyticsDisplayToken et scopeDetails.characteristics.analyticsClickToken, en conséquence.

{
  "requestId": "1234",
  "handle": [
    {
      "payload": [
        {
          "id": "AT:eyJhY3Rpdml0eUlkIjoiNDM0Njg5IiwiZXhwZXJpZW5jZUlkIjoiMCJ9",
          "scope": "a4t-test",
          "scopeDetails": {
            "decisionProvider": "TGT",
            "activity": {
              "id": "434689"
            },
            "experience": {
              "id": "0"
            },
            "strategies": [
              {
                "algorithmID": "0",
                "trafficType": "0"
              }
            ],
            "characteristics": {
               "displayToken": "2lTS5KA6gj4JuSjOdhqUhGqipfsIHvVzTQxHolz2IpTMromRrB5ztP5VMxjHbs7c6qPG9UF4rvQTJZniWgqbOw==",
               "clickToken": "E0gb6q1+WyFW3FMbbQJmrg==",
               "analyticsDisplayToken": "434689:0:0|2,434689:0:0|1",
               "analyticsClickToken": "434689:0:0|32767"
            }
          },
          "items": [
            {
              "id": "1184844",
              "schema": "https://ns.adobe.com/personalization/html-content-item",
              "meta": {
                "geo.state": "bucuresti",
                "activity.id": "434689",
                "experience.id": "0",
                "activity.name": "a4t test form based activity",
                "offer.id": "1184844",
                "profile.tntId": "04608610399599289452943468926942466370-pybgfJ"
              },
              "data": {
                "id": "1184844",
                "format": "text/html",
                "content": "<div> analytics impressions </div>"
              }
            },
            {
              "id": "434689",
              "schema": "https://ns.adobe.com/personalization/measurement",
              "data": {
                "type": "click",
                "format": "application/vnd.adobe.target.metric"
              }
            }
          ]
        }
      ],
      "type": "personalization:decisions",
      "eventIndex": 0
    }
  ]
}

Toutes les valeurs de scopeDetails.characteristics.analyticsToken, ainsi que scopeDetails.characteristics.analyticsDisplayToken (pour le contenu affiché) et scopeDetails.characteristics.analyticsClickToken (pour les mesures de clics) sont les payloads A4T qui doivent être collectées et incluses en tant que balise tnta dans l’appel API Data Insertion.

IMPORTANT

Les propriétés analyticsToken, analyticsDisplayToken et analyticsClickToken peuvent contenir plusieurs jetons, concaténés sous la forme d’une seule chaîne délimitée par des virgules.

Dans les exemples d’implémentation fournis dans la section suivante, plusieurs jetons Analytics sont collectés de manière itérative. Pour concaténer un tableau de jetons Analytics, utilisez une fonction similaire à celle-ci :

code language-javascript

code language-javascript
`var concatenateAnalyticsPayloads = function concatenateAnalyticsPayloads(analyticsPayloads) { if (analyticsPayloads.size > 1) { return [].concat(analyticsPayloads).join(','); } return [].concat(analyticsPayloads).join(); };`

var concatenateAnalyticsPayloads = function concatenateAnalyticsPayloads(analyticsPayloads) {
   if (analyticsPayloads.size > 1) {
       return [].concat(analyticsPayloads).join(',');
   }
   return [].concat(analyticsPayloads).join();
};

Exemples d’implémentation implementation-examples

Les sous-sections suivantes montrent comment implémenter la journalisation côté client d’Analytics pour les cas d’utilisation courants.

Activités du compositeur d’expérience d’après les formulaires form-based-composer

Vous pouvez utiliser le SDK Web pour contrôler l’exécution des propositions à partir des activités du Compositeur d’expérience d’Adobe Target basé sur les formulaires.

Lorsque vous demandez des propositions pour une portée de décision spécifique, la proposition renvoyée contient son jeton Analytics approprié. Il est recommandé d’enchaîner la commande sendEvent d’Experience Platform Web SDK et d’effectuer une itération sur les propositions renvoyées pour les exécuter tout en collectant les jetons Analytics.

Vous pouvez déclencher une commande sendEvent pour une portée d’activité de compositeur d’expérience d’après les formulaires comme suit :

alloy("sendEvent", {
    "decisionScopes": ["a4t-test"],
    "xdm": {
      "web": {
        "webPageDetails": {
          "name": "Home Page"
        }
      }
    }
  }
).then(function(results) {
  for (var i = 0; i < results.propositions.length; i++) {
    //Execute the propositions and collect the Analytics payload
  }
});

À partir de là, vous devez implémenter le code pour exécuter les propositions et créer une payload qui sera envoyée à Analytics. Voici un exemple de ce que results.propositions peut contenir :

[
  {
    "id": "AT:eyJhY3Rpdml0eUlkIjoiNDM0Njg5IiwiZXhwZXJpZW5jZUlkIjoiMCJ9",
    "scope": "a4t-test",
    "scopeDetails": {
      "decisionProvider": "TGT",
      "activity": {
        "id": "434689"
      },
      "experience": {
        "id": "0"
      },
      "strategies": [
        {
          "algorithmID": "0",
          "trafficType": "0"
        }
      ],
      "characteristics": {
        "eventToken": "2lTS5KA6gj4JuSjOdhqUhGqipfsIHvVzTQxHolz2IpTMromRrB5ztP5VMxjHbs7c6qPG9UF4rvQTJZniWgqbOw==",
        "analyticsToken": "434689:0:0|2,434689:0:0|1"
      }
    },
    "items": [
      {
        "id": "1184844",
        "schema": "https://ns.adobe.com/personalization/html-content-item",
        "meta": {
          "geo.state": "bucuresti",
          "activity.id": "434689",
          "experience.id": "0",
          "activity.name": "a4t test form based activity",
          "offer.id": "1184844",
          "profile.tntId": "04608610399599289452943468926942466370-pybgfJ"
        },
        "data": {
          "id": "1184844",
          "format": "text/html",
          "content": "<div> analytics impressions </div>"
        }
      }
    ]
  },
  {
    "id": "AT:eyJhY3Rpdml0eUlkIjoiNDM0Njg5IiwiZXhwZXJpZW5jZUlkIjoiMCJ9",
    "scope": "a4t-test",
    "scopeDetails": {
      "decisionProvider": "TGT",
      "activity": {
        "id": "434689"
      },
      "characteristics": {
        "eventToken": "E0gb6q1+WyFW3FMbbQJmrg==",
        "analyticsToken": "434689:0:0|32767"
      }
    },
    "items": [
      {
        "id": "434689",
        "schema": "https://ns.adobe.com/personalization/measurement",
        "data": {
          "type": "click",
          "format": "application/vnd.adobe.target.metric"
        }
      }
    ]
  },
  {
    "id": "AT:eyJhY3Rpdml0eUlkIjoiNDM0Njg5IiwiZXhwZXJpZW5jZUlkIjoiMCJ9",
    "scope": "a4t-test",
    "scopeDetails": {
      "decisionProvider": "TGT",
      "activity": {
        "id": "434688"
      },
      "experience": {
        "id": "0"
      },
      "strategies": [
        {
          "algorithmID": "0",
          "trafficType": "0"
        }
      ],
      "characteristics": {
          "displayToken": "91TS5KA6gj4JuSjOdhqUhGqipfsIHvVzTQxHolz2IpTMromRrB5ztP5VMxjHbs7c6qPG9UF4rvQTJZniWgqgEt==",
          "clickToken": "Tagb6q1+WyFW3FMbbQJrtg==",
          "analyticsDisplayTokens": "434688:0:0|2,434688:0:0|1",
          "analyticsClickTokens": "434688:0:0|32767"
        }
      }
    },
    "items": [
      {
        "id": "1184845",
        "schema": "https://ns.adobe.com/personalization/html-content-item",
        "meta": {
          "geo.state": "bucuresti",
          "activity.id": "434688",
          "experience.id": "0",
          "activity.name": "a4t test form based activity 1",
          "offer.id": "1184845"
        },
        "data": {
          "id": "1184845",
          "format": "text/html",
          "content": "<div> analytics impressions 1</div>"
        }
      },
      {
        "id": "434688",
        "schema": "https://ns.adobe.com/personalization/measurement",
        "data": {
          "type": "click",
          "format": "application/vnd.adobe.target.metric"
        }
      }
    ]
  }
]

Pour extraire le jeton Analytics d’une proposition avec des éléments de contenu, vous pouvez implémenter une fonction similaire à ce qui suit :

function getDisplayAnalyticsPayload(proposition) {
  if (!proposition || !proposition.scopeDetails || !proposition.scopeDetails.characteristics) {
    return;
  }
  var characteristics = proposition.scopeDetails.characteristics;
  if (characteristics.analyticsDisplayToken) {
    return characteristics.analyticsDisplayToken;
  }
  return characteristics.analyticsToken;
}

Une proposition peut comporter différents types d’éléments, comme indiqué par la propriété schema de l’élément en question. Quatre schémas d’élément de proposition sont pris en charge pour les activités du compositeur d’expérience d’après les formulaires :

var HTML_SCHEMA = "https://ns.adobe.com/personalization/html-content-item";
var MEASUREMENT_SCHEMA = "https://ns.adobe.com/personalization/measurement";
var JSON_SCHEMA = "https://ns.adobe.com/personalization/json-content-item";
var REDIRECT_SCHEMA = "https://ns.adobe.com/personalization/redirect-item";

HTML_SCHEMA et JSON_SCHEMA sont les schémas qui reflètent le type de l’offre, tandis que MEASUREMENT_SCHEMA reflète les mesures qui doivent être jointes à un élément DOM.

Les payloads Analytics pour les mesures de clics doivent être collectées et envoyées à Analytics séparément des éléments de contenu, au moment où le visiteur clique réellement sur le contenu précédemment affiché.

La fonction d’assistance suivante permettant d’obtenir les payloads A4T des mesures de clic sera pratique dans ce cas :

function getClickAnalyticsPayload(proposition) {
  if (!proposition || !proposition.scopeDetails || !proposition.scopeDetails.characteristics) {
    return;
  }
  var characteristics = proposition.scopeDetails.characteristics;
  if (characteristics.analyticsClickToken) {
    return characteristics.analyticsClickToken;
  }
  return characteristics.analyticsToken;
}

Résumé de la mise en œuvre implementation-summary

En résumé, les étapes suivantes doivent être exécutées lors de l’application des activités du compositeur d’expérience d’après les formulaires avec Experience Platform Web SDK :

envoyer un événement qui récupère les offres d’activité du compositeur d’expérience d’après les formulaires ;
appliquer les modifications du contenu à la page ;
Envoyer l’événement de notification decisioning.propositionDisplay ;
collecter les jetons d’affichage Analytics à partir de la réponse SDK et créer une payload pour l’accès Analytics ;
Envoyer la payload à Analytics à l’aide de l’API Data Insertion
Si des mesures de clic existent dans les propositions diffusées, les écouteurs de clic doivent être configurés de sorte que lorsqu’un clic est effectué, il envoie l’événement de notification decisioning.propositionInteract. Le gestionnaire de onBeforeEventSend doit être configuré de sorte que, lors de l’interception d’événements decisioning.propositionInteract, les actions suivantes se produisent :
1. Collecte des jetons d’analyse Click depuis xdm._experience.decisioning.propositions
2. Envoi de l’accès Click Analytics avec la payload Analytics collectée via API Data Insertion ;

alloy("sendEvent", {
    "decisionScopes": ["a4t-test"],
    "xdm": {
      "web": {
        "webPageDetails": {
          "name": "Home Page"
        }
      }
    }
  }
).then(function(results) {
  var analyticsPayload = new Set();
  results.propositions.forEach(function (proposition) {
    proposition.items.forEach(function (item) {
      if (item.schema === HTML_SCHEMA) {
        // 1. Apply offer
        // 2. Collect executed propositions and send the decisioning.propositionDisplay notification event
        // 3. Collect the display Analytics tokens
      }
      if (item.schema === MEASUREMENT_SCHEMA) {
        // Setup click listener, so that when clicked:
        // 1. Collect clicked propositions and send the decisioning.propositionInteract notification event
        // Note: onBeforeEventSend handler should be configured, so that when intercepting decisioning.propositionInteract events:
        //   1. Collect the click Analytics tokens from xdm._experience.decisioning.propositions
        //   2. Send the click Analytics hit with the collected Analytics payload via Data Insertion API
      }
    });
  });
  // Send the page view Analytics hit with the collected display Analytics payload via Data Insertion API
});

Activités du compositeur d’expérience visuelle visual-experience-composer-acitivties

Le SDK Web vous permet de gérer les offres qui ont été créées à l’aide du Compositeur d’expérience visuelle (VEC).

NOTE

Les étapes de mise en œuvre de ce cas pratique sont très similaires aux étapes des activités du compositeur d’expérience d’après les formulaires. Veuillez consulter la section précédente pour plus de détails.

Lorsque le rendu automatique est activé, vous pouvez collecter les jetons Analytics à partir des propositions qui ont été exécutées sur la page. Il est recommandé d’enchaîner la commande sendEvent d’Experience Platform Web SDK et d’effectuer une itération sur les propositions renvoyées pour filtrer celles que Web SDK a tenté de rendre.

Exemple

alloy("sendEvent", {
    "renderDecisions": true,
    "xdm": {
      "web": {
        "webPageDetails": {
          "name": "Home Page"
        }
      }
    }
  }
).then(function (results) {
  var analyticsPayloads = new Set();

  for (var i = 0; i < results.propositions.length; i++) {

    var proposition = propositions[i];
    var renderAttempted = proposition.renderAttempted;

    if (renderAttempted === true) {
      var analyticsPayload = getDisplayAnalyticsPayload(proposition);

      if (analyticsPayload !== undefined) {
        analyticsPayloads.add(analyticsPayload);
      }
    }
  }
  var analyticsPayloadsToken = concatenateAnalyticsPayloads(analyticsPayloads);
  // Send the page view Analytics hit with collected Analytics payload via Data Insertion API
});

Utilisation de `onBeforeEventSend` pour gérer les mesures de page using-onbeforeeventsend

À l’aide des activités Adobe Target, vous pouvez configurer différentes mesures sur la page, soit manuellement jointes au DOM, soit automatiquement jointes au DOM (activités créées par le VEC). Les deux types correspondent à une interaction différée de l’utilisateur final sur la page web.

Pour en tenir compte, il est recommandé de collecter les payloads Analytics à l’aide du hook de SDK web Adobe Experience Platform onBeforeEventSend. Le hook onBeforeEventSend doit être configuré à l’aide de la commande configure et sera reflété sur tous les événements envoyés par le biais du flux de données.

Voici un exemple de configuration d’onBeforeEventSent pour déclencher des accès Analytics :

alloy("configure", {
  datastreamId: "datastream configuration ID",
  orgId: "adobe ORG ID",
  onBeforeEventSend: function(options) {
    const xdm = options.xdm;
    const eventType = xdm.eventType;
    if (eventType === "decisioning.propositionInteract") {
      const analyticsPayloads = new Set();
      const propositions = xdm._experience.decisioning.propositions;

      for (var i = 0; i < propositions.length; i++) {
        var proposition = propositions[i];
        analyticsPayloads.add(getClickAnalyticsPayload(proposition));
      }
      // Trigger the Analytics hit
    }
  }
});

Étapes suivantes next-steps

Ce guide couvre la journalisation côté client pour les données A4T dans le SDK Web. Pour plus d’informations sur la gestion des données A4T sur Edge Network🔗 consultez le guide sur la journalisation côté serveur .

recommendation-more-help

ad108910-6329-42f1-aa1d-5920a2b13636