Instance-level DIL Methods

The instance-level DIL APIs let you programmatically create and work with Audience Manager objects. The instance-level methods enhance API functionality established by the class-level methods.

Getting started with Instance-level DIL Methods

When working with the instance-level DIL APIs:

• Access requires a partner name and container namespace ID (NSID). Contact your Audience Manager account manager to obtain this information.
• Replace any sample italicized text in the API documentation with value, ID, or other variable as required by the method you’re working with.

signals

Adds customer and platform-level mappings to the query string of a pending request.

Function Signature: signals: function ({key1:value1, key2:value2},prefix){}

Reserved Request Keys

The following request keys are reserved and cannot be overwritten by this method:

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

Parameters

Response

Returns the API object of the current DIL instance.

Sample Code

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

Adds SIDs to the query string of a pending request.

Function signature: traits:function (sids){}

Parameters

Response

Returns the API object of the current DIL instance.

Sample Code

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

logs

Add data to log files in the pending request.

Function signature: logs: function {key1:value1, key2:value2}

Response

Returns the API object of the current DIL instance.

Sample Code

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

submit

Submits all pending data to Audience Manager for the DIL instance.

Function Signature: submit: function () {}

Response

Returns the API object of the current DIL instance.

Sample Code

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

A function that executes after the default destination publishing callback.

Function Signature: afterResult: function (fn) {}

Parameters

Response

Returns an API object of the current DIL instance.

Sample Code

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

Clears all data in a pending request.

Function Signature: clearData: function () {}

Response

Returns the API object of the current DIL instance.

Sample Code

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

Adds custom query parameters that are not explicitly defined by the data collection server to a pending request.

Function Signature: customQueryParams: function (obj) {}

Reserved Request Keys

The following request keys are reserved and cannot be overwritten by this method:

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

Response

Returns the API object of the current DIL instance.

Sample Code

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

getContainerNSID

Returns the value of the container NSID for the DIL instance. Useful for debugging and troubleshooting.

Function Signature: dil.api.getContainerNSID: function () {}

Sample Code

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

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

getEventLog

Returns chronologically sorted event log data as an array of strings. Useful for debugging and troubleshooting.

Function Signature: dil.api.getEventLog: function () {}

Sample Code

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

Returns the partner name for a DIL instance. Useful for debugging and troubleshooting.

Function Signature: dil.api.getPartner: function () {}

Sample Code

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

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

getState

Returns the state of the current DIL instance. Useful for debugging and troubleshooting.

Function Signature: dil.api.getState: function () {}

Sample Code

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

Consists of two functions that let data partners exchange and synchronize user IDs among themselves and Audience Manager.

Function Signature:

Works with DIL versions 2.10 and 3.1 or higher.

idSync Elements

idSync can consist of the following:

Macros

idSync accepts the following macros:

• %TIMESTAMP%: Generates a timestamp (in milliseconds). Used for cache busting.
• %DID%: Inserts the Audience Manager ID for the user.
• %HTTP_PROTO%: Sets the page protocol ( http or https).

Response

Both functions return Successfully queued if successful. They return an error message string if not.

Sample Code

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

Adds a callback (that receives JSON) to the pending request.

Function Signature: result: function (callback) {}

This callback replaces the default callback that handles destination publishing.

Parameters

Response

Returns the API object of the current DIL instance.

Sample Code

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 is a boolean parameter that controls how DIL makes calls to the Data Collection Servers (DCS) and Akamai.

• When secureDataCollection= true (default), DIL always makes secure, HTTPS calls.

• When secureDataCollection= false, DIL makes either HTTP or HTTPS calls by following the security protocol set by the page.

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

useCORSOnly

useCORSOnly is a boolean true/false parameter that controls how the browser requests resources from other domains.

Overview

useCORSOnly is false by default. False means the browser can perform resource checks with CORS or JSONP. However, DIL always tries to request resources with CORS first. It reverts to JSONP on older browsers that do not support CORS. If you need to force the browser to use CORS only, such as with sites that have high-security requirements, set useCORSOnly:true.

Code Sample

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

useImageRequest

Changes the request type to image <img> from script <src>.

Function Signature: useImageRequest: function () {}

Response

Returns an API object of the current DIL instance.

Sample Code

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

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