執行個體層級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檔案中的任何範例​ 斜體化 ​文字取代為您使用的方法所需的值、識別碼或其他變數。

訊號 signals

將客戶和平台層級對應新增至待處理請求的查詢字串。

函式簽章: signals: function ({key1:value1, key2:value2},prefix){}

NOTE
  • 您可以將其他API呼叫鏈結至此方法。
  • 如果頁面上有Adobe Experience Cloud JavaScript資料庫,submit()會先等候雲端設定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

針對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以及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 Manager識別碼。
  • %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