Corona - Advanced

アカウント ID 設定

SDK インスタンスはランダムの数値でユーザーのゲスト ID として付与します。ゲスト ID はユーザーがログインする前のユーザー識別 ID として使われます。ただし、事前に注意すべきのは、アカウント ID はユーザー再インストールすると変更されます。

1.1 ゲスト ID 設定

::: Tips

一般的には、ゲスト ID を手動設定することは不要で、ユーザー識別ルールを確認した上で、ゲスト ID 設定を行なってください。

もしゲスト ID を変更したい場合は、SDK を初期設定したあとですぐ呼び出すように設定してください。

:::

独自でゲスト ID の管理体制がある場合は、identifyを呼び出して、ゲスト ID を設定してください。

-- set distinct ID as Thinker
ThinkingAnalyticsAPI.identify("Thinker");

現在のゲスト ID を取得したい場合は、getDistinctIdを呼び出して取得できます。

-- returns distinct ID
ThinkingAnalyticsAPI.getDistinctId( function (ret)
    print( "distinctId = " .. ret )
end )

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
ThinkingAnalyticsAPI.login("TE");

この方法ではログインイベントとして送信されません

1.3 アカウント ID をクリア

ユーザーがログアウトイベントを行う前に、Logoutを呼び出して、アカウント ID をクリアすることができます。もう一度Loginを呼び出す前にゲスト ID はユーザー身分の識別 ID として使われます。

ThinkingAnalyticsAPI.logout();

ユーザーがアカウントを削除する際に Logout を呼び出すよう設定してください。

ログアウトイベントとして送信されません。

イベント送信

SDK が初期化設定完了後、データ収集プランに応じて、トラッキングコードを実装し、ユーザーの行動データを収集することができます。一般的には、通常イベント送信は十分収集可能で、実際業務シーンによって、初回・更新可能などの特殊イベント収集することも可能です。

2.1 通常イベント

track を呼び出して、データ収集プランに応じてイベントのプロパティを設定の上、データ送信できます。

例：アイテム購入

local properties = { product_name="product name"}
ThinkingAnalyticsAPI.track("product_buy", properties)

2.2 初回イベント

初回イベントはあるデバイスもしくはその他分析主体の ID ごとで、1 回目のみ記録されるイベントとなります。

例えば：あるデバイスのアクティブイベントはそれを使って便利です

ThinkingAnalyticsAPI.trackFirst("device_activation", {test_string="first_string"})

もしデバイス以外で初回判断したい場合は、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.
ThinkingAnalyticsAPI.trackFirst("account_activation", {test_string="first_string"} , "TA")

注意：サーバ側で初回なのかを検証するため、初回イベントはデフォルトで 1 時間遅延して格納されます。

2.3 更新可能イベント

通常イベントはデータを格納されたら更新不可となりますが、データ更新を行いたい場合は、更新可能イベントを利用してください。更新可能イベントは識別イベントの ID が必要で、作成時はプロパティに入れてください。TE システムはイベント名とイベント ID を識別対象として更新データを確定します。

-- The event property status is 3 after reporting, with the price being 100
ThinkingAnalyticsAPI.trackUpdate("UPDATABLE_EVENT", {
    status = 3,
    price = 100
}, "Update_EventId")

-- The event property status is 5 after reporting, with the price remaining the same
ThinkingAnalyticsAPI.trackUpdate("UPDATABLE_EVENT", {
    status = 5
}, "Update_EventId")

2.4 書き替えイベント

書き替えイベントは更新可能イベントと同じようで、書き替えイベントは過去データを最新のデータで上書きされるため、前のデータを削除し新しくデータを格納するように見られます。TE システムはイベント名とイベント ID を識別対象として更新データを確定します。

-- The event property status is 3 after reporting, with the price being 100
ThinkingAnalyticsAPI.trackOverwrite("OVERWRITABLE_EVENT", {
    status = 3,
    price = 100
}, "Overwrite_EventId")

-- The event property status is 5 after reporting, with the price deleted
ThinkingAnalyticsAPI.trackOverwrite("OVERWRITABLE_EVENT", {
    status = 5
}, "Overwrite_EventId")

2.5 共通イベントプロパティ

共通イベントプロパティは全てのイベント送信する際に付属されているプロパティとなります。プロパティの更新頻度により、共通イベントプロパティは静的共通イベントプロパティと動的共通イベントプロパティがあります。

実際業務ニーズに応じて、共通イベントプロパティの設定を行なってください；通常イベント送信する前に、共通イベントプロパティを設定してくのはオススメです。

同じイベントに、共通イベントプロパティ、イベントカスタムプロパティ、プリセットプロパティの Key は同じの場合は、以下の優先順位で値付けされます。カスタムプロパティ＞動的共通イベントプロパティ＞静的共通イベントプロパティ＞プリセットプロパティ。

