菜单

Python

更新时间：2024-12-10
下载：最新版
⚠️ 此 SDK 需搭配 FileScout 使用

ⓘ 最低支持的 Python 版本：3.7

一、集成 SDK

① 通过 pip 下载安装

下载
bash 复制代码
```
pip install dt-python-sdk
```
升级
bash 复制代码
```
pip install --upgrade dt-python-sdk
```

② 自行下载安装

根据运行平台下载最新 SDK 的 whl 包

安装 whl 包

bash 复制代码

pip install {path}/dt-python-sdk-{xxx}.whl

⚠️ 注意
对于 Python 3.7 需要安装如下依赖（Python 3.8 及以上无需此操作）：
pip install importlib-metadata

二、初始化

SDK 初始化示例代码

Python 复制代码

from dt_python_sdk import *

# Outputs to "log" folder in execution path with file prefix "dt_event" 
# for every 200 events, the ideal maximum size for each log file is 10MB 
# (will be larger if size of a single event is over such limit).
consumer = DTLogConsumer("log", 200, "dt_event", 10*1024*1024)
# with debug: False
dt = DTAnalytics(consumer, False)

三、基础功能

事件上报和用户属性的所有接口会对事件名/属性名/类型进行校验

如果校验通过会返回 true，并进行记录上报

未通过则会返回 false，不进行记录上报

3.1 设置事件上报

数据说明文档：当您将要上报的事件/属性在数据说明文档中已存在时，强烈建议您使用文档中的对应属性名，比如您要上报 APP 的操作系统属性，请使用文档里预置的属性名”#os”，不要自定义取名，避免跟客户端上报的预置属性不一致
用户识别规则：为了让访客 ID（dt_id）与帐号 ID（acid）能够顺利绑定，其中访客 ID（dt_id）为必填

该接口是使用最频繁的接口，通过调用 track 来上报自定义事件，在上报事件之前，建议您根据梳理的文档来设置事件属性，以下是示例代码：

Python 复制代码

acId = "account_id_111"
dt_id = "dt_id_222"

properties = dict()
properties["#app_id"] = "appid_1234567890"
properties["#bundle_id"] = "com.example.app"
properties["#os"] = "android"
properties["user_level"] = 20
properties["coin"] = 1000
properties["from"] = "entry"

dt.track(acId, dt_id, "eventName", properties)

注意：

以#开头命名的事件/属性，必须按照预置事件/属性规则进行上报，否则将无法上报
以$开头的事件/属性都被视为非法字段，将无法上报

3.2 设置用户属性

DT 系统支持的用户属性设置类型总览说明如下

操作	对应事件名	处理规则
覆盖用户属性	`#user_set`	对用户表进行操作，覆盖用户的原有属性值，如果之前不存在该用户属性，则会新建该用户属性，类型与覆盖操作传入属性的类型一致
初始化用户属性	`#user_set_once`	对用户表进行操作，初始化用户属性，如果该属性已有值存在，系统忽略本次操作
累加用户属性	`#user_add`	对用户表进行操作，对数值型的用户属性做累加计算，如果该属性还未被设置，则会赋值 0 后再进行计算，可传入负值等同于相减操作
清空用户属性值	`#user_unset`	对用户表进行操作，清空用户属性的属性值，即设置成 NULL，如果被清空的属性不存在也不会新建该属性
追加列表型用户属性的元素	`#user_append`	对用户表进行操作，对列表类型的用户属性追加元素，如果被追加的列表属性不存在，系统将自动生成并进行追加
追加并去重列表类型用户属性的元素	`#user_uniq_append`	对用户表进行操作，对列表类型的用户属性值追加元素，并会进行一次全列表去重（去重保证前后原有的元素顺序不变），如果被追加的列表属性不存在，系统将自动生成并进行追加再去重
删除用户	`#user_delete`	对用户表进行操作，删除对应用户，您将无法再查询该名用户的用户属性，但该用户产生的事件仍然可以被查询到

3.2.1 userSet

user_set 是常用的功能，您可以调用它来进行用户属性的设置，调用该操作时，会覆盖原有的属性值，如果用户不存在该属性，则会创建新用户属性，类型与传入属性的类型一致

Python 复制代码

properties = { "name": "abc" }
# 设置用户属性，"name" 的值为 "abc"
dt.user_set(acid, dt_id, properties)

properties = { "name": "xyz" }
# 再次设置用户属性，此时 "name" 的值会被覆盖为 "xyz"
dt.user_set(acid, dt_id, properties)

3.2.2 userSetOnce

如果您希望用户属性只设置一次，则可以调用 user_set_once 进行设置，当该属性没有值时，则会创建该属性并赋值，但该属性已经有值时，将不会设置成功

Python 复制代码

properties = { "name": "abc" }
# 一次性设置用户属性，"name" 的值为 "abc"
dt.user_set_once(acid, dt_id, properties)

properties = { "name": "xyz" }
# 再次一次性设置用户属性，此时 "name" 的值不会被覆盖为 "xyz"
dt.user_set_once(acid, dt_id, properties)

3.2.3 userAdd

