Treasure Data JavaScript SDK(TD JS SDK)を使用すると、Treasure AIはお客様のドメインのウェブサイトにfirst-party cookieを保存し、ウェブサイトのユーザーを他のプラットフォーム全体で追跡して情報を収集できます。TD JS SDKを使用すれば、ウェブサイトのアクティビティを追跡するためにサーバー側に何もインストールする必要はありません。

TD JS SDKの現在のバージョンは次のとおりです。

• 4.4: https://cdn.treasuredata.com/sdk/4.4/td.min.js でホストされています
• 3.1: https://cdn.treasuredata.com/sdk/3.1/td.min.js でホストされています

• JavaScriptとHTMLの基本的な知識
• Treasure AIの基本的な知識
• Treasure AIのWrite-Only APIキー
• Treasure AIアカウントに作成済みのデータベースとテーブル
• お使いのリージョンに固有のサイトとエンドポイント

JavaScript SDKからのインポートには、IP Allowlistは適用されません。

ウェブブラウザは、無効なタイムスタンプ(1970/01/01など)を指定することがよくあります。そのため、タイムスタンプが7日より古いログ、または現在の日付より3日以上先のログは無視されます。

カスタムビルドしたJavaScript SDKを、お客様のウェブサイトまたは任意のCDNでホストできます。このクイックスタートでは、事前にビルドされ一般公開されているバージョンを使用します。

以下から適切なJavaScriptスニペットをコピーし、ページの<head>タグに貼り付けて、td-js-sdkをページにインストールします。

<script type="text/javascript">
!function(t,e){if(void 0===e[t]){e[t]=function(){e[t].clients.push(this),this._init=[Array.prototype.slice.call(arguments)]},e[t].clients=[];for(var r=["addRecord","blockEvents","fetchServerCookie","fetchGlobalID","fetchUserSegments","resetUUID","ready","setSignedMode","setAnonymousMode","set","trackEvent","trackPageview","trackClicks","unblockEvents"],s=0;s<r.length;s++){var c=r[s];e[t].prototype[c]=function(t){return function(){return this["_"+t]=this["_"+t]||[],this["_"+t].push(Array.prototype.slice.call(arguments)),this}}(c)}var n=document.createElement("script");n.type="text/javascript",n.async=!0,n.src=("https:"===document.location.protocol?"https:":"http:")+"//cdn.treasuredata.com/sdk/4.4/td.min.js";var o=document.getElementsByTagName("script")[0];o.parentNode.insertBefore(n,o)}}("Treasure",this);
</script>

<script type="text/javascript">
!function(t,e){if(void 0===e[t]){e[t]=function(){e[t].clients.push(this),this._init=[Array.prototype.slice.call(arguments)]},e[t].clients=[];for(var r=["addRecord","blockEvents","fetchServerCookie","fetchGlobalID","fetchUserSegments","resetUUID","ready","setSignedMode","setAnonymousMode","set","trackEvent","trackPageview","trackClicks","unblockEvents"],s=0;s<r.length;s++){var c=r[s];e[t].prototype[c]=function(t){return function(){return this["_"+t]=this["_"+t]||[],this["_"+t].push(Array.prototype.slice.call(arguments)),this}}(c)}var n=document.createElement("script");n.type="text/javascript",n.async=!0,n.src=("https:"===document.location.protocol?"https:":"http:")+"//cdn.treasuredata.com/sdk/3.1/td.min.js";var o=document.getElementsByTagName("script")[0];o.parentNode.insertBefore(n,o)}}("Treasure",this);
</script>

CommonJSを使用してTreasureクラスをエクスポートします。

npm install --save td-js-sdk

エントリポイントはlib/treasure.jsです。このエントリポイントは、BrowserifyやWebpackなどのビルドツールで使用できます。

var Treasure = require('td-js-sdk')

TD JS SDKは、SDKのインスタンスごとにデータベースとテーブルを作成し、それらのテーブルにデータを送信します。TD JS SDKをインストールした後、次のようなコードで初期化します。

// データベース用のインスタンスを設定します
var td = new Treasure({
  host: 'YOUR_REGION.records.in.treasuredata.com',
  writeKey: 'YOUR_WRITE_ONLY_APIKEY_IS_HERE',
  database: 'DATABASE_NAME'
});

管理者の場合、データベースは自動的に作成されます。管理者でない場合は、管理者にデータベースの作成と、そのデータベースへのimport onlyまたはfull accessの権限付与を依頼する必要があります。これらの権限がないと、イベントを送信できません。

