応用ガイド

最終更新 2026/08/27

1. イベントの送信

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

1.1 通常イベント

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

distinct_id = "ABCDEF123456"
account_id = "TE10001"
properties = {
    "#time": datetime.datetime.now(),
    # このeventの発生時刻を設定します。設定しない場合は、デフォルトで現在時刻になります
    "#ip": "192.168.1.1",
    # ユーザーのIPを設定します。tdaはこのIPから都道府県・市区町村を自動的に解析します
    # "#uuid":uuid.uuid1(),#任意。上記のenable_uuidスイッチがオンの場合は入力不要です
    "Product_Name": "商品名",
    "Price": 30,
    "OrderId": "注文番号abc_123"
}

# イベントを送信します（アカウントIDとゲストIDを含む）
try:
    te.track(distinct_id, account_id, "Payment", properties)
    # ゲストIDのみを送信することもできます
    # te.track(distinct_id = distinct_id, event_name = "Payment", properties = properties)
    # またはアカウントIDのみを送信します
    # te.track(account_id = account_id, event_name = "Payment", properties = properties)
except Exception as e:
    # 例外処理
    print(e)

1.2 初回イベント

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

# 初回イベントを呼び出します
try:
    properties = {'name': 'hello'}
    te.track_first(account_id="account_id", distinct_id="distinct_id", event_name='first_event', first_check_id='first_flag_id', properties=properties)
except Exception as e:
    # 例外処理
    raise TDIllegalDataException(e)

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

1.3 更新可能イベント

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

# 例: 更新可能なイベントを送信します。イベント名はUPDATABLE_EVENTとします
distinct_id = "65478cc0-275a-4aeb-9e6b-861155b5aca7"
account_id = "123"
event_name = "UPDATABLE_EVENT"
event_id = "123"
properties = {
    "price": 100,
    "status": 3
}
# 送信後、イベントプロパティstatusは3、priceは100になります
te.track_update(distinct_id=distinct_id, account_id=account_id, event_name=event_name, event_id=event_id,
                properties=properties)

# 送信後、同じevent_name + event_idのイベントのプロパティstatusは5に更新され、priceは変わりません
new_properties = {
    "status": 5
}
te.track_update(distinct_id=distinct_id, account_id=account_id, event_name=event_name, event_id=event_id,
                properties=new_properties)

1.4 上書き可能イベント

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

# 例： 上書き可能なイベントを送信します。イベント名はOVERWRITE_EVENTとします
distinct_id = "65478cc0-275a-4aeb-9e6b-861155b5aca7"
account_id = "123"
event_name = "OVERWRITE_EVENT"
event_id = "123"
properties = {
    "price": 100,
    "status": 3
}
# 送信後、イベントプロパティstatusは3、priceは100になります
te.track_overwrite(distinct_id=distinct_id, account_id=account_id, event_name=event_name, event_id=event_id,
                   properties=properties)

# 送信後、イベントプロパティstatusは5に更新され、priceプロパティは削除されます
new_properties = {
    "status": 5
}
te.track_overwrite(distinct_id=distinct_id, account_id=account_id, event_name=event_name, event_id=event_id,
                   properties=new_properties)

2. ユーザープロパティ

AEプラットフォームでは、次のユーザープロパティ設定APIに対応しています：user_set、user_setOnce、user_add、

user_unset、user_del、user_append、user_uniq_append。

2.1 user_set

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

properties = {"user_name": "ABC"}
# ユーザープロパティを送信します。"user_name"の値は"ABC"です
try:
    te.user_set(account_id="account_id", distinct_id="distinct_id", properties=properties)
    properties = {"user_name": "XYZ"}
    # 再度ユーザープロパティを送信します。このとき"user_name"の値は"XYZ"で上書きされます
    te.user_set(account_id="account_id", distinct_id="distinct_id", properties=properties)
except Exception as e:
    # 例外処理
    print(e)

2.2 user_setOnce

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

