Métodos de DIL de nivel de instancia instance-level-dil-methods

WARNING
A partir de julio de 2023, el Adobe ha interrumpido el desarrollo de la extensión Data Integration Library (DIL) y DIL.
Los clientes existentes pueden seguir usando su implementación de DIL. Sin embargo, el Adobe no se desarrollará DIL más allá de este punto. Se recomienda a los clientes que evalúen SDK web de Experience Platform para su estrategia de recopilación de datos a largo plazo.
Los clientes que deseen implementar nuevas integraciones de recopilación de datos a partir de julio de 2023 deben utilizar SDK web de Experience Platform en su lugar.

Las API DIL de nivel de instancia le permiten crear y trabajar mediante programación con objetos de Audience Manager. Los métodos de nivel de instancia mejoran la funcionalidad de la API establecida por los métodos de nivel de clase.

Introducción a los métodos DIL de nivel de instancia get-started-dil-methods

Al trabajar con las API DIL de nivel de instancia:

  • Access requiere un nombre de socio y un identificador de área de nombres de contenedor (NSID). Póngase en contacto con el administrador de cuentas de Audience Manager para obtener esta información.
  • Reemplace cualquier texto de cursiva de muestra en la documentación de la API por un valor, ID u otra variable según lo requiera el método con el que esté trabajando.

señales signals

Agrega asignaciones de nivel de cliente y de plataforma a la cadena de consulta de una solicitud pendiente.

Firma de función: signals: function ({key1:value1, key2:value2},prefix){}

NOTE
  • Puede encadenar otras llamadas de API a este método.
  • Si la biblioteca JavaScript de Adobe Experience Cloud está en la página, submit() espera a que Cloud establezca una cookie antes de enviar una solicitud.

Claves de solicitud reservadas

Las siguientes claves de solicitud están reservadas y este método no las puede sobrescribir:

  • sids
  • pdata
  • logdata
  • callback
  • postCallbackFn
  • useImageRequest

Parámetros

Nombre
Tipo
Descripción
obj
Objeto
Un objeto que representa los pares clave-valor para las asignaciones a nivel de plataforma. El parámetro acepta cadenas y matrices como valores de propiedad en el objeto.
prefix
Cadena
Opcional. El valor de cadena con el prefijo a cada clave de objeto (reemplaza la clave original).
return
DIL.api
Devuelve el objeto API de la instancia de DIL actual.

Respuesta

Devuelve el objeto API de la instancia actual DIL.

Código de ejemplo


var dataLib = DIL.create({
     partner: 'partnerName'
     containerNSID: containerNSID
});

// Method 1
var obj = { key1 : 1, key2 : 2 };
dataLib.api.signals(obj, 'c_').submit();

// Method 2
dataLib.api.signals({c_zdid: 54321}).submit();

// Method 3
// Will send 'c_key=a&c_key=2&c_key=3' to Audience Manager
var obj = { key : ['a', 'b', 'c'] };
dataLib.api.signals(obj, 'c_').submit();

traits traits

Agrega SID a la cadena de consulta de una solicitud pendiente.

Firma de función: traits:function (sids){}

NOTE
Puede encadenar otras llamadas de API a este método.

Parámetros

Nombre
Tipo
Descripción
sids
Matriz
ID de segmentos de rasgos en una matriz.

Respuesta

Devuelve el objeto API de la instancia actual DIL.

Código de ejemplo


var partnerObject = DIL.create({
     partner: 'partner name',
     containerNSID: NSID
});
partnerObject.api.traits([123, 456, 789]);

registros logs

Agregue datos a los archivos de registro en la solicitud pendiente.

Firma de función: logs: function {key1:value1, key2:value2}

Respuesta

Devuelve el objeto API de la instancia actual DIL.

Código de ejemplo


var partnerObject = DIL.create({
     partner: 'partner',
     containerNSID: NSID
});
partnerObject.api.logs({
     file: 'dil.js',
     message: 'This is the first request'
});

