Registrazione lato client dei dati A4T in Experience Platform Web SDK
Panoramica overview
Adobe Experience Platform Web SDK 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 raccoglierli e condividerli con Analytics. Questa opzione deve essere abilitata se intendi inviare manualmente i dati ad Analytics utilizzando l'API di inserimento dati.
Questo documento illustra i passaggi per impostare la registrazione A4T lato client per Web SDK e fornisce alcuni 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 Web SDK a scopo di personalizzazione. Per un'introduzione, consulta la seguente documentazione:
Configurare la registrazione lato client di Analytics set-up-client-side-logging
Le sottosezioni seguenti descrivono come abilitare la registrazione lato client di Analytics per l’implementazione di Web SDK.
Abilita registrazione lato client di Analytics 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.
Recupera i dati di A4T da SDK e inviali ad 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 di Analytics.
Quando Target Edge calcola una risposta di proposte, controlla se la registrazione lato client di Analytics è abilitata (ad esempio se Analytics è disabilitata 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:
Di seguito è riportato un esempio di risposta interact quando la registrazione lato client di Analytics è abilitata. Se la proposta è per un'attività che ha reporting di Analytics, 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à del Compositore esperienza basato su moduli possono contenere sia elementi di contenuto che elementi di metrica di clic sotto la 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}.
analyticsToken, analyticsDisplayToken, analyticsClickToken possono contenere più token, concatenati come una singola stringa delimitata da virgole.| code language-javascript |
|---|
|
Esempi di implementazione implementation-examples
Le seguenti sottosezioni mostrano come implementare la registrazione lato client di Analytics per i casi d’uso comuni.
Attività del Compositore esperienza basato su moduli form-based-composer
Puoi utilizzare il Web SDK per controllare l'esecuzione delle proposte dalle attività del Compositore esperienza basato su Adobe Target Form.
Quando richiedi proposte per un ambito decisionale specifico, la proposta restituita contiene il token Analytics appropriato. Si consiglia di concatenare il comando sendEvent di Experience Platform Web SDK e di eseguire iterazioni nelle proposte restituite per eseguirle durante la raccolta dei token di Analytics contemporaneamente.
È possibile attivare un comando sendEvent per un ambito di attività del Compositore esperienza basato su moduli come riportato di seguito:
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 ad 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. Per le attività del Compositore esperienza basato su moduli sono supportati quattro schemi di elementi delle proposte:
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 di Analytics per le metriche di clic devono essere raccolti e inviati ad 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 sarà 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, quando si applicano attività del Compositore esperienza basato su moduli con Experience Platform Web SDK, è necessario eseguire i seguenti passaggi:
-
Invia un evento che recupera le offerte delle attività del Compositore esperienza basato su moduli;
-
Applica le modifiche al contenuto della pagina;
-
Invia l'evento di notifica
decisioning.propositionDisplay; -
Raccogli i token di visualizzazione di Analytics dalla risposta di SDK e crea un payload per l’hit di Analytics;
-
Invia il payload ad Analytics utilizzando l'API di inserimento dati;
-
Se nelle proposte distribuite sono presenti metriche di clic, i listener di clic devono essere configurati in modo che, quando viene eseguito un clic, invii l'evento di notifica
decisioning.propositionInteract. Il gestoreonBeforeEventSenddeve essere configurato in modo che quando si intercettanodecisioning.propositionInteracteventi, si verifichino le seguenti azioni:- Raccolta dei token di analisi dei clic da
xdm._experience.decisioning.propositions - Invio dell'hit di analisi dei clic con il payload di Analytics raccolto tramite API di inserimento dati;
- Raccolta dei token di analisi dei clic da
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
});
Attività del Compositore esperienza visivo visual-experience-composer-acitivties
Il Web SDK consente di gestire le offerte create con Compositore esperienza visivo.
Quando è abilitato il rendering automatico, puoi raccogliere i token di Analytics dalle proposte che sono state eseguite sulla pagina. Si consiglia di concatenare il comando di Experience Platform Web SDK sendEvent e di eseguire un'iterazione delle proposte restituite per filtrare quelle di cui il Web SDK ha tentato il rendering.
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à di 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 questo, la best practice prevede di raccogliere i payload di Analytics utilizzando l'hook Web SDK di onBeforeEventSend Adobe Experience Platform. L'hook onBeforeEventSend deve essere configurato utilizzando il comando configure e verrà riflesso in tutti gli eventi inviati tramite lo stream di dati.
Di seguito è riportato un esempio di come onBeforeEventSent può essere configurato per attivare gli hit di 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
}
}
});
Passaggi successivi next-steps
Questa guida tratta la registrazione lato client dei dati A4T nel Web SDK. Per ulteriori informazioni su come gestire i dati A4T in Edge Network, consulta la guida alla registrazione lato server.