Metodi DIL a livello di istanza

Le API DIL a livello di istanza consentono di creare e utilizzare in modo programmatico oggetti Audience Manager. I metodi a livello di istanza migliorano la funzionalità API stabilita dai metodi a livello di classe.

Guida introduttiva ai metodi DIL a livello di istanza

Quando si lavora con le API a livello di istanza DIL:

  • L'accesso richiede un nome partner e un ID spazio nomi contenitore (NSID). Contattate il vostro responsabile commerciale Audience Manager per ottenere queste informazioni.
  • Sostituite il testo di esempio corsivo nella documentazione API con valore, ID o altra variabile, come richiesto dal metodo utilizzato.

segnali

Aggiunge mappature a livello di cliente e piattaforma alla stringa di query di una richiesta in sospeso.

Firma funzione: signals: function ({key1:value1, key2:value2},prefix){}

NOTA
  • Potete catena altre chiamate API a questo metodo.
  • Se la libreria Adobe Experience Cloud JavaScript si trova sulla pagina, submit() attende che il Cloud imposti un cookie prima di inviare una richiesta.

Chiavi richieste riservate

Le seguenti chiavi di richiesta sono riservate e non possono essere sovrascritte con questo metodo:

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

Parametri

Nome Tipo Descrizione
obj Oggetto Un oggetto che rappresenta le coppie chiave-valore per le mappature a livello di piattaforma. Il parametro accetta stringhe e array come valori di proprietà nell'oggetto.
prefix Stringa Facoltativo. Il valore della stringa con il prefisso di ogni chiave di oggetto (sostituisce la chiave originale).
return DIL.api Restituisce l'oggetto API dell'istanza DIL corrente.

Risposta

Restituisce l'oggetto API dell'istanza corrente DIL.

Codice di esempio


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

Aggiunge i SID alla stringa di query di una richiesta in sospeso.

Firma funzione: traits:function (sids){}

NOTA

Potete catena altre chiamate API a questo metodo.

Parametri

Nome Tipo Descrizione
sids Array ID segmento caratteristica in un array.

Risposta

Restituisce l'oggetto API dell'istanza corrente DIL.

Codice di esempio


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

log

Aggiungere dati ai file di registro nella richiesta in sospeso.

Firma funzione: logs: function {key1:value1, key2:value2}

Risposta

Restituisce l'oggetto API dell'istanza corrente DIL.

Codice di esempio


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

submit

Invia tutti i dati in sospeso al Audience Manager per l'istanza DIL.

Firma funzione: submit: function () {}

NOTA

Potete catena altre chiamate API a questo metodo. Inoltre, DIL scrive dati codificati in un cookie di destinazione. Ad esempio, gli spazi sono codificati come %20 e i punti e virgola come %3B.

Risposta

Restituisce l'oggetto API dell'istanza corrente DIL.

Codice di esempio


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

Funzione che viene eseguita dopo il callback di pubblicazione di destinazione predefinito.

Firma funzione: afterResult: function (fn) {}

NOTA

Potete catena altre chiamate API a questo metodo.

Parametri

Nome Tipo Descrizione
fn Funzione La funzione che si desidera eseguire dopo JSON viene elaborata dal callback predefinito che gestisce la pubblicazione delle destinazioni.

Risposta

Restituisce un oggetto API dell'istanza corrente DIL.

Codice di esempio


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

Cancella tutti i dati in una richiesta in sospeso.

Firma funzione: clearData: function () {}

NOTA

Potete catena altre chiamate API a questo metodo.

Risposta

Restituisce l'oggetto API dell'istanza corrente DIL.

Codice di esempio


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

Aggiunge a una richiesta in sospeso parametri di query personalizzati non definiti in modo esplicito dal server di raccolta dati.

Firma funzione: customQueryParams: function (obj) {}

NOTA

Potete catena altre chiamate API a questo metodo.

Chiavi richieste riservate

Le seguenti chiavi di richiesta sono riservate e non possono essere sovrascritte con questo metodo:

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

Risposta

Restituisce l'oggetto API dell'istanza DIL corrente.

Codice di esempio


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

getContainerNSID

Restituisce il valore del NSID contenitore per l'istanza DIL. Utile per il debug e la risoluzione dei problemi.

Firma funzione: dil.api.getContainerNSID: function () {}

Codice di esempio


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

getEventLog

Restituisce i dati del registro eventi ordinati cronologicamente come un array di stringhe. Utile per il debug e la risoluzione dei problemi.

Firma funzione: dil.api.getEventLog: function () {}

Codice di esempio


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

