Actualización desde at.js 1.x a at.js 2.x

La versión más reciente de at.js en Adobe Target proporciona conjuntos de funciones enriquecidas que equipan su empresa para ejecutar la personalización en tecnologías de próxima generación de lado del cliente. Esta nueva versión se centra en actualizar at.js para tener interacciones armoniosas con aplicaciones de una sola página (SPA).

Estos son algunos de los beneficios de utilizar at.js 2.x que no están disponibles en versiones anteriores:

at.js 2.x diagramas de sistema

Los siguientes diagramas le ayudan a comprender el flujo de trabajo de at.js 2.SPA x con vistas y cómo esto mejora la integración de la. Para obtener una mejor introducción a los conceptos utilizados en at.js 2.x, consulte implementación de aplicación de una sola página.

(Haga clic en la imagen para ampliarla a ancho completo).

Ahora, independientemente de que se implemente triggerView() en la SPA, las vistas y acciones se recuperan de la caché y se muestran al usuario sin una llamada al servidor. triggerView() también realiza una solicitud de notificaciones al back-end Target para aumentar y registrar los recuentos de impresión.

(Haga clic en la imagen para ampliarla a ancho completo).

Implementación de at.js 2.x

Implementación de at.js 2.x mediante etiquetas en la extensión Adobe Experience Platform.

Funciones obsoletas de at.js

Existen varias funciones que se han quedado obsoletas en at.js 2.x.

Puede encontrar las funciones obsoletas y sus equivalentes a continuación. Para ver una lista completa de las funciones, consulte Funciones de at.js.

mboxCreate(mbox,params)

Descripción:

Ejecuta una solicitud y aplica la oferta al DIV más cercano con el nombre de clase mboxDefault.

Ejemplo:

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

at.js 2.x equivalente

getOffer() y applyOffer() son una alternativa a mboxCreate(mbox, params).

Ejemplo:

<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() y mboxUpdate()

Descripción:

Crea una asignación interna entre un elemento y un nombre de mbox, pero no ejecuta la solicitud. Se utiliza junto con mboxUpdate(), que ejecuta la solicitud y aplica la oferta al elemento identificado por ID de nodo en mboxDefine(). También se puede usar para actualizar un mbox iniciado por mboxCreate.

Ejemplo:

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

at.js 2.x equivalente:

Una alternativa a mboxDefine() y mboxUpdate es getOffer() y applyOffer(), con la opción de selector utilizada en applyOffer(). Este método permite asignar la oferta a un elemento mediante cualquier selector de CSS, no solo a uno con un ID.

Ejemplo:

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

Descripción:

Ofrece una forma estándar de registrar una extensión determinada.

Esto ya no se admite y no debe usarse.

Resumen de las funciones de at.js obsoletas, nuevas y admitidas en 2.x

Limitaciones y llamadas

Tenga en cuenta las siguientes limitaciones y llamadas:

Seguimiento de conversiones

Los clientes que utilizan mboxCreate() para el seguimiento de conversiones deben utilizar trackEvent() o getOffer().

Entrega de ofertas

Los clientes que no reemplacen mboxCreate() por getOffer() o applyOffer() se arriesgan a que no se entreguen las ofertas.

Puede usarse at.js 2.x en algunas páginas mientras que at.js 1.x está en otras páginas?

Sí, el perfil del visitante se conserva en todas las páginas que utilizan distintas versiones y bibliotecas. El formato de la cookie es el mismo.

Nuevo uso de API en at.js 2.x

at.js 2.x usa una nueva API que llamamos API de envío. Para depurar si at.js llama al servidor Edge de Target correctamente, puede filtrar la pestaña Red de las herramientas para desarrolladores del explorador a "entrega", "tt.omtrdc.net" o código de cliente. También notará que Target envía una carga útil JSON en lugar de pares clave-valor.

Target mbox global ya no se usa

