Show Menu
TOPICS×

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){}
  • You can chain other API calls to this method.
  • If the Adobe Experience Cloud JavaScript library is on the page, submit() waits for the Cloud to set a cookie before sending a request.
Reserved Request Keys
The following request keys are reserved and cannot be overwritten by this method:
  • sids
  • pdata
  • logdata
  • callback
  • postCallbackFn
  • useImageRequest
Parameters
Name
Type
Description
obj
Object
An object representing the key-value pairs for platform-level mappings. Parameter accepts strings and arrays as property values in the object.
prefix
String
Optional. The string value prefixed to each object key (replaces original key).
return
DIL.api
Returns the API object of the current DIL instance.
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){}
You can chain other API calls to this method.
Parameters
Name
Type
Description
sids
Array
Trait segment IDs in an array.
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 () {}
You can chain other API calls to this method. Also, DIL writes encoded data to a destination cookie. For example, spaces are encoded as %20 and semicolons as %3B .
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) {}
You can chain other API calls to this method.
Parameters
Name
Type
Description
fn
Function
The function you want to execute after JSON is processed by the default callback that handles destination publishing.
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 () {}
You can chain other API calls to this method.
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) {}
You can chain other API calls to this method.
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.
Code Synchronizes User IDs
dil.Instance.api.idSync(initConfig)
Between different data partners and Audience Manager. For example, partner x would use this to synchronize a user ID with partner y and then send that to Audience Manager.
Important: This method is deprecated. Please use the idSyncByURL method of the Experience Cloud ID Service instance.
dil.Instance.api.aamIdSync(initConfig)
When you already know the user ID and want to send it to Audience Manager.
Important: This method is deprecated. Please use the idSyncByDataSource method of the Experience Cloud ID Service instance.
idSync Elements
idSync can consist of the following:
Name Type Description
dpid String
Data provider ID assigned by Audience Manager.
dpuuid String
The data provider's unique ID for the user.
minutesToLive Number
(Optional) Sets the cookie expiration time. Must be an integer. Default is 20160 minutes (14 days).
url String
Destination URL.
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.
You can chain other API calls to this method.
Parameters
Name
Type
Description
callback
Function
JavaScript function executed by the JSONP callback.
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.
Set secureDataCollection= false if you use visitorAPI.js and DIL on the same page. See the code sample below.
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 
});


  • We recommend that you set useCORSOnly: true only when you're sure that your site visitors have browsers that support this feature.
  • When useCORSOnly: true , DIL will not make ID calls from Internet Explorer version 9 or older.

useImageRequest

Changes the request type to image <img> from script <src> .
Function Signature: useImageRequest: function () {}
You can chain other API calls to this method.
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();