submit submit

Envía todos los datos pendientes al Audience Manager para la instancia DIL.

Firma de función: submit: function () {}

NOTE
Puede encadenar otras llamadas de API a este método. Además, DIL escribe datos codificados en una cookie de destino. Por ejemplo, los espacios se codifican como %20 y los puntos y comas como %3B.

Respuesta

Devuelve el objeto API de la instancia actual DIL.

Código de ejemplo


var dataLib = DIL.create({
     partner: 'partnerName',
     containerNSID: containerNSID
});

dataLib.api.traits([
123,456, 789]).logs({
     file: 'dil.js',
     message: 'This is the first request'
}).signals({
     c_zdid: 1111
     d_dma: 'default'
}).submit();

afterResult afterresult

Una función que se ejecuta después de la llamada de retorno de publicación de destino predeterminada.

Firma de función: afterResult: function (fn) {}

NOTE
Puede encadenar otras llamadas de API a este método.

Parámetros

Nombre
Tipo
Descripción
fn
Función
La función que desea ejecutar después de JSON se procesa mediante la llamada de retorno predeterminada que administra la publicación de destino.

Respuesta

Devuelve un objeto API de la instancia actual DIL.

Código de ejemplo


var dataLib = DIL.create({
     partner: 'partnerName',
     containerNSID: containerNSID
});

dataLib.api.signals({
     c_zdid: 54321
     d_dma: 'default'
}).afterResult(function(json){
     //Do something with the JSON data returned from the server.
}).submit();

clearData cleardata

Borra todos los datos de una solicitud pendiente.

Firma de función: clearData: function () {}

NOTE
Puede encadenar otras llamadas de API a este método.

Respuesta

Devuelve el objeto API de la instancia actual DIL.

Código de ejemplo


var dataLib = DIL.create({
     partner: 'partnerName',
     containerNSID: containerNSID
});

dataLib.api.traits([123,456, 789]).logs({
     file: 'dil.js'
     message: 'This is the first request'
}).signals({
     c_zdid: 1111
     d_dma: 'default'
});

//Reset the pending data
dataLib.clearData();

customQueryParams customqueryparams

Agrega parámetros de consulta personalizados que no están definidos explícitamente por el servidor de recopilación de datos a una solicitud pendiente.

Firma de función: customQueryParams: function (obj) {}

NOTE
Puede encadenar otras llamadas de API a este método.

Claves de solicitud reservadas

Las siguientes claves de solicitud están reservadas y este método no las puede sobrescribir:

  • sids
  • pdata
  • logdata
  • callback
  • postCallbackFn
  • useImageRequest

Respuesta

Devuelve el objeto API de la instancia de DIL actual.

Código de ejemplo


var partnerObject = DIL.create({
     partner: 'partner',
     containerNSID: NSID
});
partnerObject.api.customQueryParams({
     nid: 54231,
     ntype: 'default'
});

getContainerNSID getcontainernsid

Devuelve el valor del NSID del contenedor para la instancia DIL. Útil para depurar y solucionar problemas.

Firma de función: dil.api.getContainerNSID: function () {}

Código de ejemplo


var dataLib = DIL.create({
     partner: 'partnerName',
     containerNSID: containerNSID
});

//Verify the container NSID
var nsid = dataLib.api.getContainerNSID();

getEventLog geteventlog

Devuelve datos de registro de eventos ordenados cronológicamente como una matriz de cadenas. Útil para depurar y solucionar problemas.

Firma de función: dil.api.getEventLog: function () {}

Código de ejemplo


var dataLib = DIL.create({
     partner: 'partnerName',
     containerNSID: containerNSID
});

dataLib.api.traits([123, 456, 789]).logs({
     file: 'dil.js',
     message: 'This is the first request'
});.signals({
     c_zdid: 1111
     d_dma: 'default'
});.submit();

//Check log for messages
var log = dataLib.api.getEventLog();
if (log && log.length) {
     alert(log.join('\n'));
}else{
     alert('No log messages');
}

