応用ガイド

最終更新 2026/10/05

1. イベントの送信

SDKの初期化が完了したら、データのトラッキングを行い、ユーザーの行動情報を収集できます。通常は通常イベントで業務シナリオの要件を満たせますが、実際の業務シナリオに応じて、初回イベントや更新可能イベントなどを使用することもできます。

1.1 通常イベント

trackを呼び出してイベントを送信できます。事前に整理したドキュメントに従って、イベントのプロパティと送信条件を設定することをお勧めします。ここでは、ユーザーが商品を購入する場合を例にします：

--イベントプロパティを設定
local properties = {}
--イベントの発生時刻を設定。設定しない場合は、デフォルトで現在時刻を使用します
properties["#time"] = os.date("%Y-%m-%d %H:%M:%S")

--ユーザーのIPアドレスを設定。AEシステムはIPアドレスからユーザーの地理位置情報を解析します。設定しない場合、デフォルトでは送信されません
properties["#ip"] = "192.168.1.1"

properties["Product_Name"] = "card"
properties["Price"] = 30
properties["OrderId"] = "abc_123"
--イベントをアップロード。ユーザーのゲストIDとアカウントIDを含みます。アカウントIDとゲストIDの順序に注意してください
sdk:track("accountId", "distinctId", "payment", properties)

1.2 初回イベント

初回イベントとは、デバイスまたはその他のディメンションのIDに対して、1回だけ記録されるイベントのことです。たとえば、あるデバイスでのアクティベーションイベントを記録したい場合は、初回イベントでデータを送信できます。

local properties = {}
--first_check_idの値を設定する必要があります
sdk:trackFirst("accountId", "distinctId", "device_activation", "first_check_id", properties)

注意：初回かどうかの検証はサーバー側で行われるため、初回イベントはデフォルトで1時間遅れて取り込まれます。

1.3 更新可能イベント

更新可能イベントを使用すると、特定のシナリオでイベントデータを変更する必要がある場合に対応できます。更新可能イベントでは、そのイベントを識別するIDを指定し、更新可能イベントのオブジェクトを作成する際に渡す必要があります。AE管理画面は、イベント名とイベントIDに基づいて更新するデータを特定します。

-- "price" is 80, "count" is 3
local properties = {}
properties["price"] = 80
properties["count"] = 3
sdk:trackUpdate("accountId", "distinctId", "eventName", "eventId", properties)

-- The "price" is still 80, The "count" has changed to 5
local newProperties = {}
newProperties["count"] = 5
sdk:trackUpdate("accountId", "distinctId", "eventName", "eventId", newProperties)

1.4 上書き可能イベント

上書き可能イベントは更新可能イベントと似ていますが、上書き可能イベントでは最新のデータで過去のデータを完全に上書きする点が異なります。効果としては、前のデータを削除して最新のデータを格納するのと同じです。AE管理画面は、イベント名とイベントIDに基づいて更新するデータを特定します。

-- "price" is 80, "count" is 3
local properties = {}
properties["price"] = 80
properties["count"] = 3
sdk:trackOverwrite("accountId", "distinctId", "eventName", "eventId", properties)

-- The "count" has changed to 5，The "price" will be deleted
local newProperties = {}
newProperties["count"] = 5
sdk:trackOverwrite("accountId", "distinctId", "eventName", "eventId", newProperties)

2. ユーザープロパティ

AEプラットフォームが対応しているユーザープロパティ設定APIは、userSet、userSetOnce、userAdd、userUnset、userDel、userAppend、userUniqueAppendです。

2.1 userSet

一般的なユーザープロパティは、userSetを呼び出して設定できます。このインターフェースで送信したプロパティは、既存のプロパティ値を上書きします。そのユーザープロパティが以前に存在しない場合は新しく作成され、タイプは渡されたプロパティのタイプと同じになります。ここでは、ユーザー名の設定を例にします：

local userSetProperties = {}
userSetProperties["user_name"] = "ABC"
userSetProperties["#time"] = os.date("%Y-%m-%d %H:%M:%S")
--ユーザープロパティをアップロード
sdk:userSet("accountId", "distinctId", userSetProperties)

userSetProperties = {}
userSetProperties["user_name"] = "abc"
userSetProperties["#time"] = os.date("%Y-%m-%d %H:%M:%S")
--ユーザープロパティを再度アップロード。この時点で"user_name"の値は"abc"に上書きされます
sdk:userSet("accountId", "distinctId", userSetProperties)

2.2 userSetOnce

設定するユーザープロパティが一度だけ設定すればよいものである場合は、userSetOnceを呼び出して設定できます。そのプロパティにすでに値がある場合、この情報は無視されます。ここでもユーザー名の設定を例にします：

local userSetOnceProperties = {}
userSetOnceProperties["user_name"] = "ABC"
userSetOnceProperties["#time"] = os.date("%Y-%m-%d %H:%M:%S")
--ユーザープロパティをアップロード。"user_name"を新規作成し、値は"ABC"です
sdk:userSetOnce("accountId", "distinctId", userSetOnceProperties)