Restituisce il nome del partner per un'istanza DIL. Utile per il debug e la risoluzione dei problemi.

Firma funzione: dil.api.getPartner: function () {}

Codice di esempio


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

getState

Restituisce lo stato dell'istanza corrente DIL. Utile per il debug e la risoluzione dei problemi.

Firma funzione: dil.api.getState: function () {}

Codice di esempio


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

È composta da due funzioni che consentono ai partner di dati di scambiare e sincronizzare gli ID utente tra loro e Audience Manager.

Firma funzione:

Funziona con le versioni DIL 2.10 e 3.1 o successive.

Codice Sincronizza gli ID utente
dil.Instance.api.idSync(initConfig)

Tra partner di dati diversi e Audience Manager . Ad esempio, il partner x lo utilizza per sincronizzare un ID utente con il partner y e inviarlo al Audience Manager .

Importante: questo metodo è obsoleto. Utilizzare il metodo idSyncByURL dell'istanza di Adobe Experience Platform Identity Service.

dil.Instance.api.aamIdSync(initConfig)

Quando si conosce già l'ID utente e si desidera inviarlo Audience Manager.

Importante: questo metodo è obsoleto. Utilizzare il metodo idSyncByDataSource dell'istanza di Adobe Experience Platform Identity Service.

idSync Elements

idSync può essere costituito dai seguenti elementi:

Nome Tipo Descrizione
dpid Stringa

ID del fornitore dei dati assegnato da Audience Manager.

dpuuid Stringa

ID univoco del fornitore di dati per l'utente.

minutesToLive Numero

(Facoltativo) Imposta la data di scadenza del cookie. Deve essere un numero intero. Impostazione predefinita: 20160 minuti (14 giorni).

url Stringa

URL di destinazione.

Macro

idSync accetta le macro seguenti:

  • %TIMESTAMP%: genera una marca temporale (in millisecondi). Utilizzato per svuotare la cache.
  • %DID%: inserisce l'ID di Audience Manager per l'utente.
  • %HTTP_PROTO%: Imposta il protocollo di pagina ( http o https).

Risposta

Entrambe le funzioni restituiscono Successfully queued in caso di esito positivo. In caso di esito negativo, restituiscono la stringa di un messaggio di errore.

Codice di esempio

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

risultato

Aggiunge un callback (che riceve JSON) alla richiesta in sospeso.

Firma funzione: result: function (callback) {}

Questo callback sostituisce il callback predefinito che gestisce la pubblicazione delle destinazioni.

NOTA

Potete catena altre chiamate API a questo metodo.

Parametri

Nome Tipo Descrizione
callback Funzione Funzione JavaScript eseguita dal callback JSONP.

Risposta

Restituisce l'oggetto API dell'istanza corrente DIL.

Codice di esempio


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 è un parametro booleano che controlla il modo in cui DIL effettua le chiamate a Data Collection Servers (DCS) e Akamai.

  • Quando secureDataCollection= true (predefinito), DIL effettua sempre chiamate HTTPS sicure.

  • Quando secureDataCollection= false, DIL effettua chiamate HTTP o HTTPS seguendo il protocollo di sicurezza impostato dalla pagina.

IMPORTANTE

Impostate secureDataCollection= false se utilizzate visitorAPI.js e DIL sulla stessa pagina. Vedi l’esempio di codice riportato di seguito.


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

useCORSOnly

useCORSOnly è un parametro booleano true/false che controlla come il browser richiede risorse da altri domini.

Panoramica

useCORSOnly è false per impostazione predefinita. False indica che il browser può eseguire controlli delle risorse con CORS o JSONP. Tuttavia, [!UICONTROL DIL] tenta sempre di richiedere le risorse prima con CORS. Se necessario, utilizza JSONP per i browser più datati che non supportano CORS. Se dovete obbligare il browser a utilizzare solo CORS, ad esempio con siti con requisiti di sicurezza elevati, impostate useCORSOnly:true.

Esempio di codice


var dilInstance = DIL.create({ 
     ... 
     useCORSOnly: true 
});
IMPORTANTE
  • È consigliabile impostare useCORSOnly: true solo quando si è certi che i visitatori del sito dispongono di browser che supportano questa funzione.
  • Se useCORSOnly: true, DIL non effettua chiamate ID da Internet Explorer versione 9 o versioni precedenti.

useImageRequest

Cambia il tipo di richiesta in immagine <img> dallo script <src>.

Firma funzione: useImageRequest: function () {}

NOTA

Potete catena altre chiamate API a questo metodo.

Risposta

Restituisce un oggetto API dell'istanza corrente DIL.

Codice di esempio


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

In questa pagina