# Python
本指南将会为您介绍如何使用 Python SDK 接入您的项目。
最新版本:v3.0.0
更新时间:2023-10-07
注意
当前文档适用于 v3.0.0 及以后的版本,历史版本请参考 Python SDK 接入指南(V2) (opens new window)
# 一、集成SDK
- 通过
pip
获取 Python SDK
pip install ThinkingDataSdk
升级命令:
pip install --upgrade ThinkingDataSdk
- 安装Logbus
我们推荐使用SDK+LogBus的形式,完成服务端数据的采集上报.您可以参考以下文档完成Logbus的安装:LogBus使用指南
# 二、初始化
以下是SDK初始化的示例代码:
from tgasdk.sdk import *
te = TDAnalytics(TDLogConsumer("LOG_DIRECTORY"))
LOG_DIRECTORY
为写入本地的文件夹地址。您只需将 LogBus 的监听文件夹地址设置为此处的地址,即可使用 LogBus 进行数据的监听上传
# 三、常用功能
为了保证访客 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 个字符,对字母大小写不敏感,TE会统一转化为小写字母
- 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)
# 四、最佳实践
以下示例代码包含以上所有操作,我们推荐按照如下步骤使用:
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()