当您要对数值类型的属性进行累加操作时，可以调用 user_add 来实现，如果该属性还没有被设置，则会赋值为 0 再进行计算，可传入负值等同于相减操作

Python 复制代码

properties = {
    "total_count": 10,
    "level": 3
}
# 对用户属性进行累加，数据上传完成后，由于该属性还没有被设置，此时 "total_count" 的值为 10,"level" 的值为 3
dt.user_add(acid, dt_id, properties)

properties = { "total_count": 20 }
# 对用户属性进行累加，数据上传完成后，此时 "total_count" 的值为 30, "level" 的值为 3
dt.user_add(acid, dt_id, properties)

3.2.4 userUnset

当您要清空用户属性时，可以调用 user_unset 来实现，如果属性存在，则会删除属性，如果属性不存在，则不会做任何操作

Python 复制代码

del_set = { "name": 0, "actime_time": 0 }
# 设置后，会删除 name 和 actime_time 两个用户属性
dt.user_unset(acid, dt_id, del_set)

3.2.5 userAppend

当您要追加列表类型用户属性元素时，可以调用 user_append 来实现，如果被追加的列表属性不存在，系统将自动生成并进行追加

Python 复制代码

properties = {
    "pet": ["cat", "dog"]
}
# 设置用户属性，数据上传完成后，此时用户属性 "pet" 的值为 ["cat", "dog"]
dt.user_set(acid, dt_id, properties)

properties = {
    "pet": ["ratbbit"]
}
# 对用户列表类型属性追加元素，数据上传完成后，此时用户属性 "pet" 的值为 ["cat", "dog", "rabbit"]
dt.user_append(acid, dt_id, properties)

3.2.6 userUniqAppend

当您要追加列表类型用户属性元素并去重时，可以调用 user_uniq_append 来实现，如果被追加的列表属性不存在，系统将自动生成并进行追加和去重

Python 复制代码

properties = {
    "pet": ["cat", "dog"]
}
# 设置用户属性，数据上传完成后，此时用户属性 "pet" 的值为 ["cat", "dog"]
dt.user_set(acid, dt_id, properties)

properties = {
    "pet": ["ratbbit", "dot"]
}
# 对用户列表类型属性追加元素并去重，数据上传完成后，此时用户属性 "pet" 的值为 ["cat", "dog", "rabbit]
dt.user_uniq_append(acid, dt_id, properties)

3.2.7 userDelete

如果您要删除某个用户，可以调用 user_delete 将这名用户删除，您将无法再查询该名用户的用户属性，但该用户产生的事件仍然可以被查询到

Python 复制代码

dt.user_delete(acid, dt_id, {})

四、进阶功能

4.1 设置用户ip地址

在服务端上报数据时，如果您想设置用户的ip地址,可以通过在properties中添加#ip属性，DT会根据您上报的IP地址解析用户的地理位置信息

注：如果是用户事件，仅userSetOnce可上报#ip属性

Python 复制代码

properties["#ip"] = "127.0.0.1"

五、数据传输

可能使用的数据传输方式：

DTLogConsumer：写入文件 + 通过 FileScout 传输

如果生产的数据都是调试数据，建议您开启 debug 标志，当 debug 标志开启时，数据将不会进入生产环境

5.1 DTLogConsumer

参数（按顺序）：

log 文件的文件夹路径
最大单次写入条数
log 文件的前缀
单个文件的最大大小（单位：Byte）

Python 复制代码

consumer = DTLogConsumer("./log", 200, "dt", 10000)
# 开启 debug 标志
dt = DTAnalytics(consumer, true)
# 关闭 debug 标志
# dt = DTAnalytics(consumer, false)

5.2 提交数据

如果您期望数据立即上报到 DT 服务器，可以通过 flsuh 完成

Python 复制代码

# 立即上报数据
dt.flush()

5.3 关闭 SDK

请在退出程序前调用本接口，以避免缓存的数据丢失（重要！)

Python 复制代码

dt.close()

六、完整示例

从 SDK 初始化、上报到关闭，整个上报流程示例

Python 复制代码

import time
from dt_python_sdk import *

consumer = DTLogConsumer("log", 200, "dt_py", 10*1024*1024)
dt = DTAnalytics(consumer, True)

DTAnalytics.enable_log()    # 开启 log

dt_id = "1234567890987654321"
acid = None

dt.user_unset("xx", "xxxx", {"#app_id": "aaa", "#bundle_id": "123", "bb": 2, "cc": "ss", "#is_foreground": True})
dt.user_delete("xx", "xxxx", {"#app_id": "aaa", "#bundle_id": "123", "bb": 2, "cc": "ss"})
dt.flush()

DTAnalytics.disable_log()    # 关闭 log

properties = dict()
properties["productNames"] = ["Python", "hello"]
properties["productType"] = "Python book"
properties["producePrice"] = 80
properties["shop"] = "xx-shop"
properties["#os"] = "1.1.1.1"
properties["sex"] = 'female'
properties["#app_id"] = "appid_1234567890"
properties["#bundle_id"] = "com.example"

dt.track(dt_id, acid, "eventName", properties)

dt.flush()
dt.close()

上一个

服务端

下一个

Lua

最近修改: 2024-12-10

大纲