オブジェクトを初期化した後、Treasure AIにイベントを送信できます。完全にカスタマイズしたイベントレコードには、addRecord関数を使用します。たとえば、次のようなコードでイベントを記録できます。

// データベース用のインスタンスを設定します
var company = new Treasure({...});

// 送信したいプロパティを持つデータオブジェクトを作成します
var sale = {
  itemId: 101,
  saleId: 10,
  userId: 1
};

// 'sales'テーブルに送信します
company.addRecord('sales', sale);

イベントはいくつでも送信できます。各イベントは非同期で送信されます。

TD JS SDKは、ページインプレッションとイベント、およびクライアント情報を追跡する手段を提供します。

各クライアントにはUUIDが必要です。設定オブジェクトでclientIdを設定すると、明示的に指定できます。指定しない場合、TD JS SDKは以前に設定されたUUIDをcookieから検索します。見つからない場合は、UUIDが生成されます。

セッションをまたいでクライアントを追跡するために、cookieが設定されます。

ページインプレッションを追跡するには、次のようなコードを使用します。

/* JavaScriptスニペットをここに挿入します */
var td = new Treasure({...});

// クロスドメイン追跡を有効化します
td.set('$global', 'td_global_id', 'td_global_id');

// ページビュー情報を'pageviews'テーブルに追跡します
td.trackPageview('pageviews');

これにより、追跡したすべての情報がpageviewsテーブルに送信されます。

カスタムパラメータを設定するには、td.set()関数を使用します。

// ページビュー情報を'pageviews'テーブルに追跡します
td.set('pageviews', {foo: 'foo', bar: 'bar'});
td.trackPageview('pageviews');

ページビューの追跡に加えて、trackEvent()関数を使用してカスタムイベントを追跡できます。構文はaddRecordと似ていますが、trackEventは追跡したすべての情報を取得します。次の例では、buttonがイベントを記録するテーブルの名前です。イベントには、追加の情報とコンテキストを引数として渡せます。

var td = new Treasure({});

var buttonEvent1 = function () {
  td.trackEvent('button', {
    number: 1
  });

  // doButtonEvent(1);
};

var buttonEvent2 = function () {
  td.trackEvent('button', {
    number: 2
  });

  // doButtonEvent(2);
};

各イベントは非同期で送信されます。

さまざまな地域のデータプライバシー規制、特にGDPRに準拠するため、Treasure Data JavaScript SDKはデフォルトで匿名モードで動作します。匿名モードでは、個人を特定できる特定のイベントメタデータは収集されません。具体的には、匿名モードではデフォルトで次の情報は収集されません。

• td_ip - リクエストのIPアドレス(サーバー側で追加)
• td_client_id - クライアントのUUID(first-party cookie。匿名IDを参照)
• td_global_id - クライアントのUUID(third-party cookie。匿名IDを参照)

個々のユーザーを追跡し、ユーザーセッション内およびセッションをまたいでデータを分析したい場合や、追跡した行動を実在の個人に関連付けたい場合などには、td_client_idとtd_global_idが必要です。

個人情報を収集するかどうかは、社内のデータプライバシー責任者および法務顧問とデータ収集ポリシーを確認して判断する必要があります。個人の追跡を有効化する場合は、同意管理システムと連携して、追跡に対する各ユーザーのオプトインを記録することを推奨します。ユーザーの同意を確認できたら、JS SDKの署名モードを有効化して、これらの属性をイベントとともに取得できます。

td.setSignedMode()

追跡関数を呼び出すたびに、次の情報が送信されます。

td_ipを除くすべてのサーバー側の値は、ユーザーエージェント文字列を解析して取得されます。この処理は、常に最新の状態を保てるようにサーバー側で行われます。

Treasure#setを使用すると、テーブルにデフォルト値を設定できます。テーブル名として$globalを渡すと、すべてのテーブルにデフォルト値を設定できます。

Treasure#getにテーブル名$globalを渡すと、すべてのグローバルプロパティを確認できます。

レコードを送信すると、空のレコードオブジェクトが作成され、次の順序でプロパティが適用されます。

1. $globalのプロパティがrecordオブジェクトに適用されます
2. テーブルのプロパティがrecordオブジェクトに適用され、$globalのプロパティを上書きします
3. addRecord関数に渡したレコードのプロパティがrecordオブジェクトに適用され、テーブルのプロパティを上書きします

Meta Click IDなどのサードパーティタグは、ユーザーが広告コンテンツ経由でお客様のウェブサイトにアクセスしたときに、cookieまたはリクエストパラメータとしてウェブサイトに埋め込まれる場合があります。JS SDK 4.1以降では、collectTagsを使用してこれらのタグを収集できます。

