Documentação Audience Manager Guia do usuário do Audience Manager

Métodos de DIL em nível de instância instance-level-dil-methods

Last update: Sat Jul 20 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

Tópicos:
Implementação de DIL

WARNING

A partir de julho de 2023, o Adobe descontinuou o desenvolvimento da extensão Data Integration Library (DIL) e DIL.

Os clientes existentes podem continuar usando a implementação DIL. Entretanto, o Adobe não desenvolverá DIL além deste ponto. Os clientes são incentivados a avaliar o SDK da Web do Experience Platform para sua estratégia de coleta de dados de longo prazo.

Os clientes que desejam implementar novas integrações de coleção de dados após julho de 2023 devem usar o SDK da Web do Experience Platform.

As APIs do DIL no nível da instância permitem que você crie e trabalhe 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 em nível de instância get-started-dil-methods

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

O Access exige um nome de parceiro e uma ID de namespace de contêiner (NSID). Entre em contato com o gerente de conta do Audience Manager para obter essas informações.
Substitua qualquer texto de amostra 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 signals

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

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

NOTE

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

Chaves de solicitação reservadas

As chaves de solicitação a seguir estã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 valores chave para mapeamentos no nível da plataforma. O parâmetro aceita strings e matrizes como valores de propriedade no objeto.

prefix

String

Opcional. O valor da string prefixado para cada chave do objeto (substitui a chave original).

return

DIL.api

Retorna o objeto de API da instância DIL atual.

Resposta

Retorna o objeto de API da instância DIL 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 traits

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

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

NOTE

Você pode encadear outras chamadas de API a esse método.

Parâmetros

Nome

Tipo

Descrição

sids

Matriz

IDs de segmento de característica em uma matriz.

Resposta

Retorna o objeto de API da instância DIL atual.

Código de exemplo


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

logs logs

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

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

Resposta

Retorna o objeto de API da instância DIL 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 submit

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

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

NOTE

Você pode encadear outras chamadas de API a esse 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 de API da instância DIL 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 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) {}

NOTE

Você pode encadear outras chamadas de API a esse método.

Parâmetros

Nome

Tipo

Descrição

fn

Função

A função que você deseja executar depois que o JSON é processado pelo retorno de chamada padrão que lida com a publicação de destino.

Resposta

Retorna um objeto de API da instância DIL 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 cleardata

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

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

NOTE

Você pode encadear outras chamadas de API a esse método.

Resposta

Retorna o objeto de API da instância DIL 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 customqueryparams

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

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

NOTE

Você pode encadear outras chamadas de API a esse método.

Chaves de solicitação reservadas

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

sids
pdata
logdata
callback
postCallbackFn
useImageRequest

Resposta

Retorna o objeto de 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 getcontainernsid

Retorna o valor da NSID do contêiner da instância DIL. Ú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 geteventlog

Retorna dados do log de eventos classificados cronologicamente como uma matriz de cadeias 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 getpartner

Retorna o nome do parceiro de uma instância DIL. Ú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 getstate

Retorna o estado da instância DIL 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 idsync

Consiste em duas funções que permitem aos parceiros de dados trocar e sincronizar IDs de usuário entre eles e o Audience Manager.

Assinatura da Função:

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

Código

Sincroniza as IDs do usuário

dil.Instance.api.idSync(initConfig)

Entre os diferentes parceiros de dados e o Audience Manager. Por exemplo, o parceiro x usaria essa opção para sincronizar uma ID de usuário com o parceiro y e enviá-la para o Audience Manager.

Importante: este método foi preterido. Use o método idSyncByURL da instância do Adobe Experience Platform Identity Service.

dil.Instance.api.aamIdSync(initConfig)

Quando você já conhece a ID de usuário e deseja enviá-la para o Audience Manager.

Importante: este método foi preterido. Use o método idSyncByDataSource da instância do Adobe Experience Platform Identity Service.

Elementos de 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 única 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/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)
});

resultado 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.

NOTE

Você pode encadear outras chamadas de API a esse método.

Parâmetros

Nome

Tipo

Descrição

callback

Função

Função JavaScript executada pelo retorno de chamada JSONP.

Resposta

Retorna o objeto de API da instância DIL 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

secureDataCollection é um parâmetro booleano que controla como DIL faz chamadas para Data Collection Servers (DCS) e Akamai.

Quando secureDataCollection= true (padrão), DIL sempre faz chamadas HTTPS seguras.
Quando secureDataCollection= false, DIL faz chamadas HTTP ou HTTPS seguindo o protocolo de segurança definido pela página.

IMPORTANT

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


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

useCORSOnly usecorsonly

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

Visão geral

useCORSOnly é falso por padrão. Falso 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 for necessário forçar o navegador para usar somente o CORS, como em sites com requisitos de alta segurança, defina useCORSOnly:true.

Amostra de código


var dilInstance = DIL.create({
     ...
     useCORSOnly: true
});

IMPORTANT

Recomendamos que você defina o useCORSOnly: true somente quando tiver certeza de que os visitantes do site têm navegadores que oferecem suporte a esse recurso.
Quando useCORSOnly: true, DIL não fará chamadas de ID do Internet Explorer versão 9 ou posterior.

useImageRequest useimagerequest

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

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

NOTE

Você pode encadear outras chamadas de API a esse método.

Resposta

Retorna um objeto de API da instância DIL atual.

Código de exemplo


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

dataLib.api.traits([123, 456, 789]).useImageRequest().submit();

recommendation-more-help

de293fbf-b489-49b0-8daa-51ed303af695