实例级别的DIL方法 instance-level-dil-methods

WARNING
从2023年7月开始,Adobe已停止开发Data Integration Library (DIL)和DIL扩展。
现有客户可以继续使用其DIL实施。 但是,Adobe在此点之后不会开发DIL。 建议客户评估Experience PlatformWeb SDK的长期数据收集策略。
如果客户希望在2023年7月之后实施新的数据收集集成,则应改用Experience PlatformWeb SDK

实例级别DIL API允许您以编程方式创建并处理Audience Manager对象。 实例级方法增强了由类级方法建立的API功能。

实例级别DIL方法快速入门 get-started-dil-methods

使用实例级别DIL API时:

  • 访问需要合作伙伴名称和容器命名空间ID (NSID)。 请联系您的Audience Manager客户经理以获取此信息。
  • 将API文档中的任何示例​ 斜体 ​文本替换为您正在处理的方法所需的值、ID或其他变量。

信号 signals

将客户和平台级别的映射添加到待处理请求的查询字符串。

函数签名: signals: function ({key1:value1, key2:value2},prefix){}

NOTE
  • 您可以将其他API调用链接到此方法。
  • 如果页面上有Adobe Experience Cloud JavaScript库,则在发送请求之前,submit()会等待Cloud设置Cookie。

保留的请求密钥

以下请求键已保留,不能被此方法覆盖:

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

参数

名称
类型
描述
obj
对象
表示平台级别映射的键值对的对象。 参数接受字符串和数组作为对象中的属性值。
prefix
字符串
可选。前缀为每个对象键的字符串值(替换原始键)。
return
DIL.api
返回当前DIL实例的API对象。

响应

返回当前DIL实例的API对象。

示例代码


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

向挂起的请求的查询字符串添加SID。

函数签名: traits:function (sids){}

NOTE
您可以将其他API调用链接到此方法。

参数

名称
类型
描述
sids
数组
数组中的特征区段ID。

响应

返回当前DIL实例的API对象。

示例代码


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

日志 logs

将数据添加到待处理请求中的日志文件。

函数签名: logs: function {key1:value1, key2:value2}

响应

返回当前DIL实例的API对象。

示例代码


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

submit submit

将所有待处理数据提交给DIL实例的Audience Manager。

函数签名: submit: function () {}

NOTE
您可以将其他API调用链接到此方法。 此外,DIL还将编码的数据写入目标Cookie。 例如,空格编码为%20,分号编码为%3B

响应

返回当前DIL实例的API对象。

示例代码


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

在默认目标发布回调之后执行的函数。

函数签名: afterResult: function (fn) {}

NOTE
您可以将其他API调用链接到此方法。

参数

名称
类型
描述
fn
函数
处理目标发布的默认回调处理JSON后要执行的函数。

响应

返回当前DIL实例的API对象。

示例代码


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

清除待处理请求中的所有数据。

函数签名: clearData: function () {}

NOTE
您可以将其他API调用链接到此方法。

响应

返回当前DIL实例的API对象。

示例代码


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

将数据收集服务器未明确定义的自定义查询参数添加到挂起请求中。

函数签名: customQueryParams: function (obj) {}

NOTE
您可以将其他API调用链接到此方法。

保留的请求密钥

以下请求键已保留,不能被此方法覆盖:

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

响应

返回当前DIL实例的API对象。

示例代码


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

getContainerNSID getcontainernsid

返回DIL实例的容器NSID值。 对调试和故障排除非常有用。

函数签名: dil.api.getContainerNSID: function () {}

示例代码


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

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

getEventLog geteventlog

以字符串数组形式返回按时间顺序排序的事件日志数据。 对调试和故障排除非常有用。

函数签名: dil.api.getEventLog: function () {}

示例代码


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

返回DIL实例的合作伙伴名称。 对调试和故障排除非常有用。

函数签名: dil.api.getPartner: function () {}

示例代码


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

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

getState getstate

返回当前DIL实例的状态。 对调试和故障排除非常有用。

函数签名: dil.api.getState: function () {}

示例代码


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

由两个功能组成,允许数据合作伙伴相互交换用户ID并同步用户ID,然后进行Audience Manager。

函数签名:

适用于DIL版本2.10和3.1或更高版本。

代码
同步用户 ID
dil.Instance.api.idSync(initConfig)

在不同的数据合作伙伴和Audience Manager之间。 例如,合作伙伴x将使用此功能将用户ID与合作伙伴y同步,然后将其发送给Audience Manager。

重要信息: 此方法已弃用。 请使用Adobe Experience Platform Identity Service实例的 idSyncByURL 方法。

dil.Instance.api.aamIdSync(initConfig)

当您已经知道用户ID并想要将其发送给Audience Manager时。

重要信息: 此方法已弃用。 请使用Adobe Experience Platform Identity Service实例的 idSyncByDataSource 方法。

idSync元素

idSync可以包含以下内容:

名称
类型
描述
dpid
字符串
Audience Manager 分配的数据提供程序 ID。
dpuuid
字符串
用户的唯一数据提供程序 ID。
minutesToLive
数值
(可选) 设置 Cookie 过期时间。必须为整数。默认值为 20160 分钟(14 天)。
url
字符串
目标 URL。

idSync接受以下宏:

  • %TIMESTAMP% ​生成时间戳(以毫秒为单位)。 用于缓存无效的情况。
  • %DID% ​插入用户的Audience ManagerID。
  • %HTTP_PROTO% ​设置页面协议(httphttps)。

响应

如果运行成功,这两个函数都将返回Successfully queued。 如果失败,则将返回错误消息字符串。

示例代码

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

将回调(接收JSON)添加到待处理请求。

函数签名: result: function (callback) {}

此回调替换了处理目标发布的默认回调。

NOTE
您可以将其他API调用链接到此方法。

参数

名称
类型
描述
callback
函数
由JSONP回调执行的JavaScript函数。

响应

返回当前DIL实例的API对象。

示例代码


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是一个布尔参数,它控制DIL如何调用Data Collection Servers (DCS)和Akamai。

  • secureDataCollection= true (默认)时,DIL始终进行安全的HTTPS调用。

  • secureDataCollection= false时,DIL按照页面设置的安全协议进行HTTP或HTTPS调用。

IMPORTANT
如果您在同一页面上使用visitorAPI.js和DIL,请设置secureDataCollection= false。 请参阅下面的代码示例。

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

useCORSOnly usecorsonly

useCORSOnly是一个布尔值true/false参数,用于控制浏览器如何从其他域请求资源。

概述

默认情况下,useCORSOnly为false。 False表示浏览器可以使用CORS或JSONP执行资源检查。 但是,DIL始终会尝试先通过CORS请求资源。 它会在不支持 CORS 的早期浏览器中还原为 JSONP。如果您需要强制浏览器仅使用CORS(例如,对于具有高安全要求的网站),请设置useCORSOnly:true

代码示例


var dilInstance = DIL.create({
     ...
     useCORSOnly: true
});
IMPORTANT
  • 我们建议仅在您确定网站访客具有支持此功能的浏览器时才设置useCORSOnly: true
  • useCORSOnly: true时,DIL将不会从Internet Explorer版本9或更早版本中进行ID调用。

useImageRequest useimagerequest

将脚本<src>中的请求类型更改为图像<img>

函数签名: useImageRequest: function () {}

NOTE
您可以将其他API调用链接到此方法。

响应

返回当前DIL实例的API对象。

示例代码


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

dataLib.api.traits([123, 456, 789]).useImageRequest().submit();
recommendation-more-help
de293fbf-b489-49b0-8daa-51ed303af695