応用ガイド
1. ユーザーIDの設定
SDKインスタンスはデフォルトで乱数を各ユーザーのデフォルトのゲストIDとして使用します。このIDは、ユーザーが未ログインの状態での識別IDとして使われます。なお、ゲストIDはユーザーがAppを再インストールしたり、デバイスを変更したりすると変わります。
1.1 ゲストIDの設定
通常、ゲストIDをカスタマイズする必要はありません。ユーザー識別ルールを理解したうえで、ゲストIDを設定してください。
ゲストIDを置き換える必要がある場合は、SDKの初期化が完了した直後に呼び出してください。不要なアカウントが生成されないよう、複数回呼び出さないでください
ゲームで各ユーザーに独自のゲストID管理体系がある場合は、setDistinctIdを呼び出してゲストIDを設定できます：
-- ゲストIDをThinkerに設定
TDAnalytics.setDistinctId("Thinker");
現在のゲストIDを取得する必要がある場合は、getDistinctIdを呼び出して取得できます：
--ゲストIDを返す
TDAnalytics.getDistinctId( function (ret)
print( "distinctId = " .. ret )
end )
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. イベントの送信
SDKの初期化が完了したら、データのトラッキングを行い、ユーザーの行動情報を収集できます。通常は通常イベントで業務シナリオの要件を満たせますが、実際の業務シナリオに応じて、初回イベントや更新可能イベントなどを使用することもできます。
2.1 通常イベント
trackを呼び出してイベントを送信できます。事前に整理したドキュメントに従って、イベントのプロパティと送信条件を設定することをお勧めします。ここでは、ユーザーが商品を購入する場合を例にします：
local properties = {
product_name = "商品名"
}
TDAnalytics.track("product_buy", properties)
2.2 初回イベント
初回イベントとは、デバイスまたはその他のディメンションのIDに対して、1回だけ記録されるイベントのことです。たとえば、あるデバイスでのアクティベーションイベントを記録したい場合は、初回イベントでデータを送信できます。
-- 例：デバイスの初回イベントを送信します。イベント名はdevice_activationとします
TDAnalytics.trackFirst("device_activation", {
test_string="first_string"
})
デバイス以外のディメンションで初回かどうかを判定したい場合は、初回イベントのfirst_check_idをカスタマイズできます：
-- ユーザーIDを初回イベントのfirst_check_idに設定し、ユーザーの初回アクティベーションイベントを収集します
TDAnalytics.trackFirst("account_activation", {
test_string="first_string"
} , "TA")
注意：初回かどうかの検証はサーバー側で行われるため、初回イベントはデフォルトで1時間遅れて取り込まれます。
2.3 更新可能イベント
更新可能イベントを使用すると、特定のシナリオでイベントデータを変更する必要がある場合に対応できます。更新可能イベントでは、そのイベントを識別するIDを指定し、更新可能イベントのオブジェクトを作成する際に渡す必要があります。AE管理画面は、イベント名とイベントIDに基づいて更新するデータを特定します。
-- 例：更新可能なイベントを送信します。イベント名はUPDATABLE_EVENTとします
-- 送信後、イベントプロパティstatusは3、priceは100になります
TDAnalytics.trackUpdate("UPDATABLE_EVENT", {
status = 3,
price = 100
}, "Update_EventId")
-- 送信後、イベントプロパティstatusは5に更新され、priceは変わりません
TDAnalytics.trackUpdate("UPDATABLE_EVENT", {
status = 5
}, "Update_EventId")
2.4 上書き可能イベント
上書き可能イベントは更新可能イベントと似ていますが、上書き可能イベントでは最新のデータで過去のデータを完全に上書きする点が異なります。効果としては、前のデータを削除して最新のデータを格納するのと同じです。AE管理画面は、イベント名とイベントIDに基づいて更新するデータを特定します。
-- 例：上書き可能なイベントを送信します。イベント名はOVERWRITABLE_EVENTとします
TDAnalytics.trackOverwrite("OVERWRITABLE_EVENT", {
status = 3,
price = 100
}, "Overwrite_EventId")
-- 送信後、イベントプロパティstatusは5に更新され、priceプロパティは削除されます
TDAnalytics.trackOverwrite("OVERWRITABLE_EVENT", {
status = 5
}, "Overwrite_EventId")
2.5 共通イベントプロパティ
共通イベントプロパティとは、すべてのイベントで送信されるプロパティのことです。プロパティの更新頻度に応じて、共通イベントプロパティは静的共通イベントプロパティと動的共通イベントプロパティに分けられます。具体的な業務シナリオの要件に応じて、異なる共通イベントプロパティの設定方法を選択できます。イベントを送信する前に、共通イベントプロパティを設定しておくことを推奨します。同じイベントで、共通イベントプロパティ、イベントのカスタムプロパティ、プリセットプロパティのKeyが同じ場合は、次の優先順位で値が設定されます：カスタムプロパティ>動的共通イベントプロパティ>静的共通イベントプロパティ>プリセットプロパティ。
2.5.1 静的共通イベントプロパティ
静的共通イベントプロパティとは、変化の頻度が低く、すべてのイベントに含まれるプロパティのことです（ユーザーの会員レベルなど）。setSuperPropertiesで静的共通イベントプロパティを設定すると、SDKはイベントの収集時に、設定された共通イベントプロパティをイベントのプロパティとして取得します。
-- 共通プロパティを設定
TDAnalytics.setSuperProperties({
vip_level = 2
})
静的共通イベントプロパティはキャッシュに保存されるため、Appを起動するたびに呼び出す必要はありません。そのプロパティがすでに存在する場合は、再設定したプロパティで元のプロパティ値が上書きされます。そのプロパティが存在しない場合は、新しく作成されます。プロパティの設定以外にも、静的共通イベントプロパティを操作するためのAPIを提供しており、日常的な業務要件に対応できます。
-- プロパティ名がtripの共通プロパティをクリア
TDAnalytics.unsetSuperProperties("trip")
-- すべての共通プロパティをクリア
TDAnalytics.clearSuperProperties()
-- すべての共通プロパティを取得
TDAnalytics.getSuperProperties( function (ret)
local superProperties = ret
print( "current superProperties = " .. superProperties )
end )
2.6 イベントの所要時間の記録
あるイベントの継続時間を記録する必要がある場合は、timeEventを呼び出して計測を開始できます。計測したいイベント名を設定しておくと、そのイベントを送信する際に、記録した時間を表す#durationプロパティがイベントプロパティに自動的に追加されます。単位は秒です。なお、同じイベント名で計測中のタスクは1つしか持てません。
--以下の例では、ユーザーがある商品ページに滞在した時間を集計します
-- ユーザーが商品ページに入ったら計測を開始
TDAnalytics.timeEvent("stay_shop")
-- do some thing...
-- ユーザーが商品ページを離れたら計測を終了。"stay_shop"イベントには、イベントの所要時間を表すプロパティ#durationが含まれます
TDAnalytics.track("stay_shop")
3. ユーザープロパティ
AEプラットフォームが対応しているユーザープロパティ設定APIは、userSet、userSetOnce、userAdd、userAppend、userUnset、userDeleteです。
3.1 userSet
一般的なユーザープロパティは、userSetを呼び出して設定できます。このインターフェースで送信したプロパティは、既存のプロパティ値を上書きします。そのユーザープロパティが以前に存在しない場合は新しく作成され、タイプは渡されたプロパティのタイプと同じになります。ここでは、ユーザー名の設定を例にします
-- この時点でusernameはTA
TDAnalytics.userSet({
user_name = "TA"
})
-- この時点でusernameはAE
TDAnalytics.userSet({
user_name = "TE"
})
3.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"
})
3.3 userAdd
数値型のプロパティを送信する場合は、userAddを呼び出してそのプロパティを累積加算できます。そのプロパティがまだ設定されていない場合は、0を代入してから計算します。負の値を渡すこともでき、その場合は減算と同じになります。ここでは、累積課金額を例にします：
-- この時点でtotal_revenueは30
TDAnalytics.userAdd({
total_revenue = 30
})
-- この時点でtotal_revenueは678
TDAnalytics.userAdd({
total_revenue = 648
})
設定するプロパティのkeyは文字列で、Valueには数値のみ指定できます。
3.4 userAppend
userAppendを呼び出して、Array型のユーザープロパティに要素を追加できます:
-- リスト型のユーザープロパティに要素を追加
TDAnalytics.userAppend({
weapon = {"m41", "bulldog"}
})
3.5 userUnset
ユーザーのあるプロパティをリセットする場合は、userUnsetを呼び出して、そのユーザーの指定したユーザープロパティの値をクリアできます。このインターフェースは、文字列型のパラメータに対応しています:
-- 指定したユーザープロパティをクリア
TDAnalytics.userUnset("age")
渡す値は、クリアするプロパティのKey値です。
3.6 userDelete
あるユーザーを削除する場合は、userDeleteを呼び出してそのユーザーを削除できます。削除後はそのユーザーのユーザープロパティを照会できなくなりますが、そのユーザーが発生させたイベントは引き続き照会できます。
-- ユーザーを削除
TDAnalytics.userDelete()
4. その他の機能
4.1 デバイスIDの取得
SDKは初期化が完了すると、デバイスIDを自動的に生成してローカルキャッシュに記録します。同じアプリまたはゲームであれば、1台のデバイスのデバイスIDは変わりません。getDeviceIdを呼び出してデバイスIDを取得できます：
-- デバイスIDを取得
TDAnalytics.getDeviceId( function (ret)
print( "deviceId = " .. ret )
end )