インスタンスレベルの DIL メソッド

警告

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 メソッドの概要

インスタンスレベルの DIL API を操作する場合:

  • アクセスにはパートナー名およびコンテナ名前空間 ID(NSID)が必要になります。担当の Audience Manager アカウントマネージャーにご連絡のうえ、これらの情報を入手してください。
  • サンプルとして提示された API ドキュメント内のすべての​斜体​テキストを、使用するメソッドで必要となる値、ID、または他の変数に置き換えてください。

signals

保留中のリクエストのクエリ文字列に顧客レベルおよびプラットフォームレベルのマッピングを追加します。

関数シグネチャ:signals: function ({key1:value1, key2:value2},prefix){}

メモ
  • 他の 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

保留中のリクエストのクエリ文字列に、SID を追加します。

関数シグネチャ:traits:function (sids){}

メモ

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

メモ

他の 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: function (fn) {}

メモ

他の 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: function () {}

メモ

他の 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: function (obj) {}

メモ

他の 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

DIL インスタンスのコンテナの NSID の値を返します。デバッグおよびトラブルシューティングに役立ちます。

関数シグネチャ:dil.api.getContainerNSID: function () {}

サンプルコード


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

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

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

DIL インスタンスのパートナー名を返します。デバッグおよびトラブルシューティングに役立ちます。

関数シグネチャ:dil.api.getPartner: function () {}

サンプルコード


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

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

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

データパートナー同士、または Audience Manager とユーザー ID を交換および同期するための 2 つの関数で構成されています。

関数シグネチャ:

DIL のバージョン 2.10 および 3.1 以降で使用できます。

コード ユーザー ID の同期
dil.Instance.api.idSync(initConfig)

複数のデータパートナーと Audience Manager の間で実行されます。例えば、パートナー x がこれを使用してユーザー ID をパートナー y と同期し、Audience Manager に送信します。

重要:このメソッドは非推奨(廃止予定)となりました。Adobe Experience Platform ID サービスインスタンスの idSyncByURL メソッドを使用してください。

dil.Instance.api.aamIdSync(initConfig)

ユーザー ID が既に判明していて、それを Audience Manager に送信する場合に使用します。

重要:このメソッドは非推奨(廃止予定)となりました。Adobe Experience Platform ID サービスインスタンスの idSyncByDataSource メソッドを使用してください。

idSync の要素

idSync は次の要素で構成されます。

名前 のタイプ 説明
dpid 文字列

Audience Manager によって割り当てられたデータプロバイダー ID。

dpuuid 文字列

ユーザーに関するデータプロバイダーの一意の ID。

minutesToLive 数値

(オプション) Cookie の有効期限を設定します。整数である必要があります。デフォルトは、20,160 分(14 日)です。

url 文字列

リンク先 URL。

マクロ

idSync では次のマクロを使用できます。

  • %TIMESTAMP% タイムスタンプを生成します(ミリ秒単位)。キャッシュバスティングに使用されます。
  • %DID% ユーザーの Audience Manager ID を挿入します。
  • %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) {}

このコールバックにより、宛先パブリッシングを処理するデフォルトのコールバックが置き換えられます。

メモ

他の 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 は、DIL が Data Collection Servers (DCS) および Akamai に対して呼び出しをおこなう方法を制御するブール型パラメーターです。

  • secureDataCollection= true(デフォルト)の場合、DIL は常に、セキュリティで保護された HTTPS 呼び出しをおこないます。

  • secureDataCollection= false の場合、DIL は、ページで設定されているセキュリティプロトコルに従って、HTTP か HTTPS のどちらかの呼び出しをおこないます。

重要

visitorAPI.js と secureDataCollection= false を同じページで使用する場合は、DIL と設定します。次のコードサンプルを参照してください。


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

useCORSOnly

useCORSOnly は、ブラウザーから他のドメインのリソースをリクエストする方法を制御するための true または false のブール型パラメーターです。

概要

useCORSOnly のデフォルト値は false です。false の場合、ブラウザーは CORS または JSONP でリソースチェックを実行します。ただし、DIL は常に、最初に CORS を使用してリソースをリクエストしようとします。CORS をサポートしていない古いブラウザーでは、JSONP に切り替わります。ブラウザーで必ず CORS のみを使用するように指定する必要がある場合(サイトに厳しいセキュリティ要件がある場合など)は、useCORSOnly:true を設定します。

コードサンプル


var dilInstance = DIL.create({
     ...
     useCORSOnly: true
});
重要
  • サイト訪問者のブラウザーが CORS をサポートしていることが確実な場合にのみ useCORSOnly: true を設定することをお勧めします。
  • useCORSOnly: true の場合、DIL は Internet Explorer 9 またはそれ以前のバージョンからは ID 呼び出しをおこないません。

useImageRequest

リクエストのタイプをスクリプト(<src>)から画像(<img>)に変更します。

関数シグネチャ:useImageRequest: function () {}

メモ

他の API 呼び出しをこのメソッドに連結することができます。

応答

現在の DIL インスタンスの API オブジェクトを返します。

サンプルコード


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

dataLib.api.traits([123, 456, 789]).useImageRequest().submit();

このページ