td.collectTags(
  {
    vendors: ['google_ads', 'google_mp', 'meta', 'x'],
    cookies: ['_cookie_a', '_cookie_b'],
    params: ['param_a', 'param_b']
  },
  {
    gclPrefix: '_gcl2'
  }
)

サポートされているベンダー名の一覧は、JS-SDKによるサードパーティのコンバージョンタグの収集を参照してください。

Treasure Data JavaScript SDKは、EUのGDPRで求められる多くの一般的な要件への準拠を可能にします。より新しく厳格なデータプライバシーポリシーへの準拠を支援するため、いくつかのメソッドが用意されています。

• blockEvents / unblockEvents - Treasure AIへのイベント送信をすべて停止、または再開する引数なしのメソッドです。指定すると、メッセージは送信されず、呼び出しもキャッシュされません。デフォルトでは、イベントはブロックされていません。これらのメソッドのドキュメントを参照してください。

  • blockEvents
  • unblockEvents
  • areEventsBlocked

• setSignedMode - 「署名モード」に切り替える引数なしのメソッドです。署名モードでは、SDKが一部のPIIを自動的に収集する場合があります。指定すると、Treasure AIに送信されるデータにtd_ip、td_client_id、td_global_idが含まれます。setSignedModeのドキュメントを参照してください。

• setAnonymousMode - 「匿名モード」に切り替える引数なしのメソッドです。匿名モードでは、SDKはPIIを自動的に収集しません。指定すると、送信されるデータからtd_ip、td_client_id、td_global_idが明示的に除外されます。これがデフォルトの動作です。setAnonymousModeのドキュメントを参照してください。

• resetUUID - td_client_idの値をリセットするメソッドです。ユーザーのcookieに保存されている元の値が上書きされるため、データ上ではまったく新しいユーザーとして表示される可能性が高くなります。リセット時に適切な値を渡すと、クライアントIDやカスタムの有効期限を指定できます。resetUUIDのドキュメントを参照してください。

• config.startInSignedMode - この設定オプションは、ユーザーが署名モードと匿名モードのどちらを希望するかが明示的に決まっていない場合に、署名モードをデフォルトにするようSDKに指示します。デフォルトの動作では、ユーザーは匿名モードになります。

新しいユーザーがサイトにアクセスし、そのユーザーがマーケティング目的のcookie追跡に同意しているかを確認する必要があるとします。お客様はこの情報を管理するために同意管理ベンダーと契約しており、ユーザーの同意情報がわかった時点で適切な値を設定したいと考えています。

var td = new Treasure({
  database: 'foo',
  writeKey: 'your_write_only_key'
});
td.trackClicks()

var successConsentCallback = function (consented) {
  if (consented) {
    td.setSignedMode()
  } else {
    td.setAnonymousMode()
  }
}

var failureConsentCallback = function () {
  // エラーが発生し、同意状況が不明です
  td.setAnonymousMode()
}

ConsentManagementVendor.getConsent(userId, successConsentCallback, failureConsentCallback)

このシナリオでは、同意管理ベンダーは、userIdに関連付けられたユーザーが自分のPIIをマーケティング目的で使用することに同意しているかどうかに基づいて、コールバックでtrueまたはfalseの値を返します。PII以外のデータは引き続き収集される場合があります。

次に、同意管理ベンダーが同意レベルに応じてMARKETING、NON-MARKETING、REFUSEDの文字列を返すとします。それぞれ「PIIのマーケティング目的での使用に同意」「マーケティング以外の目的でのデータ収集に同意」「すべてのデータ収集を拒否」を意味します。この場合、successConsentCallbackをわずかに変更するだけで対応できます。

var successConsentCallback = function (consented) {
  if (consented === 'MARKETING') {
    td.unblockEvents()
    td.setSignedMode()
  } else if (consented === 'NON-MARKETING') {
    td.unblockEvents()
    td.setAnonymousMode()
  } else if (consented === 'REFUSED') {
    td.blockEvents()
  }
}

このようにすると、署名モードまたは匿名モードに移行したときに、実際にTreasure AIにデータが収集されていることを確認できます。顧客がすべての追跡を拒否した場合、そのイベントはブロックされ、この状態はページを再読み込みしても保持されます。

ChromeとFirefoxの最近のリリースでは、新しいsecure-by-defaultのcookie分類システムが適用されるようになり、SameSite値が宣言されていないcookieはSameSite=Laxのcookieとして扱われます。サードパーティのコンテキストで使用できるのは、SameSite=None; Secureとして設定されたcookieのみで、安全な接続からアクセスされる場合に限られます。

