Documentation Audience Manager Audience Manager User Guide

Instance-level DIL Methods

Last update: Wed Aug 02 2023 00:00:00 GMT+0000 (Coordinated Universal Time)

Topics:
DIL Implementation

WARNING

Beginning in July 2023, Adobe has discontinued the development of the Data Integration Library (DIL) and the DIL extension.

Existing customers can continue using their DIL implementation. However, Adobe will not be developing DIL beyond this point. Customers are encouraged to evaluate Experience Platform Web SDK for their long term data collection strategy.

Customers looking to implement new data collection integrations after July 2023 should use Experience Platform Web SDK instead.

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

NOTE

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

NOTE

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 () {}

NOTE

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

NOTE

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 () {}

NOTE

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

NOTE

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 Adobe Experience Platform Identity 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 Adobe Experience Platform Identity 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.

NOTE

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.

IMPORTANT

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

IMPORTANT

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 () {}

NOTE

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

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