応用ガイド
1. ユーザーIDの設定
SDKインスタンスは、デフォルトでランダムなUUIDを各ユーザーのデフォルトのゲストIDとして使用します。このIDは、ユーザーが未ログイン状態のときの識別IDとして使われます。なお、ゲストIDは、ユーザーがAppを再インストールしたり、デバイスを変更したりすると変わります。
1.1 ゲストIDの設定
通常、ゲストIDをカスタマイズする必要はありません。ユーザー識別ルールを理解したうえで、ゲストIDを設定してください。
ゲストIDを置き換える必要がある場合は、SDKの初期化が完了した直後に呼び出してください。不要なアカウントが生成されないよう、複数回呼び出さないでください
Appにユーザーごとの独自のゲストID管理体系がある場合は、setDistinctIdを呼び出してゲストIDを設定できます：
// ゲストIDをThinkerに設定
TDAnalytics.setDistinctId("Thinker");
現在のゲストIDを取得する必要がある場合は、getDistinctIdを呼び出して取得できます：
//ゲストIDを返す
async () => {
var distinct_id = await TDAnalytics.getDistinctId()
}
1.2 アカウントIDの設定
ユーザーがログインする際にloginを呼び出して、ユーザーのアカウントIDを設定できます。AEプラットフォームはアカウントIDを識別IDとして使用し、設定したアカウントIDはlogoutを呼び出すまで保持されます。loginを複数回呼び出すと、以前のアカウントIDが上書きされます。
// ユーザーのログイン時の一意の識別子。このデータは送信データの#account_idに対応し、この場合#account_idの値はTAになります
TDAnalytics.login("TA");
このメソッドはログインイベントを送信しません
1.3 アカウントIDのクリア
ユーザーがログアウトした後にlogoutを呼び出して、アカウントIDをクリアできます。次にloginを呼び出すまでは、ゲストIDが識別IDとして使われます。
TDAnalytics.logout();
logoutは、明示的なログアウトイベントのときに呼び出すことを推奨します。たとえば、ユーザーがアカウントからログアウトする操作を行ったときにのみ呼び出し、Appを閉じるときに呼び出す必要はありません。
このメソッドはログアウトイベントを送信しません
2. イベントの送信
2.1 通常イベント
SDKの初期化が完了したら、データのトラッキングを行い、ユーザーの行動情報を収集できます。通常は通常イベントで業務シナリオの要件を満たせますが、実際の業務シナリオに応じて、初回イベントや更新可能イベントなどを使用することもできます。
//ストア購入イベント
TDAnalytics.track({
eventName:"product_buy",
properties:{
'product_name':'商品名'
}
})
2.2 初回イベント
初回イベントとは、デバイスまたはその他のディメンションのIDに対して、1回だけ記録されるイベントのことです。たとえば、あるデバイスでのアクティベーションイベントを記録したい場合は、初回イベントでデータを送信できます。
// 例：デバイスの初回イベントを送信。イベント名はdevice_activationとします
TDAnalytics.trackFirst({
eventName:'device_activation',
properties: {
KEY_NUMBER: 1.02,
KEY_STRING: "name",
KEY_LIST: [1, 2, 3],
KEY_BOOL: true,
KEY_DateTime: "2020-05-12 06:27:18.371"
}
})
デバイス以外のディメンションで初回かどうかを判定したい場合は、初回イベントのfirst_check_idをカスタマイズできます：
// ユーザーIDを初回イベントのfirst_check_idに設定し、ユーザーの初回アクティベーションイベントを収集します
TDAnalytics.trackFirst({
eventName:'device_activation',
properties: {
KEY_NUMBER: 1.02,
KEY_STRING: "name",
KEY_LIST: [1, 2, 3],
KEY_BOOL: true,
KEY_DateTime: "2020-05-12 06:27:18.371"
},
eventId:'TA'
})
注意：初回かどうかの検証はサーバー側で行われるため、初回イベントはデフォルトで1時間遅れて取り込まれます。
2.3 更新可能イベント
更新可能イベントを使用すると、特定のシナリオでイベントデータを変更する必要がある場合に対応できます。更新可能イベントでは、そのイベントを識別するIDを指定し、更新可能イベントのオブジェクトを作成する際に渡す必要があります。AE管理画面は、イベント名とイベントIDに基づいて更新するデータを特定します。
// 例：更新可能なイベントを送信。イベント名はUPDATABLE_EVENTとします
// 送信後、イベントプロパティstatusは3、priceは100になります
TDAnalytics.trackUpdate({
eventName:'UPDATABLE_EVENT',
properties: { status: 3, price: 100},
eventId:'test_event_id'
})
// 送信後、イベントプロパティstatusは5に更新され、priceは変わりません
TDAnalytics.trackUpdate({
eventName:'UPDATABLE_EVENT',
properties: { status: 5},
eventId:'test_event_id'
})
2.4 上書き可能イベント
上書き可能イベントは更新可能イベントと似ていますが、上書き可能イベントでは最新のデータで過去のデータを完全に上書きする点が異なります。効果としては、前のデータを削除して最新のデータを格納するのと同じです。AE管理画面は、イベント名とイベントIDに基づいて更新するデータを特定します。
// 例： 上書き可能なイベントを送信。イベント名はOVERWRITE_EVENTとします
// 送信後、イベントプロパティstatusは3、priceは100になります
TDAnalytics.trackOverwrite({
eventName:'OVERWRITE_EVENT',
properties: { status: 3, price: 100},
eventId:'test_event_id'
})
// 送信後、イベントプロパティstatusは5に更新され、priceプロパティは削除されます
TDAnalytics.trackOverwrite({
eventName:'OVERWRITE_EVENT',
properties: { status: 5},
eventId:'test_event_id'
})
2.5 共通イベントプロパティ
共通イベントプロパティとは、すべてのイベントで送信されるプロパティのことです。プロパティの更新頻度に応じて、共通イベントプロパティは静的共通イベントプロパティと動的共通イベントプロパティに分けられます。具体的な業務シナリオの要件に応じて、異なる共通イベントプロパティの設定方法を選択できます。イベントを送信する前に、共通イベントプロパティを設定しておくことを推奨します。同じイベントで、共通イベントプロパティ、イベントのカスタムプロパティ、プリセットプロパティのKeyが同じ場合は、次の優先順位で値が設定されます：カスタムプロパティ>動的共通イベントプロパティ>静的共通イベントプロパティ>プリセットプロパティ。
2.5.1 静的共通イベントプロパティの設定
静的共通イベントプロパティとは、変化の頻度が低く、すべてのイベントに含まれるプロパティのことです（ユーザーの会員レベルなど）。setSuperPropertiesで静的共通イベントプロパティを設定すると、SDKはイベントの収集時に、設定された共通イベントプロパティをイベントのプロパティとして取得します。
TDAnalytics.setSuperProperties({ vip_level: 2})
静的共通イベントプロパティはキャッシュに保存されるため、Appを起動するたびに呼び出す必要はありません。そのプロパティがすでに存在する場合は、再設定したプロパティで元のプロパティ値が上書きされます。そのプロパティが存在しない場合は、新しく作成されます。プロパティの設定以外にも、静的共通イベントプロパティを管理するためのAPIを提供しており、日常的な業務要件に対応できます。
//特定の共通イベントプロパティをクリア
TDAnalytics.unsetSuperProperty("superKey")
//すべての共通イベントプロパティをクリア
TDAnalytics.clearSuperProperties()
//すべての共通イベントプロパティを取得
async () => {
var properties = await TDAnalytics.getSuperProperties()
}
2.5.2 動的共通イベントプロパティの設定
動的共通イベントプロパティとは、変化の頻度が高く、すべてのイベントに含まれるプロパティのことです（ユーザーのコイン数など）。setDynamicSuperPropertiesTrackerで動的共通プロパティのクラスを設定すると、SDKはイベントの収集時にgetDynamicSuperProperties内のプロパティを自動的に取得し、トリガーされたイベントに追加します。
var coin = 0;
TDAnalytics.setDynamicSuperProperties(function () {
return { coin: coin++ }
})
2.6 イベントの所要時間の記録
あるイベントの継続時間を記録する必要がある場合は、timeEventを呼び出して計測を開始できます。計測したいイベント名を設定しておくと、そのイベントを送信する際に、記録した時間を表す#durationプロパティがイベントプロパティに自動的に追加されます。単位は秒です。なお、同じイベント名で計測中のタスクは1つしか持てません。
//次の例では、ユーザーがある商品ページに滞在した時間を集計します
//ユーザーが商品ページに入り、計測を開始
TDAnalytics.timeEvent("stay_shop")
/**do someting
.......
**/
//ユーザーが商品ページを離れ、計測を終了。"stay_shop"イベントには、イベントの所要時間を表すプロパティ#durationが付与されます
TDAnalytics.track({eventName:"stay_shop"})
3. ユーザープロパティ
AEプラットフォームが現在対応しているユーザープロパティ設定インターフェースは次のとおりです: userSet、userSetOnce、userAdd、userUnset、userDelete、userAppend、userUniqAppend
4.1 userSet
一般的なユーザープロパティは、userSetを呼び出して設定できます。このインターフェースで送信したプロパティは、既存のプロパティ値を上書きします。そのユーザープロパティが以前に存在しない場合は新しく作成され、タイプは渡されたプロパティのタイプと同じになります。ここでは、ユーザー名の設定を例にします：
// usernameはTA
TDAnalytics.userSet({ username: "TA" });
//usernameはAE
TDAnalytics.userSet({ username: "AE" });
4.2 userSetOnce
送信するユーザープロパティを一度だけ設定すればよい場合は、userSetOnceを呼び出して設定できます。そのプロパティにすでに値がある場合、この情報は無視されます。ここでは、初回課金時間の設定を例にします：
//first_payment_timeは2018-01-01 01:23:45.678
TDAnalytics.userSetOnce({first_payment_time: "2018-01-01 01:23:45.678" });
//first_payment_timeは2018-01-01 01:23:45.678のまま
TDAnalytics.userSetOnce({first_payment_time: "2018-12-31 01:23:45.678" });
4.3 userAdd
数値型のプロパティを送信する場合は、userAddを呼び出してそのプロパティを累積加算できます。そのプロパティがまだ設定されていない場合は、0を代入してから計算します。負の値を渡すこともでき、その場合は減算と同じになります。ここでは、累積課金額を例にします：
//この時点でtotal_revenueは30
TDAnalytics.userAdd({ total_revenue: 30 });
//この時点でtotal_revenueは678
TDAnalytics.userAdd({ total_revenue: 648 });
設定するプロパティのkeyは文字列で、Valueには数値のみ指定できます。
4.4 userUnset
ユーザーのユーザープロパティ値をクリアする場合は、userUnsetを呼び出して、指定したプロパティをクリアできます。そのプロパティがまだクラスター内で作成されていない場合、userUnsetはそのプロパティを作成しません
TDAnalytics.userUnset("usersetkey")
userUnsetに渡すパラメーターはユーザープロパティのプロパティ名で、型は文字列または文字列配列です。可変長引数の形式に対応しています。
4.5 userDelete
あるユーザーを削除する場合は、userDeleteを呼び出してそのユーザーを削除できます。削除後はそのユーザーのユーザープロパティを照会できなくなりますが、そのユーザーが発生させたイベントは引き続き照会できます。
TDAnalytics.userDelete()
4.6 userAppend
userAppendを呼び出して、Array型のユーザープロパティに要素を追加できます。
TDAnalytics.userAppend({ user_list: ["apple", "ball"] });
4.7 userUniqAppend
userUniqAppendを呼び出して、Array (List)型のユーザーデータに一意の要素を追加できます。userUniqAppendインターフェースを呼び出すと、追加するユーザープロパティの重複が排除されます。userAppendインターフェースでは重複は排除されないため、ユーザープロパティに重複が存在する場合があります。
//この時点でuser_listのプロパティ値は["apple","ball"]
TDAnalytics.userAppend({ user_list: ["apple", "ball"] });
//この時点でuser_listのプロパティ値は["apple","apple","ball","cube"]
TDAnalytics.userAppend({ user_list: ["apple", "cube"] });
//この時点でuser_listのプロパティ値は["apple","ball","cube"]
TDAnalytics.userUniqAppend({ user_list: ["apple", "cube"] });
4. 暗号化機能
SDKは暗号化機能に対応しています。クライアントはAES+RSAでデータを暗号化し、サーバー側でデータを復号します。暗号化・復号機能はクライアントとサーバーの連携が必要です。詳しくはカスタマーサクセス担当者にお問い合わせください。
enableEncryptプロパティをtrueに設定し、デフォルトのバージョン番号と公開鍵を設定します。
import TDAnalytics, { TDAutoTrackEventType,TDThirdPartyType,TDTrackStatus} from "react-native-thinking-data";
TDAnalytics.init({
appId: "xxx",
serverUrl: "https://xxx",
enableEncrypt: true,// データ転送の暗号化を有効化
secretKey: {
publicKey: "xxx",// 暗号化の公開鍵
version: 1,// 鍵のバージョン番号
symmetricEncryption: "AES",
asymmetricEncryption: "RSA"
}
});
5. H5ページとの連携を有効化
H5ページのデータを収集するJavaScript SDKと連携する必要がある場合は、次のインターフェースを呼び出してください。詳細はH5とAPP SDKの連携の節を参照してください
<WebView
ref={webViewRef}
source={localHtmlFile}
onMessage={ event => {
console.log(event.nativeEvent.data);
TDAnalytics.h5ClickHandler(event.nativeEvent.data);
}}
javaScriptEnabled={true}
injectedJavaScript='window.ThinkingData_APP_ReactNative_Bridge = function(data) { window.ReactNativeWebView.postMessage(data); };'
/>
6. その他の機能
6.1 デバイスIDの取得
getDeviceIdを呼び出して、デバイスIDを取得できます：
async () => {
var device_id = await TDAnalytics.getDeviceId()
}
6.2 時間の校正
SDKはデフォルトで端末のローカル時間をイベント発生時間として送信します。ユーザーがデバイスの時間を手動で変更すると業務分析に影響が出るため、その場合は時間の補正を行うことで、イベント発生時間の正確性を確保できます。タイムスタンプ、NTPの2種類の時間補正方法を提供しています。
- サーバーから取得した現在のタイムスタンプを使用して、SDKの時間を補正できます。以降、時間を指定していないすべての呼び出し（イベントデータやユーザープロパティの設定操作を含む）では、補正後の時間が発生時間として使用されます。
// 1585633785954は現在のunixタイムスタンプ（単位はミリ秒）で、北京時間の2020-03-31 13:49:45に相当します
TDAnalytics.calibrateTime(1585633785954);
- NTPサーバーのアドレスを設定することもできます。設定後、SDKは渡されたNTPサービスのアドレスから現在時刻を取得し、SDKの時間を補正しようとします。デフォルトのタイムアウト時間（3秒）以内に正しい結果が返されなかった場合、以降はローカル時間でデータを送信します。
// Apple社のNTPサービスを使用して時間を補正
TDAnalytics.calibrateTimeWithNtp("time.apple.com");
1. NTPサービスによる時間補正には一定の不確実性があるため、タイムスタンプによる補正方法を優先的に検討することを推奨します
2. ネットワーク状況が良好な場合にユーザーのデバイスがすばやくサーバー時間を取得できるよう、NTPサーバーのアドレスは慎重に選択してください
6.3 データの即時送信
業務シナリオによっては、データをすぐにAEサーバーに送信したい場合があります。その場合はflushインターフェースを呼び出します
TDAnalytics.flush();