getPartner getpartner

Devuelve el nombre del socio para una instancia de DIL. Útil para depurar y solucionar problemas.

Firma de función: dil.api.getPartner: function () {}

Código de ejemplo


var dataLib = DIL.create({
     partner: 'partnerName'
     containerNSID: containerNSID
});

//Verify the partner name
var partner = dataLib.api.getPartner();

getState getstate

Devuelve el estado de la instancia actual de DIL. Útil para depurar y solucionar problemas.

Firma de función: dil.api.getState: function () {}

Código de ejemplo


var dataLib = DIL.create({
     partner: 'partnerName',
     containerNSID: containerNSID
});

dataLib.api.traits([123, 456, 789]).logs({
     file: 'dil.js',
     message:'This is the first request'
});.signals({
     c.zdid: 1111
     d_dma: 'default'
});.submit();

var state = dataLib.api.getState();

/*Object outline of state
state = {
     pendingRequest: {pending data for call to server},
     otherRequestInfo:{
          firingQueue: [],
          fired: [],
          firing: false,
          errored: [],
          reservedKeys: {
               sids: true,
               pdata: true,
               logdata: true,
               callback: true,
               postCallbackFn: true,
               useImageRequest: true,
          },
          firstRequestHasFired: false,
          num_of_jsonp_responses: 0,
          num_of_jsonp_errors: 0,
          num_of_img_responses: 0,
          num_of_img_errors: 0
     },
     destinationPublishingInfo: {
          THROTTLE_START: 3000,
          throttleTimerSet: false,
          id: ''destination_publishing_iframe_' + partner + '_' + containerNSID,
          url: (constants.isHTTPS ? 'https://' : 'https://fast.') + partner + '.demdex.net/dest3.html?d_nsid='
          ​+ containerNSID + '#' + encodeURIComponent(document.location.href),
               iframe: null,
               iframeHasLoaded: false,
               sendingMessages: false,
               messages: [],
               messageSendingInterval: constants.POST_MESSAGE_ENABLED ? 15: 100,
               //Recommend 100ms for IE 6 & 7, 15ms for other browsers
               jsonProcessed: []
     }
}
*/

idSync idsync

Consta de dos funciones que permiten a los socios de datos intercambiar y sincronizar los ID de usuario entre ellos y el Audience Manager.

Firma de función:

Funciona con DIL versiones 2.10 y 3.1 o superiores.

Código
Sincroniza los ID de los usuarios
dil.Instance.api.idSync(initConfig)

Entre diferentes socios de datos y el Audience Manager. Por ejemplo, el socio x utilizaría esto para sincronizar un ID de usuario con un socio y enviarlo al Audience Manager.

Importante: Este método está obsoleto. Utilice el método idSyncByURL de la instancia del servicio de identidad de Adobe Experience Platform.

dil.Instance.api.aamIdSync(initConfig)

Cuando ya conoce el ID de usuario y desea enviarlo al Audience Manager.

Importante: Este método está obsoleto. Utilice el método idSyncByDataSource de la instancia del servicio de identidad de Adobe Experience Platform.

Elementos idSync

idSync puede consistir en lo siguiente:

Nombre
Tipo
Descripción
dpid
Cadena
ID de proveedor de datos asignado por Audience Manager.
dpuuid
Cadena
El ID único de proveedor de datos para el usuario.
minutesToLive
Número
(Opcional) Establece el tiempo de caducidad de la cookie. Debe ser un número entero. El valor predeterminado es de 20160 minutos (14 días).
url
Cadena
Dirección URL de destino.

Macros

idSync acepta las siguientes macros:

  • %TIMESTAMP%: genera una marca de tiempo (en milisegundos). Se emplea para ignorar la caché.
  • %DID%: inserta el identificador de Audience Manager para el usuario.
  • %HTTP_PROTO%: Establece el protocolo de la página ( http o https).

Respuesta