2.5.1 静的共通イベントプロパティ

静的共通イベントプロパティは低頻度変化かつ全てのイベントの属しているプロパティ：例えば VIP レベル。setSuperPropertiesを利用して、静的共通イベントプロパティを設定したら、SDK はイベント収集時に設定されている共通イベントプロパティを当イベントのプロパティとして利用されます。

--- set super properties
ThinkingAnalyticsAPI.setSuperProperties({vip_level = 2})

静的共通イベントプロパティはキャッシュに保存されるため、APP を起動するたびに呼び出す必要はありません。もしそのプロパティが存在されているのであれば、新たに設定するプロパティは元のプロパティ値を書き替えされます；もし以前そのプロパティが存在しない場合は、新規プロパティとして作成されます。プロパティ設定以外には API 利用で静的共通イベントプロパティを管理できます。

-- clear a super property named 'Channel'
ThinkingAnalyticsAPI.unsetSuperProperties("Channel")
-- clear all super properties
ThinkingAnalyticsAPI.clearSuperProperties()
-- get all super properties
ThinkingAnalyticsAPI.getSuperProperties()

2.6 イベント時間記録

イベントの経過時間を記録したい場合は、timeEventを呼び出して計算可能です。計算したいイベント名称を設定し、該当イベントが送信される際に、自動的にイベントプロパティに#durationのプロパティを追加され、経過時間を記録されます。単位は秒です。

注意：一つイベントに対しては一個の時間経過計算タスクのみつけることが可能です。

-- The following instance has recorded the time the user spent on a certain product page
-- The user enters the product page and starts the timing
ThinkingAnalyticsAPI.timeEvent("stay_shop")
-- do some thing...
-- the timing would end when the user leaves the product page. "stay_shop" event would carry#duration, a property representing event duration.
ThinkingAnalyticsAPI.track("stay_shop", {})

ユーザープロパティ

TE でユーザープロパティを設定する API は：userSet()、userSetOnce()、userAdd()、userAppend()、userUnset()、userDelete()。

3.1 userSet

一般的にユーザープロパティ設定はuserSetを用いて設定できます。この呼び出しを利用して元のプロパティ値を書き替えされます。元のプロパティ値がない場合は、新規作成になります。データタイプは格納されたデータタイプと一致します。以下は例：

-- current username is TA
ThinkingAnalyticsAPI.userSet({user_name = "TA"})
-- current username is TE
ThinkingAnalyticsAPI.userSet({user_name = "TE"})

3.2 userSetOnce

もしユーザープロパティは一回設定の上で変更がない場合は、userSetOnceを用いて設定できます。この呼び出しは値のある際に書き替えを行いません。例：初回課金時間設定

--first_payment_time is '2018-01-01 01:23:45.678'
ThinkingAnalyticsAPI.userSetOnce({first_payment_time = "2018-01-01 01:23:45.678"})
-- first_payment_time is '2018-01-01 01:23:45.678' as before
ThinkingAnalyticsAPI.userSetOnce({first_payment_time = "2018-12-31 01:23:45.678"})

3.3 userAdd

もし数値型のプロパティで累積計算を行いたい場合は、userAddを用いて設定できます。この呼び出しは値のない際に自動で 0 を付与した上で計算されます。“-”値で計算することも可能で、例：累積課金金額

-- current total_revenue is 30
ThinkingAnalyticsAPI.userAdd({total_revenue = 30})
-- current total_revenue is 678
ThinkingAnalyticsAPI.userAdd({total_revenue = 648})

設定のプロパティ Key は文字列で、Value は数値のみとなります。

3.4 userAppend

userAppend()を用いて、Array型のユーザープロパティを追加できます。

-- append user properties with array
ThinkingAnalyticsAPI.userAppend({user_list = {"apple", "ball"}})

3.5 userUnset

ユーザープロパティをリセットしたい場合は、userUnset()を用いて設定できます。

-- remove a user property named 'age'
ThinkingAnalyticsAPI.userUnset("age")

受信される値はクリアされたプロパティの Key 値となります。

3.6 userDelete

ユーザーを削除したい場合はuserDelete()を用いて設定できます。削除したら当ユーザーのユーザープロパティはクエリできなくなりますが、当ユーザーが生成したイベントデータはクエリできます。

-- remove all user properties
ThinkingAnalyticsAPI.userDelete()

その他機能

4.1 デバイス ID を取得

getDeviceIdを呼び出して、デバイス ID を取得できます：

-- get device ID
ThinkingAnalyticsAPI.getDeviceId( function (ret)
    print( "deviceId = " .. ret )
end )