跳到主要内容

Python

最近更新 2026/08/27

本指南将会为您介绍如何使用 Python SDK 接入您的项目。

最新版本：v3.0.0

更新时间：2023-10-07

资源下载：源代码

注意

当前文档适用于 v3.0.0 及以后的版本，历史版本请参考 Python SDK 接入指南（V2）

一、集成SDK​

  1. 通过pip获取 Python SDK
pip install ThinkingDataSdk

升级命令：

pip install --upgrade ThinkingDataSdk
  1. 安装Logbus

我们推荐使用SDK+LogBus的形式，完成服务端数据的采集上报.您可以参考以下文档完成Logbus的安装:LogBus使用指南

二、初始化​

以下是SDK初始化的示例代码:

from tgasdk.sdk import *

consumer = TDLogConsumer("LOG_DIRECTORY", rotate_mode=TD_ROTATE_MODE.HOURLY, file_prefix="LOG_FILE_PREFIX")
te = TDAnalytics(consumer)

LOG_DIRECTORY为写入本地的文件夹地址。您只需将 LogBus 的监听文件夹地址设置为此处的地址，即可使用 LogBus 进行数据的监听上传。

LOG_FILE_PREFIX为日志文件名字的前缀。

三、常用功能​

为了保证访客 ID 与账号 ID 能够顺利进行绑定，如果您的游戏中会用到访客 ID 与账号 ID，我们极力建议您同时上传这两个 ID，否则将会出现账号无法匹配的情况，导致用户重复计算，具体的 ID 绑定规则可参考用户识别规则一章。

3.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)
  • 事件的名称是字符串类型，只能以字母开头，可包含数字，字母和下划线 "_"，长度最大为 50 个字符。
  • Key 为该属性的名称，为字符串类型，规定只能以字母开头，包含数字，字母和下划线 "_"，长度最大为 50 个字符，对字母大小写不敏感,AE会统一转化为小写字母
  • Value 为该属性的值，支持字符串、数字、布尔、时间、对象、对象组、数组

用户属性的要求与事件属性保持一致

3.2 设置用户属性​

对于一般的用户属性，您可以调用 user_set 来进行设置，使用该接口上传的属性将会覆盖原有的属性值，如果之前不存在该用户属性，则会新建该用户属性，类型与传入属性的类型一致，此处以设置用户名为例：

properties = {"user_name": "ABC"}
# 上传用户属性，"user_name"的值为"ABC"
try:
    te.user_set(account_id="account_id", distinct_id="distinct_id", properties=properties)
except Exception as e:
    # 异常处理
    print(e)

3.3 数据上报​

使用 TDLogConsumer 时，采集到的事件会先转成 json 字符串，然后添加到缓存数组中。当数组元素个数超出设置的容量时才会将数据写入磁盘。默认容量限制为 5 条数据，你可以在 TDLogConsumer 的构造方法中设置 buffer_size 的大小。

在某些业务场景下，如果您期望数据立即上报到AE服务器，可以通过调用flush()接口完成。需要注意，频繁调用flush()会导致服务性能下降。

te.flush();

3.4 关闭SDK​

te.close()

关闭并退出 sdk，请在关闭服务器前调用本接口，以避免缓存内的数据丢失

四、最佳实践​

以下示例代码包含以上所有操作，我们推荐按照如下步骤使用:

from tgasdk.sdk import *

# 初始化SDK
te = TDAnalytics(TDLogConsumer("LOG_DIRECTORY"))

# 上传事件，账号ID与访客ID不能全部为空
properties = {
    "#time": datetime.datetime.now(),  # 设置这条event发生的时间，如果不设置的话，则默认是当前时间
    "#ip": "192.168.1.1",  # 设置用户的IP，tda会自动根据该IP解析省份、城市
    "Product_Name": "商品名"
}
try:
    te.track("distinct_id", "account_id", "Payment", properties)
except Exception as e:
    # 异常处理
    print(e)

# 上传用户属性，"user_name"的值为"ABC"
user_properties = {"user_name": "ABC"}
try:
    te.user_set(account_id="account_id", distinct_id="distinct_id", properties=user_properties)
except Exception as e:
    # 异常处理
    print(e)

# 调用flush接口数据会立即写入文件，生产环境注意避免频繁调用flush引发IO或网络开销问题
te.flush()
这篇文档对你有帮助吗？
本页内容