# JavaScript-Advanced
# ユーザーID設定
SDKインスタンスはランダムの値でユーザーのゲストIDとして付与します。ゲストIDはユーザーがログインする前のユーザー識別IDとして使われます。ただし、事前に注意すべきのは、アカウントIDはユーザー再インストールすると変更されます。
# 1.1 ゲストID設定
TIP
一般的には、ゲストIDを手動設定することは不要で、ユーザー識別ルールを確認した上で、ゲストID設定を行なってください。
もしゲストIDを変更したい場合は、SDKを初期設定したあとですぐ呼び出すように設定してください。
te.identify("Thinker");
現在のゲストIDを取得したい場合は、getDistinctId
を呼び出して取得できます。
//Return distinct ID
var distinctId = te.getDistinctId();
# 1.2 アカウントID設定
ユーザーログイン時に、Login
を呼び出してアカウントIDを設定できます。TEはアカウントIDをユーザー身分の識別IDとして使われています。一度設定されたアカウントIDはLogout
を呼び出す前に保存されます。Login
を多数呼び出した場合は、その前のアカウントIDを上書きされます。
// The login unique identifier of the user, corresponding to the #account_id in data tracking. #Account_id now is TE
te.login("TE");
この方法ではログインイベントとして送信されません
# 1.3 アカウントIDをクリア
ユーザーがログアウトイベントを行う前に、Logout
を呼び出して、アカウントIDをクリアすることができます。もう一度Login
を呼び出す前にゲストIDはユーザー身分の識別IDとして使われます。
te.logout();
ユーザーがアカウントを削除する際にLogoutを呼び出すよう設定してください。
ログアウトイベントとして送信されません。
# イベント送信
SDKが初期化設定完了後、データプランに応じて、トラッキングコードを実装し、ユーザーの行動データを収集することができます。一般的には、通常イベント送信は十分収集可能で、実際業務シーンによって、初回・更新可能などの特殊イベント収集することも可能です。
# 2.1 通常イベント
track
を呼び出して、データプランに応じてイベントのプロパティを設定の上、データ送信できます。
例:アイテム購入
te.track(
"product_buy", //event name
{ product_name: "product_name"} //event property
);
# 2.2 初回イベント
初回イベントはあるデバイスもしくはその他分析主体のIDごとで、1回目のみ記録されるイベントとなります。
例えば:あるデバイスのアクティブイベントはそれを使って便利です
te.trackFirstEvent({
eventName: "device_activation",
properties: { key:"valeu" }
});
もしデバイス以外で初回判断したい場合は、first_check_id
で初回イベントを定義してください。
//set the user ID as the first_check_id of the first event to track the first initialization event of the user.
te.trackFirstEvent({
eventName: "account_activation",
firstCheckId: "TE",
properties: { key: "value"}
});
注意:サーバ側で初回なのかを検証するため、初回イベントはデフォルトで1時間遅延して格納されます。
# 2.3 更新可能イベント
通常イベントはデータを格納されたら更新不可となりますが、データ更新を行いたい場合は、更新可能イベントを利用してください。更新可能イベントは識別イベントのIDが必要で、作成時はプロパティに入れてください。TEシステムはイベント名とイベントIDを識別対象として更新データを確定します。
//The event property status is 3 after reporting, with the price being 100
te.trackUpdate({
eventName: "UPDATABLE_EVENT",
properties: { status: 3, price: 100 },
eventId: "test_event_id"
});
//The event property status is 5 after reporting, with the price remaining the same
te.trackUpdate({
eventName: "UPDATABLE_EVENT",
properties: { status: 5 },
eventId: "test_event_id"
});
# 2.4 書き替えイベント
書き替えイベントは更新可能イベントと同じようで、書き替えイベントは過去データを最新のデータで上書きされるため、前のデータを削除し新しくデータを格納するように見られます。TEシステムはイベント名とイベントIDを識別対象として更新データを確定します。
//The event property status is 3 after reporting, with the price being 100
te.trackOverwrite({
eventName: "OVERWRITE_EVENT",
properties: { status: 3, price: 100 },
eventId: "test_event_id"
});
//The event property status is 5 after reporting, with the price deleted
te.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 となり、イベントプロパティと一致する必要があります。
// set super properties
ta.setSuperProperties({ channel: "channel", user_name: "nsername" });
プロパティ設定以外では、その他API利用で静的共通イベントプロパティの設定が可能です。
//obtain all certain super properties
var superProperties = ta.getSuperProperties();
// clear a certain super property
te.unsetSuperProperty("channel");
// clear all certain super properties
te.clearSuperProperties();
# 2.5.2 ページ共通プロパティ設定
ページ中の静的プロパティに対しては:ページの名称やURL。当ページでトリガーされたすべてのイベントにこれらのプロパティを付属したい場合は、ページ共通プロパティを設定してください。setPageProperty
を利用して設定した共通プロパティは当ページのみ有効となります。
//Set the page ID as a public property of the page, and all events triggered in this page will have the following properties
te.setPageProperty({ page_id: "page10001" });
当ページのページ共通プロパティを取得したい場合はgetPageProperty
で取得可能です。
//Get the page public properties of the current page
var pageProperty = te.getPageProperty();
# 2.5.3 ページ動的共通プロパティ設定
setDynamicSuperProperties
を通じて、動的共通プロパティのコールバック関数を設定します。SDKはイベントデータ送信時にコールバック関数をトリガーし、戻り値のJSONをイベントプロパティに記録します。setDynamicSuperProperties
のパラメータは一つの関数で、関数は一つJSONが戻り値として設定することが必要です。
te.setDynamicSuperProperties(function() {
var d = new Date();
d.setHours(10);
return { date: d };
});
# 2.6 イベント時間記録
イベントの経過時間を記録したい場合は、timeEvent
を呼び出して計算可能です。計算したいイベント名称を設定し、該当イベントが送信される際に、自動的にイベントプロパティに#duration
のプロパティを追加され、経過時間を記録されます。単位は秒です。
//The following instance has recorded the time the user spent on a certain product page
ta.timeEvent("stay_shop");
/**do someting
.......
**/
//the timing would end when the user leaves the product page. "stay_shop" event would carry#duration, a property representing event duration.
ta.track("stay_shop",{product_name:"product_name"});
# 2.7 バッチ送信
SDK バージョン1.6.1以上はデータのバッチ送信が対応できるようになりました。
var config = {
appId: '2f2d8810817c4cbfb7c38aeb8466615a',
serverUrl: 'https://receiver-ta-preview.thinkingdata.cn',
send_method: 'ajax',
batch:true
batch: {
size: 5,
interval: 5000,
storageLimit:200
},
};
- batch:バッチ送信有効するのか、任意でデフォルト値はfalse
- size:バッチ送信データの最大値、デフォルトは5で、最小値1で、最大値30
- interval:送信時間間隔、デフォルト6000
- storageLimit: ローカルで最大キャッシュのデータ件数、デフォルトで200件
注意:
- バッチ送信とコールバック機能を同時に使用することはできません。例えば、trackがcallbackで追加された場合、バッチ送信を使用した後、callbackは実行されません。
- バッチ送信はデフォルトでajaxの方法でデータ送信します。
- localStorage に 200 個を超えるデータが格納されている場合、バッチ送信は失敗しません。200 個のデータのみが localStorage に保存され、新しく生成されたデータが構成メソッドを使用して送信されます。対策としては毎回 20 個のデータを削除し、これらの 20 個のデータに同時にデータを送信します。
- app_js_bridge と batch_send 一つのみ選択可能です。
- localstorageストレージ利用です。
- debugまたはdebugOnlyは直接データ送信です。
# ユーザープロパティ
TEでユーザープロパティを設定するAPIはuserSet
、userSetOnce
、userAdd
、userUnset
、userDelete
、userAppend
、userUniqAppend
。
# 3.1 userSet
一般的にユーザープロパティ設定はUserSet
を用いて設定できます。この呼び出しを利用して元のプロパティ値を書き替えされます。元のプロパティ値がない場合は、新規作成になります。データタイプは格納されたデータタイプと一致します。以下は例:
//the username now is TA
ta.userSet({ username: "TA" });
//the username now is TE
ta.userSet({ username: "TE" });
# 3.2 userSetOnce
もしユーザープロパティは一回設定の上で変更がない場合は、UserSetOnce
を用いて設定できます。この呼び出しは値のある際に書き替えを行いません。
例:初回課金時間設定
//first_payment_time is 2018-01-01 01:23:45.678
te.userSetOnce({first_payment_time: "2018-01-01 01:23:45.678" });
//first_payment_time is still 2018-01-01 01:23:45.678
te.userSetOnce({first_payment_time: "2018-12-31 01:23:45.678" });
# 3.3 userAdd
もし数値型のプロパティで累積計算を行いたい場合は、UserAdd
を用いて設定できます。この呼び出しは値のない際に自動で0を付与した上で計算されます。"-"値で計算することも可能で、例:累積課金金額
//in this case, the total_revenue is 30
te.userAdd({ total_revenue: 30 });
//in this case, the total_revenue is 678
te.userAdd({ total_revenue: 648 });
# 3.4 userUnset
ユーザープロパティをリセットしたい場合は、UserUnset
を用いて設定できます。このプロパティはクラスター内で作成されていない場合は、UserUnset
はそのプロパティを作成しません。
// reset properties of a single user
te.userUnset("userPropertykey");
# 3.5 userDel
ユーザーを削除したい場合はuserDel
を用いて設定できます。削除したら当ユーザーのユーザープロパティはクエリできなくなりますが、当ユーザーが生成したイベントデータはクエリできます。
ta.userDelete();
# 3.6 userAppend
UserAppend
を用いて、List
型のユーザープロパティを追加できます。
ta.userAppend({ user_list: ["apple", "ball"] });
# 3.7 userUniqAppend
v1.6.0以降は、userUniqAppend
を利用して、Array (List)型のユーザーデータにユニークエレメントを追加できます。userUniqAppend
インターフェースは追加されたユーザープロパティを重複排除され、userAppend
は重複排除しませんので、ユーザープロパティは重複される可能性があります。
//in this case, the property value of user_list is ["apple","ball"]
te.userAppend({ user_list: ["apple", "ball"] });
//in this case, the property value of user_list is ["apple","apple","ball","cube"]
te.userAppend({ user_list: ["apple", "cube"] });
//in this case, the property value of user_list is ["apple","ball","cube"]
te.userUniqAppend({ user_list: ["apple", "cube"] });
# 送信データの暗号化対応
v1.6.0以降は、データ送信方式はajaxで、送信データの暗号化対応ができるようになりました。SDK初期設定のconfigに暗号化する情報を入れます。
var config = {
appId: "xxx",
serverUrl: "xxx",
secretKey: {
//The encrypted public key can be obtained in the TA management background
publicKey: '公钥',
//public key version number
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>
# 複数ドメイン連携
1.6.1バージョン以上は、複数ドメイン連携ができるようになります。二つ以上の異なるドメインのURLのユーザー行動の統一することによって、ユーザーの転換フローを分析できます。
ta.quick('siteLinker', {
linker: [
{ part_url: 'thinkingdata.cn', after_hash: true },
{ part_url: 'example.com', after_hash: true }
]
})
part_url :The configured part_url string must be a substring of the URL to open the URL.
The domain you want to open | configuration | a tag href address | a label to get through the results |
---|---|---|---|
thinkingdata.cn | { part_url: 'thinkingdata.cn', after_hash: false } | https://thinkingdata.cn/ | https://thinkingdata.cn/?_tasdk='d'+distinctID |
after_hash: Mandatory attribute, and the attribute value must be Boolean type, namely true or false, configure the _tasdk parameter in the hash part of the URL (that is, the part after #) or in the search part of the URL (that is, the part before # ?)
url | after_hash | result |
---|---|---|
https://thinkingdata.cn | false | https://thinkingdata.cn?_tasdk=distinctID |
true | https://thinkingdata.cn#?_tasdk=distinctID | |
https://thinkingdata.cn#index | false | https://thinkingdata.cn?_tasdk=distinctID#index |
true | https://thinkingdata.cn#index?_tasdk=distinctID | |
https://thinkingdata.cn?a=1#index | false | https://thinkingdata.cn?a=1&_tasdk=distinctID#index |
true | https://thinkingdata.cn?a=1#index?_tasdk=distinctID | |
https://thinkingdata.cn?a=1#index?b=2 | false | https://thinkingdata.cn?a=1&_tasdk=distinctID#index?b=2 |
true | https://thinkingdata.cn?a=1#index?b=2&_tasdk=distinctID |
# その他機能
# 6.1 デバイスIDを取得
getDeviceId
を利用して、デバイスIDの取得ができます。
var deviceId = ta.getDeviceId();
# 6.2 デフォルトタイムゾーン設定
デフォルトでSDKは本デバイスの表示時間をイベント発生時間として送信されます。デフォルトタイムゾーンを指定することも可能です。
var config = {
appId: "xxx",
serverUrl: "xxx",
zoneOffset:8
};
タイムゾーン指定したら、本デバイスのタイムゾーンのデータが破棄されます。もし本デバイスのタイムゾーンを保留したい場合は、別途イベントにカスタムプロパティを追加してください。