Métodos da DIL em nível de instância

As DIL APIs de nível de instância permitem criar e trabalhar programaticamente com objetos Audience Manager. Os métodos de nível de instância aprimoram a funcionalidade da API estabelecida pelos métodos de nível de classe.

Introdução aos Métodos de DIL de nível de instância

Ao trabalhar com as DIL APIs de nível de instância:

  • O acesso requer um nome de parceiro e uma ID de namespace de container (NSID). Entre em contato com seu gerente de contas de Audience Manager para obter essas informações.
  • Substitua qualquer amostra de texto em itálico na documentação da API por valor, ID ou outra variável, conforme exigido pelo método com o qual você está trabalhando.

sinais

Adiciona mapeamentos no nível do cliente e da plataforma à sequência de query de uma solicitação pendente.

Assinatura da função: signals: function ({key1:value1, key2:value2},prefix){}

Observação
  • Você pode encadear outras chamadas de API para este método.
  • Se a biblioteca do Adobe Experience Cloud JavaScript estiver na página, submit() aguardará que a Cloud defina um cookie antes de enviar uma solicitação.

Chaves de Solicitação Reservadas

As seguintes chaves de solicitação são reservadas e não podem ser substituídas por este método:

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

Parâmetros

Nome Tipo Descrição
obj Objeto Um objeto que representa os pares de valor chave para mapeamentos no nível da plataforma. O parâmetro aceita sequências de caracteres e matrizes como valores de propriedade no objeto.
prefix String Opcional. O valor da string prefixado para cada chave de objeto (substitui a chave original).
return DIL.api Retorna o objeto API da instância DIL atual.

Resposta

Retorna o objeto API da DIL instância atual.

Código de exemplo


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

Adiciona SIDs à sequência de query de uma solicitação pendente.

Assinatura da função: traits:function (sids){}

Observação

Você pode encadear outras chamadas de API para este método.

Parâmetros

Nome Tipo Descrição
sids Matriz IDs de segmento de características em uma matriz.

Resposta

Retorna o objeto API da DIL instância atual.

Código de exemplo


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

logs

Adicione dados aos arquivos de log na solicitação pendente.

Assinatura da função: logs: function {key1:value1, key2:value2}

Resposta

Retorna o objeto API da DIL instância atual.

Código de exemplo


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

submit

Envia todos os dados pendentes para o Audience Manager da DIL instância.

Assinatura da função: submit: function () {}

Observação

Você pode encadear outras chamadas de API para este método. Além disso, DIL grava dados codificados em um cookie de destino. Por exemplo, espaços são codificados como %20 e ponto-e-vírgula como %3B.

Resposta

Retorna o objeto API da DIL instância atual.

Código de exemplo


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

Uma função que é executada após o retorno de chamada de publicação de destino padrão.

Assinatura da função: afterResult: function (fn) {}

Observação

Você pode encadear outras chamadas de API para este método.

Parâmetros

Nome Tipo Descrição
fn Função A função que você deseja executar após o JSON ser processada pelo retorno de chamada padrão que lida com a publicação de destino.

Resposta

Retorna um objeto API da DIL instância atual.

Código de exemplo


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

Limpa todos os dados em uma solicitação pendente.

Assinatura da função: clearData: function () {}

Observação

Você pode encadear outras chamadas de API para este método.

Resposta

Retorna o objeto API da DIL instância atual.

Código de exemplo


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

Adiciona parâmetros de query personalizados que não são explicitamente definidos pelo servidor de coleta de dados a uma solicitação pendente.

Assinatura da função: customQueryParams: function (obj) {}

Observação

Você pode encadear outras chamadas de API para este método.

Chaves de Solicitação Reservadas

As seguintes chaves de solicitação são reservadas e não podem ser substituídas por este método:

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

Resposta

Retorna o objeto API da instância DIL atual.

Código de exemplo


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

getContainerNSID

Retorna o valor do NSID do container para a DIL instância. Útil para depuração e solução de problemas.

Assinatura da função: dil.api.getContainerNSID: function () {}

Código de exemplo


var dataLib = DIL.create({ 
     partner: 'partnerName', 
     containerNSID: containerNSID 
}); 
 
//Verify the container NSID 
var nsid = dataLib.api.getContainerNSID();

getEventLog

Retorna dados do log de eventos classificados cronologicamente como uma matriz de sequências de caracteres. Útil para depuração e solução de problemas.

Assinatura da função: dil.api.getEventLog: function () {}

Código de exemplo


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

Retorna o nome do parceiro para uma DIL instância. Útil para depuração e solução de problemas.

Assinatura da função: dil.api.getPartner: function () {}

