インスタンスレベルの 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

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

関数シグネチャ: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

保留中のリクエストのログファイルにデータを追加します。

関数シグネチャ: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

データパートナー同士、または 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 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 と secureDataCollection= false を同じページで使用する場合は、DIL と設定します。次のコードサンプルを参照してください。

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
  • サイト訪問者のブラウザーが CORS をサポートしていることが確実な場合にのみ 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