properties = {"user_name": "ABC"}
# ユーザープロパティを送信します。"user_name"の値は"ABC"です
try:
    te.user_setOnce(account_id="account_id", distinct_id="distinct_id", properties=properties)
except Exception as e:
    # 例外処理
    print(e)
properties = {
    "user_name": "XYZ",
    "user_age": 18
}
# 再度ユーザープロパティを送信します。このとき"user_name"にはすでに値があるため変更されず、"ABC"のままです。"user_age"の値は18です
try:
    te.user_setOnce(account_id="account_id", distinct_id="distinct_id", properties=properties)
except Exception as e:
    # 例外処理
    print(e)

2.3 user_add

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

properties = {
    "total_revenue": 30,
    "vip_level": 1
}
# ユーザープロパティを送信します。このとき"total_revenue"の値は30、"vip_level"の値は1です
te.user_add(account_id="account_id", distinct_id="distinct_id", properties=properties)

properties = {"total_revenue": 90}
# ユーザープロパティを送信します。このとき"total_revenue"の値は90、"vip_level"の値は1です
try:
    te.user_add(account_id="account_id", distinct_id="distinct_id", properties=properties)
except Exception as e:
    # 例外処理
    print(e)

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

2.4 user_append

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

list1 = ['Google']
# arrKey1、arrKey2の配列型プロパティに要素を追加します
properties = {'arrKey1': list1, 'arrKey2': ['11', '22']}
try:
    te.user_append(account_id="account_id", distinct_id="distinct_id", properties=properties)
except Exception as e:
    # 例外処理
    print(e)

2.5 user_uniq_append

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

arrayValue = ['Google', 'True', '2.222']
properties = {'arrKey4': arrayValue, 'arrKey3': ['appendList', '222'], 'dict1': {'name': 'Tom', 'Age': 28}}
try:
    # 実行後、ユーザープロパティarrKey4は['Google', True, 2.222]、arrKey3は['appendList', '222']になります
    te.user_append(account_id="account_id", distinct_id="distinct_id", properties=properties)
except Exception as e:
    # 例外処理
    raise TDIllegalDataException(e)

properties = {'arrKey4': ['addValue', 'True'], 'arrKey3': ['appendList', '222']}
try:
    # 実行後、ユーザープロパティarrKey4は['Google', True, 2.222, 'addValue']、arrKey3は['appendList', '222']になります
    te.user_uniq_append(account_id="account_id", distinct_id="distinct_id", properties=properties)
except Exception as e:
    # 例外処理
    raise TDIllegalDataException(e)

2.6 user_unset

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

try:
    te.user_unset("distinct_id", "account_id", ["string1", "lastTime"])
except Exception as e:
    # 例外処理
    print(e)

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

2.7 user_del

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

try:
    te.user_del(account_id="account_id", distinct_id="distinct_id")
except Exception as e:
    # 例外処理
    print(e)

3. その他の機能

3.1 TDBatchConsumer

注意

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

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

te = TDAnalytics(TDBatchConsumer("SERVER_URL", "APP_ID"))

パラメータの説明:

APP_ID: プロジェクトのAPP IDです。AE管理画面の「プロジェクト管理」ページで取得できます
SERVER_URL: データの送信先URL
- クラウドサービスをご利用の場合は、次を入力します: https://global-receiver-ta.thinkingdata.cn
- プライベートデプロイ版をご利用の場合は、データ収集アドレスにドメインをバインドし、HTTPS証明書を設定してください：https://データ収集アドレスにバインドしたドメイン

このページは役に立ちましたか？

1. イベントの送信​

1.1 通常イベント​

1.2 初回イベント​

1.3 更新可能イベント​

1.4 上書き可能イベント​

2. ユーザープロパティ​

2.1 user_set​

2.2 user_setOnce​

2.3 user_add​

2.4 user_append​

2.5 user_uniq_append​

2.6 user_unset​

2.7 user_del​

3. その他の機能​

3.1 TDBatchConsumer​