応用ガイド
1. ユーザー識別子の設定
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を返す
let distinctId = 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として使われます。
// 送信データから"#account_id"を削除し、以降のデータには"#account_id"が含まれなくなります
TDAnalytics.logout();
logoutは、明示的なログアウトイベントのときに呼び出すことを推奨します。たとえば、ユーザーがアカウントからログアウトする操作を行ったときにのみ呼び出し、Appを閉じるときに呼び出す必要はありません。
このメソッドはログアウトイベントを送信しません
2. イベントの送信
SDKの初期化が完了したら、データのトラッキングを行い、ユーザーの行動情報を収集できます。通常は通常イベントで業務要件を満たせますが、実際の業務シナリオに応じて初回イベントや更新可能イベントなども使用できます。
2.1 通常イベント
trackを呼び出してイベントを送信できます。事前に整理したドキュメントに従ってイベントのプロパティを設定することを推奨します。ここでは、ユーザーが商品を購入する場合を例にします：
TDAnalytics.track({
eventName: "product_buy", // イベント名
properties: {
product_name: "商品名"
} //イベントプロパティ
});
2.2 初回イベント
初回イベントとは、デバイスまたはその他のディメンションのIDに対して、1回だけ記録されるイベントのことです。たとえば、あるデバイスでのアクティベーションイベントを記録したい場合は、初回イベントでデータを送信できます。
TDAnalytics.trackFirst({
eventName: "device_activation",
properties: { key: "value" }
});
デバイス以外のディメンションで初回かどうかを判定したい場合は、初回イベントのfirst_check_idをカスタマイズできます：
// ユーザーIDを初回イベントのfirst_check_idに設定し、ユーザーの初回アクティベーションイベントを収集します
TDAnalytics.trackFirst({
eventName: "account_activation",
firstCheckId: "TA",
properties: { key: "value" }
});
注意：初回かどうかの検証はサーバー側で行われるため、初回イベントはデフォルトで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 共通イベントプロパティ
ユーザーのデバイスID、流入チャネル、ユーザーステータスなどの重要なプロパティは、すべてのイベントに設定する必要があります。その場合、これらのプロパティを共通プロパティ、つまりすべてのイベントに含まれるプロパティとして設定できます。イベントを送信する前に、共通プロパティを設定しておくことを推奨します。
2.5.1 静的共通イベントプロパティ
ユーザーのチャネル、ニックネーム、IDなどの重要なプロパティは、すべてのイベントに設定する必要があります。この場合はsetSuperPropertiesを呼び出して静的共通イベントプロパティを設定できます。静的共通イベントプロパティはグローバルに有効です。
// 共通イベントプロパティを設定すると、すべてのデータのイベントにこれらのプロパティが含まれます
TDAnalytics.setSuperProperties({
channel: "チャネル名",
user_name: "ユーザー名"
});
プロパティの設定以外にも、静的共通イベントプロパティを操作するためのAPIを提供しており、日常的な業務要件に対応できます。
// 静的共通イベントプロパティを取得
let superProperties = TDAnalytics.getSuperProperties();
// 静的共通イベントプロパティを1つクリアします。たとえば以前設定した'channel'プロパティをクリアすると、以降のデータにはこのプロパティが含まれなくなります
TDAnalytics.unsetSuperProperty("channel");
// すべての静的共通イベントプロパティをクリア
TDAnalytics.clearSuperProperties();
2.5.2 動的共通イベントプロパティ
setDynamicSuperPropertiesで動的共通プロパティのコールバック関数を設定すると、SDKはイベントの送信時にコールバック関数をトリガーし、返されたJSONオブジェクトをイベントプロパティに追加します。setDynamicSuperPropertiesのパラメーターは関数で、関数はJSONオブジェクトを返す必要があります。
// 動的共通プロパティを設定します。イベントの送信時にコールバック関数がトリガーされ、返されたJSONオブジェクトがイベントプロパティに追加されます
TDAnalytics.setDynamicSuperProperties(() => {
return {
dy_name: 'xxx',
dy_age: 18
}
})
2.6 イベントの所要時間の記録
あるイベントの継続時間を記録する必要がある場合は、timeEventを呼び出して計測を開始できます。計測したいイベント名を設定しておくと、そのイベントを送信する際に、記録した時間を表す#durationプロパティがイベントプロパティに自動的に追加されます。単位は秒です。なお、同じイベント名で計測中のタスクは1つしか持てません。
//以下の例では、ユーザーがある商品ページに滞在した時間を集計します
TDAnalytics.timeEvent("stay_shop");
/**do someting
.......
**/
//ユーザーが商品ページを離れたら計測を終了。"stay_shop"イベントには、イベントの所要時間を表すプロパティ#durationが含まれます
TDAnalytics.track({
eventName: "stay_shop",
properties: {
product_name: "商品名"
}
});
3. ユーザープロパティ
TAプラットフォームがサポートしているユーザープロパティ設定APIは次のとおりです：userSet、userSetOnce、userAdd、userUnset、userDelete、userAppend、userUniqAppend。
3.1 userSet
一般的なユーザープロパティは、userSetを呼び出して設定できます。このインターフェースで送信したプロパティは、既存のプロパティ値を上書きします。そのユーザープロパティが以前に存在しない場合は新しく作成され、タイプは渡されたプロパティのタイプと同じになります。ここでは、ユーザー名の設定を例にします：
// usernameはTA
TDAnalytics.userSet({
properties: {
username: "TA"
}
});
//usernameはAE
TDAnalytics.userSet({
properties: {
username: "TE"
}
});
3.2 userSetOnce
送信するユーザープロパティを一度だけ設定すればよい場合は、userSetOnceを呼び出して設定できます。そのプロパティにすでに値がある場合、この情報は無視されます。ここでは、初回課金時間の設定を例にします：
//first_payment_timeは2018-01-01 01:23:45.678
TDAnalytics.userSetOnce({
properties: {
first_payment_time: "2018-01-01 01:23:45.678"
}
});
//first_payment_timeは引き続き2018-01-01 01:23:45.678
TDAnalytics.userSetOnce({
properties: {
first_payment_time: "2018-12-31 01:23:45.678"
}
});
3.3 userAdd
数値型のプロパティを送信する場合は、userAddを呼び出してそのプロパティを累積加算できます。そのプロパティがまだ設定されていない場合は、0を代入してから計算します。負の値を渡すと、減算と同じになります。
//この時点でtotal_revenueは30
TDAnalytics.userAdd({
properties: {
total_revenue: 30
}
});
//この時点でtotal_revenueは678
TDAnalytics.userAdd({
properties: {
total_revenue: 648
}
});
3.4 userUnset
ユーザーのユーザープロパティ値をクリアする場合は、userUnsetを呼び出して、指定したプロパティをクリアできます。そのプロパティがまだクラスター内で作成されていない場合、userUnsetはそのプロパティを作成しません
// このユーザーの、ユーザープロパティ名がuserPropertykeyのユーザープロパティ値をクリアします（NULLに設定）
TDAnalytics.userUnset({
property: "userPropertykey"
});
3.5 userDelete
あるユーザーを削除する場合は、userDeleteを呼び出してそのユーザーを削除できます。削除後はそのユーザーのユーザープロパティを照会できなくなりますが、そのユーザーが発生させたイベントは引き続き照会できます。
TDAnalytics.userDelete();
3.6 userAppend
userAppendを呼び出して、配列型のユーザーデータに要素を追加できます。
TDAnalytics.userAppend({
properties: {
user_list: ["apple", "ball"]
}
});
3.7 userUniqAppend
userUniqAppendを呼び出して、Array (List)型のユーザーデータに一意の要素を追加できます。userUniqAppendインターフェースを呼び出すと、追加するユーザープロパティの重複が排除されます。userAppendインターフェースでは重複は排除されないため、ユーザープロパティに重複が存在する場合があります。
//この時点でuser_listのプロパティ値は["apple"，"ball"]
TDAnalytics.userAppend({
properties: {
user_list: ["apple", "ball"]
}
});
//この時点でuser_listのプロパティ値は["apple","apple","ball","cube"]
TDAnalytics.userAppend({
properties: {
user_list: ["apple", "cube"]
}
});
//この時点でuser_listのプロパティ値は["apple"，"ball","cube"]
TDAnalytics.userUniqAppend({
properties: {
user_list: ["apple", "cube"]
}
});
4. 暗号化機能
SDKはAES+RSAによるデータの暗号化に対応しています。データ暗号化機能はクライアントとサーバーの連携が必要です。具体的な使用方法については、カスタマーサクセス担当者にお問い合わせください。
let config = new TDConfig()
config.appId = 'app_id'
config.serverUrl = 'server_url'
//暗号化機能を有効にし、公開鍵情報を設定
config.enableEncrypt(1,'publicKey')
TDAnalytics.initWithConfig(context, config)
5. H5ページとの連携を有効化
H5ページのデータを収集するJavaScript SDKと連携する必要がある場合は、WebViewの初期化時に次のインターフェースを呼び出します
controller: webview.WebviewController = new webview.WebviewController();
TDAnalytics.setJsBridge(controller)
6. その他の機能
6.1 デバイスIDの取得
getDeviceId()を呼び出してデバイスIDを取得できます。
let deviceId = TDAnalytics.getDeviceId();
デバイスIDはキャッシュに保存されるため、ユーザーがキャッシュを削除するとデバイスIDはリセットされます。
6.2 時間の校正
SDKはデフォルトで端末のローカル時間をイベント発生時間として使用します。ユーザーがデバイスの時間を手動で変更すると業務分析に影響が出るため、時間の校正によってイベント発生時間の正確さを確保できます。タイムスタンプ、自動の2種類の時間校正方法を提供しています。
- サーバーから取得した現在のタイムスタンプを使用して、SDKの時間を補正できます。以降、時間を指定していないすべての呼び出し（イベントデータやユーザープロパティの設定操作を含む）では、補正後の時間が発生時間として使用されます。
// 1585633785954は現在のunixタイムスタンプ（単位はミリ秒）で、北京時間の2020-03-31 13:49:45に相当します
TDAnalytics.calibrateTime(1585633785954)
- 自動時間校正を設定することもできます。設定すると、SDKはconfigインターフェースから現在時刻の取得を試み、SDKの時間を校正します。正しい結果が返されなかった場合は、以降はローカル時間でデータを送信します。
let config = new TDConfig()
config.appId = 'appId'
config.serverUrl = 'serverUrl'
//trueに設定すると自動時間補正が有効になります
config.enableAutoCalibrated = true
TDAnalytics.initWithConfig(context, config)
6.3 デフォルトタイムゾーンの設定
デフォルトでは、SDKは端末のローカル時間をイベント発生時間として使用します。デフォルトタイムゾーンを設定するインターフェースでタイムゾーンを指定することもでき、その場合、すべてのイベントのイベント時間は設定したタイムゾーンに合わせて揃えられます：
import I18n from '@ohos.i18n';
let config = new TDConfig()
config.appId = 'appId'
config.serverUrl = 'serverUrl'
config.defaultTimeZone = 8
TDAnalytics.initWithConfig(this.context, config)
指定したタイムゾーンでイベント時間を揃えると、デバイスのローカルタイムゾーン情報は失われます。デバイスのローカルタイムゾーン情報を保持する必要がある場合は、現時点ではご自身でイベントに関連するプロパティを追加する必要があります。
6.4 データの即時送信
業務シナリオによっては、データをすぐにAEサーバーに送信したい場合があります。その場合はflushインターフェースを呼び出します
TDAnalytics.flush();
6.5 GZIP圧縮送信のサポート
1.8.0以降、SDKはgzip圧縮によるデータ送信に対応しています。有効にする方法は次のとおりです：
ohpm install @ohos/flate2
または、dependenciesに依存関係を追加します：
"dependencies": {
"@ohos/flate2": "1.0.0"
}
次に、初期化設定でgzip圧縮を有効にします：
import { gzip } from "@ohos/flate2"
let config = new TDConfig()
config.appId = 'appId'
config.serverUrl = 'serverUrl'
config.enableAutoCalibrated = true
//gzip圧縮を有効にします。デフォルトはfalseです。enableGzipをtrueにする場合は必ずgzipFunを設定してください。設定しないとgzip圧縮を有効にできません
config.enableGzip = true
config.gzipFun = gzip
TDAnalytics.initWithConfig(this.context, config)
flate2の使用をお勧めします。HarmonyOS向けに最適化された高性能ライブラリで、圧縮データを直接操作でき、pakoより高性能です。pakoは処理に時間がかかり性能も低いため、推奨しません。