userSetOnceProperties = {}
userSetOnceProperties["user_name"] = "abc"
userSetOnceProperties["user_age"] = 18
userSetOnceProperties["#time"] = os.date("%Y-%m-%d %H:%M:%S")
--ユーザープロパティを再度アップロード。この時点で"user_name"の値は上書きされず"ABC"のままで、"user_age"の値は18です
sdk:userSetOnce("accountId", "distinctId", userSetOnceProperties)

2.3 userAdd

数値型のプロパティを送信して累積加算を行う場合は、userAddを呼び出せます。そのプロパティがまだ設定されていない場合は、0を代入してから計算します。負の値を渡すこともでき、その場合は減算と同じになります。ここでは、累積課金額を例にします：

local userAddProperties = {}
userAddProperties["total_revenue"] = 30
userAddProperties["#time"] = os.date("%Y-%m-%d %H:%M:%S")
--ユーザープロパティをアップロード。この時点で"total_revenue"の値は30です
sdk:userAdd("accountId", "distinctId", userAddProperties)

userAddProperties = {}
userAddProperties["total_revenue"] = 60
userAddProperties["#time"] = os.date("%Y-%m-%d %H:%M:%S")
--ユーザープロパティを再度アップロード。この時点で"total_revenue"の値は累積加算されて90になります
sdk:userAdd("accountId", "distinctId", userAddProperties)

設定するプロパティのkeyは文字列で、Valueには数値のみ指定できます。

2.4 userAppend

userAppendを呼び出して、配列型のユーザープロパティに要素を追加できます。

local equips = {}
equips[1] = "weapon"
equips[2] = "hat"
local userAppendProperties = {}
userAppendProperties["equips"] = equips
userAppendProperties["#time"] = os.date("%Y-%m-%d %H:%M:%S")
--ユーザープロパティをアップロード。この時点で"equips"の値は["weapon", "hat"]です
sdk:userAppend("accountId", "distinctId", userAppendProperties)

equips = {}
equips[1] = "clothes"
userAppendProperties = {}
userAppendProperties["equips"] = equips
userAppendProperties["#time"] = os.date("%Y-%m-%d %H:%M:%S")
--ユーザープロパティを再度アップロード。この時点で"equips"の値に"clothes"が1つ追加されます:["weapon", "hat", "clothes"]
sdk:userAppend("accountId", "distinctId", userAppendProperties)

2.5 userUniqueAppend

userUniqueAppendを呼び出して、配列型のユーザープロパティに要素を追加できます。userUniqueAppendインターフェースを呼び出すと、追加するユーザープロパティの重複が排除されます。 userAppendインターフェースでは重複は排除されず、ユーザープロパティに重複が存在する場合があります。

local profiles_append = {}
--実行後、ユーザープロパティappendは["test_append"]になります
profiles_append["append"] = { "test_append" }
sdk:userAppend("accountId", "distinctId", profiles_append)

local profiles_uniq_append = {}
--実行後、ユーザープロパティappendは["test_append", "test_append1"]になります
profiles_uniq_append["append"] = {"test_append", "test_append1"}
sdk:userUniqueAppend("accountId", "distinctId", profiles_uniq_append)

2.6 userUnset

ユーザーのユーザープロパティの値をクリアする場合は、userUnsetを呼び出して指定したプロパティをクリアできます。そのプロパティがまだクラスター内で作成されていない場合、userUnsetはそのプロパティを作成しません

local userUnsetProperties = {}
userUnsetProperties[1] = "total_revenue"
userUnsetProperties[2] = "equips"
--ユーザープロパティをアップロード。この時点で"total_revenue"と"equips"の2つのプロパティがリセットされます
sdk:userUnset("accountId", "distinctId", userUnsetProperties)

userUnset: には、クリアするプロパティのKey値を渡します。

2.7 userDel

あるユーザーを削除する場合は、userDelを呼び出してそのユーザーを削除できます。削除後はそのユーザーのユーザープロパティを照会できなくなりますが、そのユーザーが発生させたイベントは引き続き照会できます。この操作は元に戻せない結果を招く可能性があるため、慎重に使用してください

sdk:userDel("accountId", "distinctId")

3. その他の機能

3.1 TDBatchConsumer

注意

データ量が多すぎる場合やネットワークに異常がある場合は、データが失われるおそれがあるため、本番環境での使用はお勧めしません

データをバッチでリアルタイムにAEサーバーへ送信します。転送ツールと組み合わせる必要はありません。

local tdAnalytics = require "ThinkingDataSdk"
local consumer = tdAnalytics.TDBatchConsumer("SERVER_URL", "APP_ID")
local sdk = tdAnalytics(consumer)

パラメータの説明:

• APP_ID: プロジェクトのAPP IDです。AE管理画面の「プロジェクト管理」ページで取得できます

• SERVER_URL: データの送信先URL

  • クラウドサービスをご利用の場合は、次を入力します: https://global-receiver-ta.thinkingdata.cn
  • プライベートデプロイ版をご利用の場合は、データ収集アドレスにドメインをバインドし、HTTPS証明書を設定してください：https://データ収集アドレスにバインドしたドメイン