JS SDK 2.4.2より前のバージョンでは、td_client_idとtd_global_idのcookieがsecure cookieとして設定されていなかったため、この影響を受けていました。

JS SDK 2.4.2以降では、Treasure Data JS SDKは新しいcookieの適用方式に対応するため、デフォルトでSameSite=None; Secureのcookieを使用します。

詳細については、以下を参照してください。

• Firefox: Changes to SameSite Cookie Behavior

• Chrome: SameSite Cookie Changes in February 2020: What You Need to Know

JS SDKによるデータ取り込みの方法は、使用しているSDKのバージョンによって異なります。

useNewJavaScriptEndpointにはtrueまたはfalseの値を指定します。このオプションを有効化する場合は、新しいエンドポイントを指すようにhostの設定も変更する必要があります。この新機能は、SDKのサーバー側cookieおよびパーソナライゼーション機能には影響しません。

hostの設定には、データを取り込む環境に応じて次の値を指定します。

JS SDK 4.4の例

  var foo = new Treasure({
    database: 'foo',
    writeKey: 'your_write_only_key',
    host: 'us01.records.in.treasuredata.com'
  });

useNewJavaScriptEndpointをfalseに設定するか、設定しないことでこの機能をオプトアウトする場合は、hostを従来の設定に更新してください。

JS SDK 3.1の例

  var foo = new Treasure({
    database: 'foo',
    writeKey: 'your_write_only_key',
    useNewJavaScriptEndpoint: true,
    host: 'us01.records.in.treasuredata.com'
  });

useNewJavaScriptEndpointをfalseに設定するか、設定しないことでこの機能をオプトアウトする場合は、hostを従来の設定に更新してください。

JS SDK 4.1以降では、次の変更と制限が導入されました。

• リアルタイムセグメンテーションを使用するには、バックエンドでルーティングを有効化する必要があります。ルーティングを有効化するには、テクニカルサポートまたはカスタマーサクセス担当者にお問い合わせください。その際、account、database、tableをお知らせください。
  
  

• td_browser、td_browser_version、td_os、td_os_versionは、JS SDK 4.xでは追跡されません。これらの値を取得するには、td_user_agentとHiveまたはTrino(Presto)の関数TD_PARSE_USER_AGENTを使用します。
  
  

• records.inエンドポイントには、次の制限があります。

  • 1~500レコード。
  • 1イベントあたり最大1000kiB。
  • 全イベントの合計で最大5MiB。

新しいAPIであるfetchPersonalizationを使用すると、パーソナライゼーションデータを取得して、消費者にパーソナライズされたコンテンツを配信できます。

• us01.p13n.in.treasuredata.com
• eu01.p13n.in.treasuredata.com
• ap01.p13n.in.treasuredata.com
• ap03.p13n.in.treasuredata.com

マーケターは、メールとランディングページ全体のパフォーマンスを追跡し、エンゲージメント、コンバージョン、収益アトリビューションを効果的に測定できます。

次のUTMパラメータは自動的に追跡されます。

• utm_id
• utm_medium
• utm_source_platform
• utm_source
• utm_campaign
• utm_marketing_tactic

UTMパラメータ付きでウェブページが読み込まれると、JS SDKはこれらのパラメータを自動的に収集し、$globalテーブルに追加します。その結果、これらのパラメータはページビューやイベント追跡などの追跡リクエストとともに送信されます。

JavaScript SDKは、REST APIエンドポイントを使用してデータをインポートします。サーバー側のバッファリングのため、インポートがデータベースに反映されるまで数分かかる場合があります。

• X-TD-Data-Type: k - イベントコレクターは複数のデータタイプを扱います。'k'はその1つで、複数のレコードを扱えます。

単一レコード

$ curl -X POST -H 'Content-Type: application/json' -H 'X-TD-Write-Key: your_write_apikey' \
--data-binary '{"name":"komamitsu", "num":1234}' \
https://your_region.treasuredata.com/js/v3/event/your_db/your_table

複数レコード

$ curl -X POST -H 'Content-Type: application/json' -H 'X-TD-Write-Key: your_write_apikey' \
-H 'X-TD-Data-Type: k' \
--data-binary '{"your_db.your_table":[{"time":1403147720, "name":"komamitsu", "age":41},{"time":1403147721, "name":"kzk", "age":29}]}' \
https://your_region.treasuredata.com/js/v3/event

JS SDKに関するその他のリソースは次のとおりです。

• GitHubリポジトリのtd-js-sdk README
• TD JavaScript APIリファレンス