Código de exemplo


var dataLib = DIL.create({ 
     partner: 'partnerName' 
     containerNSID: containerNSID 
}); 
 
//Verify the partner name 
var partner = dataLib.api.getPartner();

getState

Retorna o estado da DIL instância atual. Útil para depuração e solução de problemas.

Assinatura da função: dil.api.getState: function () {}

Código de exemplo


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

Consiste em duas funções que permitem que os parceiros de dados troquem e sincronizem IDs de usuário entre si e Audience Manager.

Assinatura da função:

Funciona com DIL as versões 2.10 e 3.1 ou superior.

Código Sincroniza as IDs do usuário
dil.Instance.api.idSync(initConfig)

Entre diferentes parceiros de dados e Audience Manager. Por exemplo, o parceiro x usaria isso para sincronizar uma ID de usuário com o parceiro y e, em seguida, enviá-la para o Audience Manager.

Importante: Este método está obsoleto. Use o idSyncByURL método da instância do Adobe Experience Platform Identity Service.

dil.Instance.api.aamIdSync(initConfig)

Quando você já souber a ID do usuário e quiser enviá-la para a Audience Manager.

Importante: Este método está obsoleto. Use o idSyncByDataSource método da instância do Adobe Experience Platform Identity Service.

elementos idSync

idSync pode consistir no seguinte:

Nome Tipo Descrição
dpid Sequência de caracteres

A ID do provedor de dados atribuída pelo Audience Manager.

dpuuid Sequência de caracteres

A ID exclusiva do provedor de dados para o usuário.

minutesToLive Número

(Opcional) Define o tempo de expiração do cookie. Deve ser um inteiro. O padrão é de 20160 minutos (14 dias).

url Sequência de caracteres

URL de Destino.

Macros

idSync aceita as seguintes macros:

  • %TIMESTAMP%: gera um carimbo de data e hora (em milissegundos). Usado para eliminação de cache.
  • %DID%: insere a ID do Audience Manager para o usuário.
  • %HTTP_PROTO%: Define o protocolo da página ( http ou https).

Resposta

Ambas as funções retornam Successfully queued se bem-sucedidas. Do contrário, elas retornam uma sequência de mensagem de erro.

Código de exemplo

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

result

Adiciona um retorno de chamada (que recebe JSON) à solicitação pendente.

Assinatura da função: result: function (callback) {}

Esse retorno de chamada substitui o retorno de chamada padrão que lida com a publicação de destino.

Observação

Você pode encadear outras chamadas de API para este método.

Parâmetros

Nome Tipo Descrição
callback Função Função JavaScript executada pelo retorno de chamada JSONP.

Resposta

Retorna o objeto API da DIL instância atual.

Código de exemplo


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 é um parâmetro booleano que controla como DIL faz chamadas para o Data Collection Servers (DCS) e o Akamai.

  • Quando secureDataCollection= true (padrão), DIL sempre efetua chamadas HTTPS seguras.

  • Quando secureDataCollection= false, DIL faz chamadas HTTP ou HTTPS seguindo o protocolo de segurança definido pela página.

IMPORTANTE

Defina secureDataCollection= false se você usa visitorAPI.js e DIL na mesma página. Consulte a amostra de código abaixo.


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

useCORSOnly

useCORSOnly é um parâmetro booleano true/false que controla como o navegador solicita recursos de outros domínios.

Visão geral

useCORSOnly é false por padrão. False significa que o navegador pode executar verificações de recursos com CORS ou JSONP. No entanto, DIL sempre tenta solicitar recursos com o CORS primeiro. Em seguida, reverte para JSONP em navegadores antigos sem suporte ao CORS. Se você precisar forçar o navegador a usar somente CORS, como com sites que têm requisitos de alta segurança, defina useCORSOnly:true.

Amostra de código


var dilInstance = DIL.create({ 
     ... 
     useCORSOnly: true 
});
IMPORTANTE
  • Recomendamos que você defina useCORSOnly: true somente quando tiver certeza de que os visitantes do site têm navegadores compatíveis com esse recurso.
  • Quando useCORSOnly: true, DIL não fará chamadas de ID do Internet Explorer versão 9 ou anterior.

useImageRequest

Altera o tipo de solicitação para imagem <img> do script <src>.

Assinatura da função: useImageRequest: function () {}

Observação

Você pode encadear outras chamadas de API para este método.

Resposta

Retorna um objeto API da DIL instância atual.

Código de exemplo


var dataLib = DIL.create({ 
     partner:'partnerName', 
     containerNSID: containerNSID 
}); 
 
dataLib.api.traits([123, 456, 789]).useImageRequest().submit();

Nesta página