En at.js 2.x, ya no ve "target-global-mbox" visiblemente en las llamadas de red. En su lugar, hemos reemplazado la sintaxis "target-global-mbox" por "execute > pageLoad" en la carga útil JSON enviada a los servidores Target, como se ve a continuación:

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

fundamentalmente, el concepto de mbox global se introdujo para hacer saber a Target si se recuperarán las ofertas y el contenido durante la carga de página. Esto lo hemos hecho más explícito en la versión más reciente.

¿Sigue siendo relevante el nombre de mbox global en at.js?

Los clientes pueden especificar un nombre de mbox global mediante Target > Administration > Implementation > Edit at.js Settings. Este ajuste lo utilizan los servidores Target Edge para traducir Ejecutar > pageLoad al nombre de mbox global que aparece en la interfaz de usuario Target. Esto permite a los clientes seguir utilizando API del lado del servidor, el compositor basado en formularios, los comandos de perfil y crear audiencias utilizando el nombre de mbox global. Le recomendamos encarecidamente que verifique que se haya configurado el mismo nombre de mbox global en la página Administration > Visual Experience Composer, en caso de que tenga páginas con at.js 1.x, como se muestra en las ilustraciones siguientes.

y

¿Es necesario activar la configuración de creación automática de mbox global para at.js 2?x?

En la mayoría de los casos, sí. Esta configuración indica a at.js 2.x para activar una solicitud a los servidores Edge Target al cargar la página. Este ajuste debería estar activado ya que mbox global se traduce para Ejecutar > pageLoad, y si desea activar una solicitud al cargar la página.

¿Seguirán funcionando las actividades existentes de VEC aunque el nombre de mbox global de Target no se especifique desde at.js 2?x?

Sí, porque Ejecutar > pageLoad se trata en el backend Target como target-global-mbox.

Si mis actividades basadas en formularios están dirigidas a target-global-mbox, ¿seguirán funcionando esas actividades?

Sí, porque Ejecutar > pageLoad se trata en los servidores Target Edge como target-global-mbox.

at.js 2 compatible y no compatible.Configuración de x

Compatibilidad de seguimiento entre dominios en at.js 2.x

El seguimiento entre dominios permite unir visitantes de dominios distintos. Dado que se debe crear una nueva cookie para cada dominio, es difícil rastrear a los visitantes cuando navegan de un dominio a otro. Para realizar el seguimiento entre dominios, Target utiliza una cookie de terceros para rastrear visitantes entre dominios. Esto le permite crear una actividad de Target que abarca siteA.com y siteB.com, y los visitantes permanecen en la misma experiencia cuando navegan por dominios únicos. Esta funcionalidad se vincula al comportamiento de cookies de origen y de terceros de Target.

En Target, la cookie de terceros se almacena en <CLIENTCODE>.tt.omtrdc.net. La cookie de origen se almacena en clientdomain.com. La primera solicitud devuelve encabezados de respuesta HTTP que intentan establecer cookies de terceros denominadas mboxSession y mboxPC, mientras se devuelve una solicitud de redirección con un parámetro adicional (mboxXDomainCheck=true). Si el navegador acepta cookies de terceros, la solicitud de redirección incluye dichas cookies y la experiencia se devuelve. Este flujo de trabajo es posible porque utilizamos el método HTTP GET.

Sin embargo, en at.js 2.x, no se usa la GET HTTP. En su lugar, se utiliza el POST HTTP a través de at.js 2.x para enviar cargas JSON a Target servidores de Edge. El uso del POST HTTP significa que se interrumpirá la solicitud de redirección para comprobar si un explorador admite cookies de terceros. Esto se debe a que las solicitudes HTTP GET son transacciones idempotentes, mientras que HTTP POST no es idempotente y no se debe repetir arbitrariamente. Por lo tanto, en el seguimiento entre dominios en at.js 2.x (anterior a 2.10) no es compatible de serie. Solo at.js 1.x es compatible de serie para el seguimiento entre dominios.