Ambas funciones devuelven Successfully queued si se realiza correctamente. Si no, devuelven una cadena con un mensaje de error.

Código de ejemplo

dilInstance.api.idSync(initConfig)


// Fires url with macros replaced
dilInstance.api.idSync({
 dpid: '23', // must be a string
 url: '//su.addthis.com/red/usync?pid=16&puid=%DID%&url=%HTTP_PROTO%%3A%2F%2Fdpm.demdex.net
%2Fibs%3Adpid%3D420%26dpuuid%3D%7B%7Buid%7D%7D',
 minutesToLive: 20160 // optional, defaults to 20160 minutes (14 days)
});

dilInstance.api.aamIdSync(initConfig)


// Fires 'https:/https:' + '//dpm.demdex.net/ibs:dpid=<dpid>&dpuuid=<dpuuid>'
dilInstance.api.aamIdSync({
 dpid: '23', // must be a string
 dpuuid: '98765', // must be a string
 minutesToLive: 20160 // optional, defaults to 20160 minutes (14 days)
});

resultado result

Agrega una llamada de retorno (que recibe JSON) a la solicitud pendiente.

Firma de función: result: function (callback) {}

Esta llamada de retorno reemplaza la llamada de retorno predeterminada que administra la publicación de destino.

NOTE
Puede encadenar otras llamadas de API a este método.

Parámetros

Nombre
Tipo
Descripción
callback
Función
Función de JavaScript ejecutada por la llamada de retorno JSONP.

Respuesta

Devuelve el objeto API de la instancia actual DIL.

Código de ejemplo


var dataLib = DIL.create({
     partner: 'partnerName',
     containerNSID: containerNSID
});

dataLib.api.traits([123, 456, 789]).result(function(json){
     //Do something, possibly with the JSON data returned from the server.
});.submit();

secureDataCollection securedatacollection

secureDataCollection es un parámetro booleano que controla cómo DIL realiza llamadas a Data Collection Servers (DCS) y Akamai.

  • Cuando secureDataCollection= true (predeterminado), DIL siempre realiza llamadas HTTPS seguras.

  • Cuando secureDataCollection= false, DIL realiza llamadas HTTP o HTTPS siguiendo el protocolo de seguridad establecido por la página.

IMPORTANT
Establezca secureDataCollection= false si utiliza visitorAPI.js y DIL en la misma página. Consulte el ejemplo de código siguiente.

var dilInstance = DIL.create({
     ...
     secureDataCollection: false
});

useCORSOnly usecorsonly

useCORSOnly es un parámetro booleano true/false que controla el modo en el que el explorador solicita recursos de otros dominios.

Información general

useCORSOnly es falso de manera predeterminada. False significa que el explorador puede realizar comprobaciones de recursos con CORS o JSONP. Sin embargo, DIL siempre intenta solicitar recursos con CORS primero. Vuelve a JSONP en navegadores anteriores que no son compatibles con CORS. Si necesita forzar al navegador para que use solo CORS, como con sitios que tienen requisitos de alta seguridad, establezca useCORSOnly:true.

Ejemplo de código


var dilInstance = DIL.create({
     ...
     useCORSOnly: true
});
IMPORTANT
  • Le recomendamos que configure useCORSOnly: true solo cuando esté seguro de que los visitantes del sitio tienen exploradores compatibles con esta característica.
  • Cuando useCORSOnly: true, DIL no hará llamadas de identificador desde Internet Explorer versión 9 o anterior.

useImageRequest useimagerequest

Cambia el tipo de solicitud a la imagen <img> del script <src>.

Firma de función: useImageRequest: function () {}

NOTE
Puede encadenar otras llamadas de API a este método.

Respuesta

Devuelve un objeto API de la instancia actual DIL.

Código de ejemplo


var dataLib = DIL.create({
     partner:'partnerName',
     containerNSID: containerNSID
});

dataLib.api.traits([123, 456, 789]).useImageRequest().submit();
recommendation-more-help
de293fbf-b489-49b0-8daa-51ed303af695