Documentazione Target Guida per gli sviluppatori di Target

Registrazione lato client per i dati A4T in Experience Platform Web SDK

Last update: Mon Aug 11 2025 00:00:00 GMT+0000 (Coordinated Universal Time)

Argomenti:
Implementazione

Creato per:

Sviluppatore

Adobe Experience Platform Web SDK ti consente di raccogliere i dati di Adobe Analytics for Target (A4T) sul lato client dell'applicazione Web.

La registrazione lato client indica che i dati Target rilevanti vengono restituiti sul lato client, consentendo di raccogliere i dati e condividerli con Analytics. Questa opzione deve essere abilitata se intendi inviare manualmente i dati ad Analytics utilizzando l'API di inserimento dati.

NOTE

Un metodo per eseguire questa operazione utilizzando AppMeasurement.js è attualmente in fase di sviluppo e sarà disponibile nel prossimo futuro.

Questo documento descrive i passaggi per configurare la registrazione A4T lato client per Platform Web SDK e fornisce esempi di implementazione per i casi d'uso comuni.

Prerequisiti prerequisites

Questo tutorial presuppone che tu abbia familiarità con i concetti e i processi fondamentali relativi all'utilizzo di Platform Web SDK a scopo di personalizzazione. Se hai bisogno di un’introduzione, consulta la seguente documentazione:

Configura Analytics registrazione lato client set-up-client-side-logging

Nelle sottosezioni seguenti viene descritto come abilitare la registrazione lato client di Analytics per l'implementazione di Platform Web SDK.

Abilita Analytics registrazione lato client enable-analytics-client-side-logging

Per considerare abilitata la registrazione lato client di Analytics per l'implementazione, è necessario disabilitare la configurazione di Adobe Analytics nel flusso di dati.

Configurazione dello stream di dati di Analytics disabilitata

Recupera i dati di A4T da SDK e inviali a Analytics a4t-to-analytics

Per il corretto funzionamento di questo metodo di reporting, è necessario inviare i dati correlati a A4T recuperati dal comando sendEvent nell'hit Analytics.

Quando Target Edge calcola una risposta di proposte, controlla se la registrazione lato client di Analytics è abilitata (ad esempio, se Analytics è disabilitato nello stream di dati). Se la registrazione lato client è abilitata, il sistema aggiunge un token Analytics a ogni proposta nella risposta.

Il flusso è simile al seguente:

Flusso di registrazione lato client

Di seguito è riportato un esempio di risposta interact quando è abilitata la registrazione lato client di Analytics. Se la proposta è per un'attività che ha Analytics reporting, avrà una proprietà 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
    }
  ]
}

Le proposte per le attività Form-based Experience Composer possono contenere sia elementi di contenuto che elementi di metrica di clic nella stessa proposta. Pertanto, invece di avere un singolo token di analisi per la visualizzazione del contenuto nella proprietà scopeDetails.characteristics.analyticsToken, è possibile che nelle proprietà scopeDetails.characteristics.analyticsDisplayToken e scopeDetails.characteristics.analyticsClickToken siano specificati sia un token di analisi dei clic che un token di analisi dei clic.

{
  "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
    }
  ]
}

Tutti i valori da scopeDetails.characteristics.analyticsToken, così come scopeDetails.characteristics.analyticsDisplayToken (per il contenuto visualizzato) e scopeDetails.characteristics.analyticsClickToken (per le metriche di clic) sono i payload A4T che devono essere raccolti e inclusi come tag tnta nella chiamata dell'API di inserimento dati 5}.

IMPORTANT

Le proprietà analyticsToken, analyticsDisplayToken, analyticsClickToken possono contenere più token, concatenati come una singola stringa delimitata da virgole.

Negli esempi di implementazione forniti nella sezione successiva, più token Analytics vengono raccolti iterativamente. Per concatenare un array di Analytics token, utilizzare una funzione simile alla seguente:

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

Esempi di implementazione implementation-examples

Nelle sottosezioni seguenti viene illustrato come implementare la registrazione lato client di Analytics per i casi d'uso comuni.

Form-Based Experience Composer attività form-based-composer

È possibile utilizzare Platform Web SDK per controllare l'esecuzione delle proposte dalle attività Compositore esperienza basato su Adobe Target Form.