Para utilizar el seguimiento entre dominios para at.js v2.10 o posterior, puede realizar una de las siguientes acciones:

Para utilizar el seguimiento entre dominios para las versiones de at.js v2.x antes de 2.10, puede implementar la opción #1 arriba (instale la biblioteca ECID).

Se admite Crear automáticamente un mbox global

Esta configuración indica a at.js 2.x para activar una solicitud a los servidores Edge de Target durante la carga de página. Dado que el mbox global se traduce en ejecutar > pageLoad, y este es interpretado por los servidores Edge de Target, los clientes deben habilitarlo si desean activar una solicitud durante la carga de página.

Se admite el nombre de mbox global

Los clientes pueden especificar un nombre de mbox global mediante Target > Administration > Implementation > Edit. Este ajuste lo utilizan los servidores Edge Target para representar ejecutar > pageLoad en el nombre de mbox global introducido. Esto permite a los clientes seguir utilizando las API del servidor, el compositor basado en formularios, scripts de perfil y crear audiencias dirigidas al mbox global.

¿Los eventos personalizados de at.js se aplican a triggerView(), o es solo para applyOffer() o applyOffers()?

Sí, los eventos personalizados de at.js también son aplicables en triggerView().

Indica que cuando llamo a triggerView() con {"page" : "true"}, enviará una notificación al servidor de Target y aumentará la impresión. ¿También provoca que se ejecuten los scripts de perfil?

Cuando se realiza una llamada de recuperación previa al back-end de Target, se ejecutan los scripts de perfil. A partir de ahí, los datos de perfil afectados se cifran y se devuelven al cliente. Después de la invocación de triggerView() con {"page": "true"}, se envía una notificación junto con los datos de perfil cifrados. Es entonces cuando el back-end de Target descifra los datos de perfil y los almacena en las bases de datos.

¿Es necesario agregar el código de ocultamiento previo antes de llamar a triggerView() para administrar el parpadeo?

No, no es necesario agregar el código de ocultamiento previo antes de llamar a triggerView(). at.js 2.x administra la lógica de ocultamiento previo y el parpadeo antes de que se muestre y se aplique la vista.

Qué at.js 1.x parámetros para crear audiencias no son compatibles con at.js 2.x?

Los siguientes parámetros de at.js 1.x son NOT compatibles actualmente con la creación de audiencias al usar at.js 2.x:

at.js 2.x no admite la creación de audiencias con vst.* parámetros

Clientes en at.js 1.x pudieron usar vst.* Parámetros de mbox para crear audiencias. Este fue un efecto secundario no intencionado de cómo at.js 1.x envió parámetros de mbox al back-end Target. Después de migrar a at.js 2.x, ya no puede crear audiencias con estos parámetros debido a at.js 2.x envía parámetros de mbox de forma diferente.

Compatibilidad de at.js

Las tablas siguientes explican la 2.x compatibilidad con diferentes tipos de actividades, integraciones, características y funciones de at.js.

Tipos de actividades

Integraciones

Funciones

Parámetros de cadena de consulta

Tokens de respuesta

at.js 2.x, igual que at.js 1.x, utiliza el evento personalizado at-request-succeeded para los tokens de respuesta. Para obtener ejemplos de código utilizando el evento personalizado at-request-succeeded, consulte Tokens de respuesta.

at.js 1.x parámetros para at.js 2.Asignación de carga útil x

Esta sección describe las asignaciones entre at.js 1.x y at.js 2.x.

Antes de profundizar en la asignación de parámetros, los puntos finales que utilizan estas versiones de la biblioteca han cambiado:

Otra diferencia importante es que:

Las siguientes secciones enumeran cada at.js 1.x parámetro, su descripción y los 2 correspondientes.x carga JSON (si corresponde):

at_property

(at.js 1.x parámetro)

Se utiliza para Permisos de usuario de Enterprise.

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

mboxHost

(at.js 1.x parámetro)

