Aggiornamento da at.js 1.x in at.js 2.x

La versione più recente di at.js in Adobe Target offre set di funzioni avanzate che consentono di eseguire personalizzazioni su tecnologie lato client di nuova generazione. Questa nuova versione si concentra sull'aggiornamento di at.js per garantire interazioni in sintonia con le applicazioni a pagina singola.

Di seguito sono riportati alcuni vantaggi dell’utilizzo di at.js 2.x non disponibili nelle versioni precedenti:

at.js 2.x diagrammi di sistema

I seguenti diagrammi ti aiutano a comprendere il flusso di lavoro di at.js 2.x con visualizzazioni e miglioramento dell'integrazione SPA. Per una migliore introduzione dei concetti utilizzati in at.js 2.x, vedi Implementazione di un'applicazione a pagina singola.

(Fare clic sull'immagine per espanderla a larghezza intera.)

Ora, ovunque si implementi triggerView() nell’applicazione a pagina singola, le visualizzazioni e le azioni vengono recuperate dalla cache e mostrate all’utente senza una chiamata al server. triggerView() invia anche una richiesta di notifica al backend Target per incrementare e registrare i conteggi delle impression.

(Fare clic sull'immagine per espanderla a larghezza intera.)

Implementare at.js 2.x

Implementare at.js 2.x tramite tag nell'estensione Adobe Experience Platform.

Funzioni at.js obsolete

In at.js 2 sono state rimosse diverse funzioni.x.

Di seguito puoi trovare le funzioni obsolete e i loro equivalenti. Per un elenco completo delle funzioni, consulta Funzioni di at.js.

mboxCreate(mbox,params)

Descrizione:

Esegue una richiesta e applica l’offerta all’elemento DIV più vicino con il nome della classe mboxDefault.

Esempio:

<div class="mboxDefault">
  default content to replace by offer
</div>
<script>
  mboxCreate('mboxName','param1=value1','param2=value2');
</script>

Equivalente in at.js 2.x

Un’alternativa a mboxCreate(mbox, params) è getOffer() e applyOffer().

Esempio:

<div class="mboxDefault">
  default content to replace by offer
</div>
<script>
  var el = document.currentScript.previousElementSibling;
  adobe.target.getOffer({
    mbox: "mboxName",
    params: {
      param1: "value1",
      param2: "value2"
    },
    success: function(offer) {
      adobe.target.applyOffer({
        mbox: "mboxName",
        selector: el,
        offer: offer
      });
    },
    error: function(error) {
      console.error(error);
      el.style.visibility = "visible";
    }
  });
</script>

mboxDefine() e mboxUpdate()

Descrizione:

Crea una mappatura interna tra un elemento e un nome mbox, ma non esegue la richiesta. Utilizzata insieme a mboxUpdate(), che esegue la richiesta e applica l’offerta all’elemento identificato dal nodeId in mboxDefine(). Può essere utilizzato anche per aggiornare una mbox iniziata da mboxCreate.

Esempio:

<div id="someId" class="mboxDefault"></div>
<script>
 mboxDefine('someId','mboxName','param1=value1','param2=value2');
 mboxUpdate('mboxName','param3=value3','param4=value4');
</script>

Equivalente in at.js 2.x:

Un’alternativa a mboxDefine() e mboxUpdate è getOffer() e applyOffer(), con l’opzione del selettore utilizzata in applyOffer(). Questo approccio consente di mappare l’offerta su un elemento utilizzando qualsiasi selettore CSS, non solo uno con un ID.

Esempio:

<div id="someId" class="mboxDefault">
  default content to replace by offer
</div>
<script>
  adobe.target.getOffer({
    mbox: "mboxName",
    params: {
      param1: "value1",
      param2: "value2",
      param3: "value3",
      param4: "value4"
    },
    success: function(offer) {
      adobe.target.applyOffer({
        mbox: "mboxName",
        selector: "#someId",
        offer: offer
      });
    },
    error: function(error) {
      console.error(error);
      var el = document.getElementById("someId");
      el.style.visibility = "visible";
    }
  });
</script>

adobe.target.registerExtension()

Descrizione:

Fornisce un metodo standard per registrare un’estensione specifica.

Questa funzione non è più supportata. Non utilizzarla.

Riepilogo delle funzioni obsolete, nuove e supportate in at.js 2.x

Limitazioni e callout

Tieni presente le limitazioni e i callout seguenti:

Tracciamento delle conversioni

I clienti che usano mboxCreate() per il tracciamento delle conversione devono utilizzare trackEvent() o getOffer().

Consegna delle offerte

Se mboxCreate() non viene sosituito con getOffer() o applyOffer(), la consegna delle offerte potrebbe non riuscire.

È possibile usare at.js 2.x in alcune pagine, e at.js 1.x si trova su altre pagine?

Sì, il profilo del visitatore è mantenuto su più pagine utilizzando diverse versioni e librerie. Il formato del cookie è lo stesso.

Nuovo utilizzo dell’API in at.js 2.x

at.js 2.x utilizza una nuova API, che chiamiamo API Delivery. Per eseguire il debug se at.js sta chiamando correttamente il server perimetrale Target, è possibile filtrare la scheda Rete degli strumenti per sviluppatori del browser in "delivery", "tt.omtrdc.net" o nel codice client. Noterai inoltre che Target invia un payload JSON invece di coppie chiave-valore.

Mbox globale Target non più utilizzata

In at.js 2.x, non vedrai più "target-global-mbox" chiaramente nelle chiamate di rete. La sintassi "target-global-mbox" è stata sostituita con "execute > pageLoad" nel payload JSON inviato ai server Target, come illustrato di seguito:

{
  "id": {
    // ...
  },
  "context": {
    "channel": "web",
    // ...
  },
  "execute": {
    "pageLoad": {}
  }
}

In sostanza, il concetto di mbox globale era stato introdotto per comunicare a Target se recuperare o meno offerte e contenuti al caricamento delle pagine. Nella nostra versione più recente, lo abbiamo reso più esplicito.

Il nome della mbox globale in at.js ha ancora importanza?

I clienti possono specificare un nome di mbox globale tramite Target > Administration > Implementation > Edit at.js Settings. I server perimetrali Target utilizzano questa impostazione per tradurre execute > pageload nel nome della mbox globale visualizzato nell’interfaccia utente Target. Questo consente ai clienti di continuare a utilizzare le API lato server, il compositore basato su moduli, gli script di profilo e creare tipi di pubblico utilizzando il nome della mbox globale. Inoltre, ti consigliamo vivamente di configurare lo stesso nome della mbox globale anche sulla pagina Administration > Visual Experience Composer, nel caso in cui si disponga di pagine che utilizzano ancora at.js 1.x, come illustrato nelle illustrazioni seguenti.

e

È necessario attivare l’impostazione di creazione automatica di una mbox globale con at.js 2.x?

Nella maggior parte dei casi, sì. Questa impostazione comunica a at.js 2.x per attivare una richiesta ai server perimetrali Target al caricamento della pagina. Questa impostazione deve essere attiva perché la mbox globale si traduce in execution > pageLoad, ma anche se desideri attivare una richiesta al caricamento della pagina.

Le attività del Compositore esperienza visivo esistenti continueranno a funzionare, anche se il nome della mbox globale di Target non è specificato a partire da at.js 2.x?

Sì, perché execute > pageLoad è trattato sul backend Target come target-global-mbox.

Se le mie attività basate su moduli sono mirate per target-global-mbox, queste continueranno a funzionare?

Sì, perché execute > pageLoad è trattato sui server edge di Target come target-global-mbox.

at.js 2 supportato e non supportato.Impostazioni x

Supporto del tracciamento tra più domini in at.js 2.x

Il tracciamento tra più domini consente di unire i visitatori di domini diversi. Poiché per ciascun dominio deve essere creato un nuovo cookie, è difficile tenere traccia dei visitatori che passano da un dominio a un altro. Per eseguire il tracciamento tra più domini, Target utilizza usa un cookie di terze parti. Ciò ti consente di creare un'attività Target che si estende su siteA.com e siteB.com e i visitatori rimangono nella stessa esperienza quando passano da un dominio all'altro. Questa funzionalità è legata al comportamento dei cookie di terze parti e di prima parte di Target.

In Target, il cookie di terze parti è memorizzato in <CLIENTCODE>.tt.omtrdc.net. Il cookie di prime parti è memorizzato in clientdomain.com. La prima richiesta restituisce intestazioni di risposta HTTP che tentano di impostare cookie di terze parti denominati mboxSession e mboxPC, mentre viene inviata nuovamente una richiesta di reindirizzamento con un parametro aggiuntivo (mboxXDomainCheck=true). Se il browser accetta cookie di terze parti, la richiesta di reindirizzamento li include e viene restituita l’esperienza. Questo flusso di lavoro è possibile perché utilizziamo il metodo HTTP GET.

In at.js 2.x, GET HTTP non utilizzato. Invece, HTTP POST viene utilizzato tramite at.js 2.x per inviare payload JSON a Target server Edge. L’utilizzo di HTTP POST comporta la richiesta di reindirizzamento per verificare se un browser supporta i cookie di terze parti. Infatti le richieste HTTP GET sono transazioni idempotenti, mentre HTTP POST non lo è e non deve essere ripetuto arbitrariamente. Di conseguenza, il tracciamento tra più domini in at.js 2.x (prima della versione 2.10) non è supportato come funzionalità integrata. Solo at.js 1.x supporta il tracciamento tra più domini come funzionalità integrata.

Per utilizzare il tracciamento tra domini diversi per at.js v2.10 o versione successiva, puoi effettuare una delle seguenti operazioni:

Utilizzare il tracciamento tra domini diversi per le versioni di at.js v2.x prima della versione 2.10, è possibile implementare l'opzione #1 sopra (installare la libreria ECID).

Supporto della creazione automatica di una mbox globale

Questa impostazione comunica a at.js 2.x per attivare una richiesta ai server perimetrali Target al caricamento della pagina. Poiché la mbox globale è convertita in execute > pageLoad e interpretata dai server edge di Target, i clienti devono attivarla se desiderano avviare una richiesta al caricamento della pagina.

Supporto del nome mbox globale

I clienti possono specificare un nome di mbox globale tramite Target > Administration > Implementation > Edit. I server perimetrali Target utilizzano questa impostazione per tradurre execute > pageLoad nel nome della mbox globale immesso. Questo consente ai clienti di continuare a utilizzare le API lato server, il compositore basato su moduli, gli script di profilo e creare tipi di pubblico mirati per la mbox globale.

I seguenti eventi personalizzati at.js sono applicabili a triggerView() o valgono solo per applyOffer() o applyOffers()?

Sì, gli eventi personalizzati at.js sono applicabili anche a triggerView().

Quando richiamo triggerView() con {"page" : "true"}, dice che invierà una notifica al backend Target e aumenterà le impression. Questo provocherà anche l’esecuzione degli script di profilo?

Quando si effettua una chiamata di preacquisizione al backend Target, avviene l’esecuzione degli script di profilo. Successivamente, i dati del profilo interessati saranno crittografati e trasmessi nuovamente al lato client. Dopo la chiamata di triggerView() con {"page": "true"}, si invierà una notifica insieme ai dati di profilo codificati. Questo si verifica quando il backend Target deciderà di decodificare i dati di profilo e archiviarli nei database.

Per gestire la visualizzazione temporanea di altri contenuti è necessario aggiungere codice per nasconderli preventivamente prima di richiamare triggerView()?

No, non è necessario aggiungere codice per nascondere contenuti preventivamente prima di richiamare triggerView(). at.js 2.x gestisce la logica relativa ai contenuti nascosti anticipatamente e visualizzati temporaneamente prima di mostrare e applicare la visualizzazione.

Quale at.js 1.I parametri x per la creazione di tipi di pubblico non sono supportati in at.js 2.x?

I seguenti parametri di at.js 1.x sono NOT attualmente supportati per la creazione di tipi di pubblico quando si utilizza at.js 2.x:

at.js 2.x non supporta la creazione di tipi di pubblico utilizzando i parametri vst.* parametri

Clienti su at.js 1.x ha potuto usare vst.* Parametri mbox per creare tipi di pubblico. Si è trattato di un effetto collaterale non previsto di come at.js 1.x ha inviato parametri mbox al back-end Target. Dopo la migrazione a at.js 2.x, non è più possibile creare tipi di pubblico utilizzando questi parametri perché at.js 2.x invia i parametri mbox in modo diverso.

Compatibilità di at.js

Le tabelle seguenti contengono una spiegazione di at.js. 2.x compatibilità con diversi tipi di attività, integrazioni, funzionalità e funzioni di at.js.

Tipi di attività

Integrazioni

Funzioni

Parametri stringa di query

Token di risposta

at.js 2.x, esattamente come at.js 1.x, utilizza l’evento personalizzato at-request-succeeded per ottenere i token di risposta. Per esempi di codice con l’evento at-request-succeeded personalizzato, consulta Token di risposta.

Mappatura payload dei parametri at.js 1.x parametri in at.js 2.Mappatura payload x

Questa sezione delinea le mappature tra at.js 1.x che in at.js 2.x.

Prima di passare alla mappatura dei parametri, gli endpoint utilizzati da queste versioni della libreria sono cambiati:

Un’altra differenza significativa è che:

Le seguenti sezioni riportano tutte nell’elenco il parametro di at.js 1.Parametro x, descrizione e 2 corrispondente.Payload JSON x (se applicabile):

at_property

(parametro di at.js 1.x)

Utilizzato per le autorizzazioni per gli utenti Enterprise.

{
  ....
  "property": {
    "token": "1213213123122313121"
  }
  ....
}

mboxHost

(parametro di at.js 1.x)

Dominio della pagina in cui viene eseguita la libreria Target.

at.js 2.Payload JSON x:

{
  "context": {
    "browser": {
       "host": "test.com"
    }
  }
}

webGLRenderer

(parametro di at.js 1.x)

Funzionalità del rendering GL WEB del browser. Questo viene usato dal nostro meccanismo di rilevamento del dispositivo per determinare se il dispositivo del visitatore è un computer desktop, un iPhone, un dispositivo Android, ecc.

Payload JSON di at.js 2.Payload JSON x:

{
  "context": {
    "browser": {
       "webGLRenderer": "AMD Radeon Pro 560X OpenGL Engine"
    }
  }
}

mboxURL

(parametro di at.js 1.x)

URL della pagina.

Payload JSON di at.js 2.Payload JSON x:

{
  "context": {
    "address": {
       "url": "http://test.com"
    }
  }
}

mboxReferrer

(parametro di at.js 1.x)

Riferimento (provenienza) della pagina.

Payload JSON di at.js 2.Payload JSON x:

{
  "context": {
    "address": {
       "referringUrl": "http://google.com"
    }
  }
}

mbox (il nome) è uguale a mbox globale

(parametro di at.js 1.x)

L’API della consegna non dispone più di un concetto mbox globale. Nel payload JSON devi usare execute > pageLoad.

Payload JSON di at.js 2.Payload JSON x:

{
  "execute": {
    "pageLoad": {
       "parameters": ....
       "profileParameters": ...
       .....
    }
  }
}

mbox (il nome) non è uguale a mbox globale

(parametro di at.js 1.x)

Per utilizzare il nome di una mbox, trasmettilo a execute > mboxes. Una mbox richiede un indice e un nome.

Payload JSON di at.js 2.Payload JSON x:

{
  "execute": {
    "mboxes": [{
       "index": 0,
       "name": "some-mbox",
       "parameters": ....
       "profileParameters": ...
       .....
    }]
  }
}

mboxId

(parametro di at.js 1.x)

Non più utilizzato.

mboxCount

(parametro di at.js 1.x)

Non più utilizzato.

mboxRid

(parametro di at.js 1.x)

ID della richiesta utilizzato dai sistemi a valle per facilitare il debug.

Payload JSON di at.js 2.Payload JSON x:

{
  "requestId": "2412234442342"
  ....
}

mboxTime

(parametro di at.js 1.x)

Non più utilizzato.

mboxSession

(parametro di at.js 1.x)

L’ID della sessione viene inviato come parametro della stringa di query (sessionId) all’endpoint API di consegna.

mboxPC

(parametro di at.js 1.x)

L’ID TNT viene trasmesso in id > tntId.

Payload JSON di at.js 2.Payload JSON x:

{
  "id": {
    "tntId": "ca5ddd7e33504c58b70d45d0368bcc70.21_3"
  }
  ....
}

mboxMCGVID

(parametro di at.js 1.x)

L’ID del visitatore di Experience Cloud viene trasmesso in id > marketingCloudVisitorId.

Payload JSON di at.js 2.Payload JSON x:

{
  "id": {
    "marketingCloudVisitorId": "797110122341429343505"
  }
  ....
}

vst.aaaa.id e vst.aaaa.authState

(parametro di at.js 1.x)

Gli ID cliente devono essere trasmessi in id > customerIds.

Payload JSON di at.js 2.Payload JSON x:

{
  "id": {
    "customerIds": [{
       "id": "1232131",
       "integrationCode": "aaaa",
       "authenticatedState": "....."
     }]
  }
  ....
}

mbox3rdPartyId

(parametro di at.js 1.x)

ID di terze parti del cliente utilizzato per collegare diversi ID Target.

at.js 2.Payload JSON x:

{
  "id": {
    "thirdPartyId": "1232312323123"
  }
  ....
}

mboxMCSDID

(parametro di at.js 1.x)

SDID, noto anche come ID di dati supplementari. Deve essere trasmesso in experienceCloud > analytics > supplementalDataId.

Payload JSON di at.js 2.Payload JSON x:

{
  "experienceCloud": {
    "analytics": {
      "supplementalDataId": "1212321132123131"
    }
  }
  ....
}

vst.trk

(parametro di at.js 1.x)

Server di tracciamento Analytics. Deve essere trasmesso in experienceCloud > analytics > trackingServer.

Payload JSON di at.js 2.Payload JSON x:

{
  "experienceCloud": {
    "analytics": {
      "trackingServer": "analytics.test.com"
    }
  }
  ....
}

vst.trks

(parametro di at.js 1.x)

Server di tracciamento sicuro di Analytics. Deve essere trasmesso in experienceCloud > analytics > trackingServerSecure.

Payload JSON di at.js 2.Payload JSON x:

{
  "experienceCloud": {
    "analytics": {
      "trackingServerSecure": "secure-analytics.test.com"
    }
  }
  ....
}

mboxMCGLH

(parametro di at.js 1.x)

Hint di posizione di Audience Manager. Deve essere trasmesso in experienceCloud > audienceManager > locationHint.

Payload JSON di at.js 2.Payload JSON x:

{
  "experienceCloud": {
    "audienceManager": {
      "locationHint": 9
    }
  }
  ....
}

mboxAAMB

(parametro di at.js 1.x)

Blob Audience Manager. Deve essere trasmesso in experienceCloud > audienceManager > blob.

Payload JSON di at.js 2.Payload JSON x:

{
  "experienceCloud": {
    "audienceManager": {
      "blob": "2142342343242342"
    }
  }
  ....
}

mboxVersion

(parametro di at.js 1.x)

La versione viene inviata come parametro della stringa di query tramite il parametro della versione.

Video di formazione: at.js 2.x diagramma architetturale

at.js 2.x migliora il supporto di Adobe Target per l'SPA e si integra con altre soluzioni Experience Cloud. Questo video spiega come tutti questo elementi funzionano insieme.

Consulta Informazioni su at.js 2.x funziona per ulteriori informazioni.