Quando si richiedono proposte per un ambito decisionale specifico, la proposta restituita contiene il token Analytics appropriato. Si consiglia di concatenare il comando Experience Platform Web SDK sendEvent e di scorrere le proposte restituite per eseguirle durante la raccolta dei token Analytics contemporaneamente.

È possibile attivare un comando sendEvent per un ambito attività Form-Based Experience Composer come:

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

Da qui, devi implementare il codice per eseguire le proposte e creare un payload che verrà infine inviato a Analytics. Di seguito è riportato un esempio di ciò che results.propositions potrebbe contenere:

[
  {
    "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"
        }
      }
    ]
  }
]

Per estrarre il token Analytics da una proposta con elementi di contenuto, puoi implementare una funzione simile alla seguente:

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

Una proposta può avere diversi tipi di elementi, come indicato dalla proprietà schema dell'elemento in questione. Sono supportati quattro schemi di elementi di proposta per Form-Based Experience Composer attività:

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 e JSON_SCHEMA sono gli schemi che riflettono il tipo di offerta, mentre MEASUREMENT_SCHEMA riflette le metriche che devono essere collegate a un elemento DOM.

I payload Analytics per le metriche di clic devono essere raccolti e inviati a Analytics separatamente dagli elementi di contenuto, nel momento in cui il visitatore fa clic sul contenuto visualizzato in precedenza.

In questo caso, la seguente funzione di assistenza per ottenere i payload A4T della metrica di clic risulta utile:

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

Riepilogo dell’implementazione implementation-summary

In sintesi, è necessario eseguire i seguenti passaggi quando si applicano Form-Based Experience Composer attività con Experience Platform Web SDK:

Invia un evento che recupera Form-Based Experience Composer offerte di attività;
Applica le modifiche al contenuto della pagina;
Invia l'evento di notifica decisioning.propositionDisplay;
Raccogliere i token di visualizzazione Analytics dalla risposta di SDK e creare un payload per l'hit Analytics;
Invia il payload a Analytics utilizzando l'API di inserimento dati;
Se nelle proposte distribuite sono presenti metriche di clic, è necessario configurare i listener di clic in modo che, quando viene eseguito un clic, invii l'evento di notifica decisioning.propositionInteract. Il gestore onBeforeEventSend deve essere configurato in modo che quando si intercettano decisioning.propositionInteract eventi, si verifichino le seguenti azioni:
1. Raccolta dei token di clic Analytics da xdm._experience.decisioning.propositions
2. Invio dell'hit di clic Analytics con il payload Analytics raccolto tramite API di inserimento dati;

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

Visual Experience Composer attività (VEC) visual-experience-composer-acitivties

Platform Web SDK consente di gestire le offerte create con Compositore esperienza visivo.

NOTE

I passaggi per l'implementazione di questo caso d'uso sono molto simili a quelli per attività del Compositore esperienza basato su moduli. Consulta la sezione precedente per ulteriori dettagli.

Quando è abilitato il rendering automatico, puoi raccogliere i token Analytics dalle proposte eseguite sulla pagina. Si consiglia di concatenare il comando Experience Platform Web SDK sendEvent e di scorrere le proposte restituite per filtrare quelle che Web SDK ha tentato di riprodurre.

Esempio

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

Utilizzo di `onBeforeEventSend` per gestire le metriche della pagina using-onbeforeeventsend

Utilizzando le attività Adobe Target, puoi impostare metriche diverse sulla pagina, sia manualmente allegate al DOM che automaticamente associate al DOM (attività create dal Compositore esperienza visivo). Entrambi i tipi rappresentano un’interazione ritardata dell’utente finale sulla pagina web.

Per tenere conto di ciò, la best practice prevede di raccogliere i payload Analytics utilizzando l'hook onBeforeEventSend Adobe Experience Platform Web SDK. L'hook onBeforeEventSend deve essere configurato utilizzando il comando configure e si riflette in tutti gli eventi inviati tramite lo stream di dati.

Di seguito è riportato un esempio di come onBeforeEventSent può essere configurato per attivare Analytics hit:

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

Passaggi successivi next-steps

Questa guida tratta la registrazione lato client per i dati A4T in Platform Web SDK. Per ulteriori informazioni su come gestire i dati A4T in Edge Network, consulta la guida alla registrazione lato server.

recommendation-more-help

6906415f-169c-422b-89d3-7118e147c4e3