Dominio de la página donde se ejecuta la biblioteca Target.

at.js 2.x carga JSON:

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

webGLRenderer

(at.js 1.x parámetro)

Las capacidades del procesador WEB GL del explorador. El mecanismo de detección de dispositivos lo utiliza para determinar si el dispositivo del visitante es de escritorio, un iPhone, un dispositivo Android, etc.

at.js 2.x carga JSON:

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

mboxURL

(at.js 1.x parámetro)

La dirección URL de la página.

at.js 2.x carga JSON:

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

mboxReferrer

(at.js 1.x parámetro)

El referente de la página.

at.js 2.x carga JSON:

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

mbox (el nombre) es igual al mbox global

(at.js 1.x parámetro)

La API de envío ya no tiene un concepto de mbox global. En la carga útil JSON debe utilizar execute > pageLoad.

at.js 2.x carga JSON:

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

mbox (el nombre) no es igual al mbox global

(at.js 1.x parámetro)

Para utilizar un nombre de mbox, páselo a execute > mboxes. Un mbox requiere un índice y un nombre.

at.js 2.x carga JSON:

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

mboxId

(at.js 1.x parámetro)

Ya no se utiliza.

mboxCount

(at.js 1.x parámetro)

Ya no se utiliza.

mboxRid

(at.js 1.x parámetro)

Solicitar ID utilizado por los sistemas descendentes para ayudar a depurar.

at.js 2.x carga JSON:

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

mboxTime

(at.js 1.x parámetro)

Ya no se utiliza.

mboxSession

(at.js 1.x parámetro)

El ID de sesión se envía como parámetro de cadena de consulta (sessionId) al extremo de la API de envío.

mboxPC

(at.js 1.x parámetro)

El ID de TNT se pasa a id > tntId.

at.js 2.x carga JSON:

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

mboxMCGVID

(at.js 1.x parámetro)

El ID de visitante de Experience Cloud se pasa a id > marketingCloudVisitorId.

at.js 2.x carga JSON:

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

vst.aaaa.id y vst.aaaa.authState

(at.js 1.x parámetros)

Los ID de cliente se deben pasar a id > customerIds.

at.js 2.x carga JSON:

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

mbox3rdPartyId

(at.js 1.x parámetro)

ID de terceros de cliente utilizado para vincular Target ID diferentes.

at.js 2.x carga JSON:

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

mboxMCSDID

(at.js 1.x parámetro)

SDID, también conocido como ID de datos suplementarios. Debe pasar a experienceCloud > analytics > supplementalDataId.

at.js 2.x carga JSON:

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

vst.trk

(at.js 1.x parámetro)

Servidor de seguimiento Analytics. Debe pasar a experienceCloud > analytics > trackingServer.

at.js 2.x carga JSON:

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

vst.trks

(at.js 1.x parámetro)

Servidor de seguimiento de Analytics seguro. Debe pasar a experienceCloud > analytics > trackingServerSecure.

at.js 2.x carga JSON:

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

mboxMCGLH

(at.js 1.x parámetro)

Sugerencia de ubicación de Audience Manager. Debe pasar a experienceCloud > audienceManager > locationHint.

at.js 2.x carga JSON:

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

mboxAAMB

(at.js 1.x parámetro)

Blob de Audience Manager. Debe pasar a experienceCloud > audienceManager > blob.

at.js 2.x carga JSON:

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

mboxVersion

(at.js 1.x parámetro)

La versión se envía como parámetro de cadena de consulta a través del parámetro de versión.

Vídeo de formación: at.js 2.x diagrama arquitectónico

at.js 2.x mejora la compatibilidad de Adobe SPA Target con el servicio de asistencia técnica e integra el servicio con otras soluciones de Experience Cloud para la integración con el servicio de asistencia técnica de . Este vídeo explica cómo se vincula todo.

Ver Explicación de cómo at.js 2.x funciona para obtener más información.