文件 Audience Manager Audience Manager 使用手冊

執行個體層級DIL方法 instance-level-dil-methods

Last update: Sat Jul 20 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

主題：
DIL 實施

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%： 設定頁面通訊協定（ http或https）。

回應

如果成功，兩個函式都會傳回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