応用ガイド
1. ユーザーIDの設定
SDKインスタンスは、デフォルトで乱数を各ユーザーのデフォルトのゲストIDとして使用します。このIDは、ユーザーが未ログインの状態での識別IDとして使われます。なお、ゲストIDはユーザーがキャッシュを削除した場合やデバイスを変更した場合に変わります。
1.1 ゲストIDの設定
通常、ゲストIDをカスタマイズする必要はありません。ユーザー識別ルールを理解したうえで、ゲストIDを設定してください。
ta.setDistinctId("Thinker");
ゲストIDを取得する場合は、getDistinctIdを呼び出して取得できます：
//ゲストIDを返す
var distinctId = ta.getDistinctId();
1.2 アカウントIDの設定
ユーザーがログインする際にloginを呼び出して、ユーザーのアカウントIDを設定できます。AEプラットフォームはアカウントIDを識別IDとして使用し、設定したアカウントIDはlogoutを呼び出すまで保持されます。loginを複数回呼び出すと、以前のアカウントIDが上書きされます。
// ユーザーのログインの一意識別子。このデータは送信データの#account_idに対応し、この時点で#account_idの値はTA
ta.login("TA");
このメソッドはログインイベントを送信しません
1.3 アカウントIDのクリア
ユーザーがログアウトした後にlogoutを呼び出して、アカウントIDをクリアできます。次にloginを呼び出すまでは、ゲストIDが識別IDとして使われます。
ta.logout();
logoutはログアウト操作時に呼び出すことを推奨します。例えば、ユーザーがアカウントからログアウトした場合にのみ呼び出し、アプリを閉じるときに呼び出す必要はありません。
このメソッドはログアウトイベントを送信しません
2. イベントの送信
SDKの初期化が完了したら、データのトラッキングを行い、ユーザーの行動情報を収集できます。通常は通常イベントで業務シナリオの要件を満たせますが、実際の業務シナリオに応じて、初回イベントや更新可能イベントなどを使用することもできます。
2.1 通常イベント
trackを呼び出してイベントを送信できます。事前に整理したドキュメントに従って、イベントのプロパティと送信条件を設定することをお勧めします。ここでは、ユーザーが商品を購入する場合を例にします：
ta.track(
"product_buy", //イベント名
{ product_name: "商品"} //イベントプロパティ
);
2.2 初回イベント
初回イベントとは、あるデバイスまたはその他のディメンションのIDについて、一度だけ記録されるイベントです。例えば、あるデバイスでのアクティベーションイベントを記録したい場合などは、初回イベントでデータを送信できます
ta.trackFirst({
eventName: "device_activation",
properties: { key:"value" }
});
デバイス以外のディメンションで初回かどうかを判定したい場合は、初回イベントのfirst_check_idをカスタマイズできます：
// ユーザーIDを初回イベントのFIRST_CHECK_IDに設定し、ユーザーの初回アクティベーションイベントを収集します
ta.trackFirst({
eventName: "account_activation",
firstCheckId: "TA",
properties: { key: "value"}
});
注意：初回かどうかの検証はサーバー側で行われるため、初回イベントはデフォルトで1時間遅れて取り込まれます。
2.3 更新可能イベント
更新可能イベントを使用すると、特定のシナリオでイベントデータを変更する必要がある場合に対応できます。更新可能イベントでは、そのイベントを識別するIDを指定し、更新可能イベントのオブジェクトを作成する際に渡す必要があります。AE管理画面は、イベント名とイベントIDに基づいて更新するデータを特定します。
// 例：更新可能なイベントを送信します。イベント名はUPDATABLE_EVENTとします
// 送信後、イベントプロパティstatusは3、priceは100になります
ta.trackUpdate({
eventName: "UPDATABLE_EVENT",
properties: { status: 3, price: 100 },
eventId: "test_event_id"
});
// 送信後、イベントプロパティstatusは5に更新され、priceは変わりません
ta.trackUpdate({
eventName: "UPDATABLE_EVENT",
properties: { status: 5 },
eventId: "test_event_id"
});
2.4 上書き可能イベント
上書き可能イベントは更新可能イベントと似ていますが、上書き可能イベントでは最新のデータで過去のデータを完全に上書きする点が異なります。効果としては、前のデータを削除して最新のデータを格納するのと同じです。AE管理画面は、イベント名とイベントIDに基づいて更新するデータを特定します。
// 例：上書き可能なイベントを送信します。イベント名はOVERWRITE_EVENTとします
// 送信後、イベントプロパティstatusは3、priceは100になります
ta.trackOverwrite({
eventName: "OVERWRITE_EVENT",
properties: { status: 3, price: 100 },
eventId: "test_event_id"
});
// 送信後、イベントプロパティstatusは5に更新され、priceプロパティは削除されます
ta.trackOverwrite({
eventName: "OVERWRITE_EVENT",
properties: { status: 5 },
eventId: "test_event_id"
});
2.5 共通イベントプロパティの設定
データを収集する過程では、複数のイベントで共通して使われるフィールドがあります。例えば、同じページで発生したすべてのイベントにはそのページのページプロパティが含まれるべきで、ユーザーのアカウント情報はすべてのデータに含まれるべきです。そのため、trackを呼び出してイベントを送信する際に、これらのプロパティを毎回設定する必要があります。このようなプロパティは、共通プロパティの設定インターフェースでまとめて設定できます。
共通プロパティの設定方法を説明する前に、3種類の共通プロパティの特性を理解し、実際の要件に応じて適切な種類を選択してください：
- 静的共通プロパティ: すべてのページで有効です。優先度は最も低く、キャッシュが有効な場合はlocalStorageまたはcookieにキャッシュされます。固定値のみ設定できます。
- ページ共通プロパティ: 現在のページでのみ有効で、優先度は最も高くなります。SDKを再初期化すると、ページ共通プロパティはクリアされます。固定値のみ設定できます。
- 動的共通プロパティ: 優先度はページ共通プロパティの次です。SDKを再初期化した後は、動的共通プロパティを再度設定する必要があります。動的な変数を設定できます。
2.5.1 静的共通プロパティの設定
ユーザーのチャネル、ニックネーム、IDなどの重要なプロパティは、すべてのイベントに設定する必要があります。setSuperPropertiesを呼び出して静的共通イベントプロパティを設定でき、静的共通イベントプロパティはグローバルに適用されます。キャッシュが有効な場合（デフォルトで有効）、静的共通プロパティはlocalStorageまたはcookieにキャッシュされます。
静的共通プロパティのパラメーターはJSONオブジェクトで、形式の要件はイベントプロパティと同じです。
// 共通イベントプロパティを設定すると、すべてのデータのイベントにこれらのプロパティが含まれます
ta.setSuperProperties({ channel: "チャネル名", user_name: "ユーザー名" });
プロパティの設定以外にも、静的共通イベントプロパティを操作するためのAPIを提供しており、日常的な業務要件に対応できます。
// 静的共通イベントプロパティを取得
var superProperties = ta.getSuperProperties();
// 静的共通イベントプロパティを1つクリアします。例えば、以前に設定した'channel'プロパティをクリアすると、以降のデータにはこのプロパティが含まれなくなります
ta.unsetSuperProperty("channel");
// すべての静的共通イベントプロパティをクリア
ta.clearSuperProperties();
2.5.2 ページ共通プロパティの設定
ページの名前やURLなど、ページ内の静的なプロパティについては、そのページでトリガーされるすべてのイベントにこのプロパティを追加したい場合があります。このように、ページ内のすべてのイベントに適用する必要がある静的プロパティは、setPagePropertyで設定できます。なお、setPagePropertyで設定した共通プロパティは現在のページでのみ有効です
// ページIDをページ共通プロパティに設定します。このページでトリガーされるすべてのイベントに、次のプロパティが含まれます
ta.setPageProperty({ page_id: "page10001" });
現在のページのページ共通プロパティを取得する場合は、getPagePropertyを呼び出して取得できます
// 現在のページのページ共通プロパティを取得
var pageProperty = ta.getPageProperty();
2.5.3 ページ動的共通プロパティの設定
setDynamicSuperPropertiesで動的共通プロパティのコールバック関数を設定すると、SDKはイベントの送信時にコールバック関数をトリガーし、返されたJSONオブジェクトをイベントプロパティに追加します。setDynamicSuperPropertiesのパラメーターは関数で、関数はJSONオブジェクトを返す必要があります。
// 動的共通プロパティを設定します。イベントの送信時にコールバック関数がトリガーされ、返されたJSONオブジェクトがイベントプロパティに追加されます
ta.setDynamicSuperProperties(function() {
var d = new Date();
d.setHours(10);
return { date: d };
});
2.6 イベントの所要時間の記録
あるイベントの継続時間を記録する必要がある場合は、timeEventを呼び出して計測を開始できます。計測したいイベント名を設定しておくと、そのイベントを送信する際に、記録した時間を表す#durationプロパティがイベントプロパティに自動的に追加されます。単位は秒です。なお、同じイベント名で計測中のタスクは1つしか持てません。
//次の例では、ユーザーがある商品ページに滞在した時間を集計します
ta.timeEvent("stay_shop");
/**do someting
.......
**/
//ユーザーが商品ページを離れると計測が終了し、"stay_shop"イベントにイベントの所要時間を表すプロパティ#durationが付与されます
ta.track("stay_shop",{product_name:"商品名"});
2.7 一括送信
データの一括送信には、SDKバージョン1.6.1以上が必要です
var config = {
appId: '2f2d8810817c4cbfb7c38aeb8466615a',
serverUrl: 'https://receiver-ta-preview.thinkingdata.cn',
send_method: 'ajax',
//一括送信を有効にします。デフォルトはfalse
batch:true
//または
batch: {
size: 6,//データがsize件に達すると自動的に送信。デフォルトは6
interval: 6000,//送信間隔（ミリ秒）。間隔ごとに即時送信。デフォルトは6S
maxLimit:500//ローカルにキャッシュできるデータの最大件数。デフォルトは500件
},
};
- batch：データの一括送信を有効にするかどうか。必須ではなく、デフォルト値はfalse
- size：データがsize件に達すると自動的に送信をトリガーします。デフォルトは6、最小値は1、最大値は30
- interval：送信の時間間隔。デフォルトは6000
- maxLimit: ローカルにキャッシュできるデータの最大件数。デフォルトは500件
注意事項：
- 一括送信機能とコールバック関数機能は同時に使用できません。例えば、trackにcallbackを追加している場合、一括送信を使用するとcallbackは実行されません。
- 一括送信では、デフォルトでajax方式でデータを送信します。
- localStorageにキャッシュされたデータ件数がmaxLimit（デフォルトは500件）を超えた場合は、先入れ先出しの方針に従って最も古いデータを破棄します。
- app_js_bridgeとbatch_sendはどちらか一方しか選択できません。連携を有効にすると、一括送信は使用できなくなります。
- localstorageに保存します。
- debugまたはdebugOnlyではデータが直接送信され、ローカルにキャッシュしてから一括送信されることはありません。
- 有効にすると、指定した件数または指定した時間間隔を満たした場合にのみデータが送信されます。頻繁に遷移するページでは、送信される前にページが閉じられ、一部のデータが失われる可能性があるため、慎重に有効にしてください。
3. ユーザープロパティ
AEプラットフォームがサポートしているユーザープロパティ設定APIは次のとおりです：userSet、userSetOnce、userAdd、userUnset、userDelete、userAppend、userUniqAppend。
3.1 userSet
一般的なユーザープロパティは、userSetを呼び出して設定できます。このインターフェースで送信したプロパティは、既存のプロパティ値を上書きします。そのユーザープロパティが以前に存在しない場合は新しく作成され、タイプは渡されたプロパティのタイプと同じになります。ここでは、ユーザー名の設定を例にします：
// usernameはTA
ta.userSet({ username: "TA" });
//usernameはAE
ta.userSet({ username: "AE" });
3.2 userSetOnce
送信するユーザープロパティを一度だけ設定すればよい場合は、userSetOnceを呼び出して設定できます。そのプロパティにすでに値がある場合、この情報は無視されます。ここでは、初回課金時間の設定を例にします：
//first_payment_timeは2018-01-01 01:23:45.678
ta.userSetOnce({first_payment_time: "2018-01-01 01:23:45.678" });
//first_payment_timeは2018-01-01 01:23:45.678のまま
ta.userSetOnce({first_payment_time: "2018-12-31 01:23:45.678" });
3.3 userAdd
数値型のプロパティを送信する場合は、userAddを呼び出してそのプロパティを累積加算できます。そのプロパティがまだ設定されていない場合は、0を代入してから計算します。負の値を渡すと、減算と同じになります。
//この時点でtotal_revenueは30
ta.userAdd({ total_revenue: 30 });
//この時点でtotal_revenueは678
ta.userAdd({ total_revenue: 648 });
3.4 userUnset
ユーザーのユーザープロパティ値をクリアする場合は、userUnsetを呼び出して、指定したプロパティをクリアできます。そのプロパティがまだクラスター内で作成されていない場合、userUnsetはそのプロパティを作成しません
// このユーザーの、ユーザープロパティ名がuserPropertykeyのユーザープロパティ値をクリアします（NULLに設定）
ta.userUnset("userPropertykey");
3.5 userDelete
あるユーザーを削除する場合は、userDeleteを呼び出してそのユーザーを削除できます。削除後はそのユーザーのユーザープロパティを照会できなくなりますが、そのユーザーが発生させたイベントは引き続き照会できます。
ta.userDelete();
3.6 userAppend
userAppendを呼び出して、配列型のユーザーデータに要素を追加できます。
ta.userAppend({ user_list: ["apple", "ball"] });
3.7 userUniqAppend
v1.6.0から、userUniqAppendを呼び出して、Array (List)型のユーザーデータに一意の要素を追加できます。userUniqAppendインターフェースを呼び出すと、追加するユーザープロパティの重複が排除されます。userAppendインターフェースでは重複は排除されないため、ユーザープロパティに重複が存在する場合があります。
//この時点でuser_listのプロパティ値は["apple"，"ball"]
ta.userAppend({ user_list: ["apple", "ball"] });
//この時点でuser_listのプロパティ値は["apple","apple","ball","cube"]
ta.userAppend({ user_list: ["apple", "cube"] });
//この時点でuser_listのプロパティ値は["apple"，"ball","cube"]
ta.userUniqAppend({ user_list: ["apple", "cube"] });
4. データ転送の暗号化への対応
v1.6.0から、データの送信方式がajaxの場合、データ転送の暗号化に対応しています。SDKの初期化configで暗号化関連の情報を設定できます。
var config = {
appId: "xxx",
serverUrl: "xxx",
secretKey: {
//暗号化用の公開鍵。AE管理画面で取得できます
publicKey: '公開鍵',
//公開鍵のバージョン番号
version: 1
},
};
データの暗号化に対応するには、crypto-jsとjsencryptを追加で導入する必要があります
<script src="https://cdn.bootcdn.net/ajax/libs/crypto-js/4.1.1/crypto-js.js"></script>
<script src="https://cdn.bootcss.com/jsencrypt/3.2.1/jsencrypt.js"></script>
5. 複数ドメインの連携
複数ドメインの連携には、SDKバージョン1.6.1以上が必要です。2つの異なるドメインのWebサイト上のユーザー行動を統合でき、関連するWebサイトのユーザーのコンバージョンの過程をより効果的に観察できます。
ta.quick('siteLinker', {
linker: [
{ part_url: 'thinkingdata.cn', after_hash: true }，
{ part_url: 'example.com', after_hash: true }
]
})
part_url :設定するpart_url文字列は、連携するWebサイトのURLの部分文字列である必要があります。
| 連携したいドメイン | 設定 | aタグのhrefアドレス | aタグの連携結果 |
|---|---|---|---|
| thinkingdata.cn | { part_url: 'thinkingdata.cn', after_hash: false } | https://thinkingdata.cn/ | https://thinkingdata.cn/?_tasdk='d'+distinctID |
after_hash: 必須プロパティで、値はブール型（trueまたはfalse）である必要があります。_tasdkパラメータをURLのhash部分（#の後ろの部分）に配置するか、URLのsearch部分（#の前の？の部分）に配置するかを設定します
6. その他の機能
6.1 デバイスIDの取得
getDeviceIdを呼び出して、デバイスIDを取得できます：
var deviceId = ta.getDeviceId();
6.2 デフォルトタイムゾーンの設定
デフォルトでは、SDKはインターフェースを呼び出した時点の端末のローカル時間をイベント発生時間として送信します。初期化時にデフォルトタイムゾーンを設定することもでき、その場合、すべてのイベントのイベント時間は設定したタイムゾーンに合わせて揃えられます：
var config = {
appId: "xxx",
serverUrl: "xxx",
zoneOffset:8
};
注意：指定したタイムゾーンでイベント時間を合わせると、デバイスのローカルタイムゾーンの情報は失われます。デバイスのローカルタイムゾーンの情報を保持する必要がある場合は、現時点ではイベントに関連プロパティを自分で追加する必要があります。
6.3 SDKによる設定情報の取得を無効化
SDKが初期化時に設定情報を取得しないようにする場合は、次の方法で制御できます：
var config = {
appId: "xxx",
serverUrl: "xxx",
disableRConfig:true
};
ta.init(config);
disableRConfigがtrueの場合は設定情報の取得を禁止し、falseの場合は設定情報の取得を有効にします