ae-tracking 0.1.0 → 0.2.0

package/skills/data-integration-helper/references/minigame_sdk_faq.md

@@ -0,0 +1,115 @@
+---
+title: "小游戏 SDK FAQ"
+code: "minigame_sdk_faq"
+source: "Feishu MCP"
+doc_id: "wikcnvfJGsMHmKJIsEIhx0T2lyj"
+fetched_at: "2026-04-20T17:29:39Z"
+---
+
+# 集成 SDK
+## SDK 集成方式说明
+- 目前只支持本地集成暂不支持 NPM
+
+## SDK 兼容性说明
+- 支持平台：微信小游戏、支付宝小游戏、字节跳动小游戏、百度小游戏等
+- 支持引擎：CocosCreator、Egret 白鹭引擎、Laya 引擎
+
+# 初始化 SDK
+## 推荐 SDK 初始化位置
+- 在小游戏的启动脚本中初始化，如微信小游戏的 game.js
+
+## 常见问题
+### 延迟初始化会导致自动采集事件时间延迟
+### 设备无网络 SDK 初始化不会失败
+
+# SDK 数据上报策略
+## 实时上报
+- 默认采集后立即上报，失败重试 3 次
+
+## 定时批量上报
+```javascript
+var config = {
+    appId: "APP_ID",
+    serverUrl: "SERVER_URL",
+    enableBatch: true,
+    batchConfig: {
+       size: 5,
+       interval: 5000,
+       storageLimit: 200
+     }
+};
+TDAnalytics.init(config);
+```
+
+## 数据上报失败原因
+- 需要将 serverUrl 配置为小游戏访问域名白名单
+
+# SDK 缓存机制
+## 存储内容
+- 访客 ID、设备 ID、事件数据等
+- 调用小游戏原生 setStorage 接口存储
+
+## 缓存数量限制
+- 默认最大缓存 200 条
+
+# 访客 ID（#distinct_id）
+## 默认格式
+- 随机数-当前时间戳，如 2267955649-1679397798804
+
+## 长度限制
+- 最大长度 128 位
+
+# Debug 模式
+## debugMode 三种取值
+- none：Normal 模式
+- debug：数据在 TE Debug 模式中看到，参与分析
+- debugOnly：只校验，不入库
+
+## 开启 Debug 模式看不到数据原因
+- 确认模式正确打开
+- 确认设备 ID 已在 TE 后台配置
+- 确认 appId、serverUrl 正确
+
+# 自动采集
+## ta_mg_show
+- 小游戏启动、后台回到前台时触发
+- 监听 onShow 事件
+
+## ta_mg_hide
+- 前台切换到后台时触发
+- 监听 onHide 事件
+- #duration 为 onShow 到 onHide 时差
+
+# 公共事件属性
+## 静态公共事件属性
+```javascript
+ta.setSuperProperties({ channel: "渠道名", user_name: "用户名" });
+```
+
+## 动态公共事件属性
+```javascript
+ta.setDynamicSuperProperties(function () {
+    return { gold_coin: getGold() };
+});
+```
+
+## 属性优先级
+- 用户自定义 > 动态公共 > 静态公共
+
+# 预置属性
+## 设备 ID（#device_id）
+- 默认和访客 ID 一致
+
+## IP 地址（#ip）
+- 服务端从请求头解析
+- 可手动上报 #ip
+
+# 已知问题
+## 淘宝小游戏
+- 3.4.4 版本 Batch 模式循环发送问题
+
+## OPPO 小游戏
+- module is not defined 报错
+
+## TikTok
+- #scene 属性类型不合法

package/skills/data-integration-helper/references/miniprogram_sdk_faq.md

@@ -0,0 +1,118 @@
+---
+title: "小程序 SDK FAQ"
+code: "miniprogram_sdk_faq"
+source: "Feishu MCP"
+doc_id: "wikcnFKi1tU3gBHjbIqVy4M6GGe"
+fetched_at: "2026-04-20T17:29:39Z"
+---
+
+# 集成 SDK
+## SDK 集成方式说明
+- 目前只支持本地集成暂不支持 NPM
+
+## SDK 兼容性说明
+- 支持平台：微信小程序、支付宝小程序、字节跳动小程序、百度小程序等
+
+# 初始化 SDK
+## 推荐 SDK 初始化位置
+- 在小程序启动脚本中初始化，如微信小程序的 app.js
+
+## 常见问题
+### 延迟初始化会导致初始化后首次自动采集事件无法上报
+### 设备无网络 SDK 初始化不会失败
+
+# SDK 数据上报策略
+## 实时上报
+- 默认采集后立即上报，失败重试 3 次
+
+## 定时批量上报
+```javascript
+var config = {
+    appId: "APP_ID",
+    serverUrl: "SERVER_URL",
+    enableBatch: true,
+    batchConfig: {
+       size: 20,
+       interval: 10000,
+       storageLimit: 100
+     }
+};
+TDAnalytics.init(config);
+```
+
+## 数据上报失败原因
+- 需要将 serverUrl 配置为小程序访问域名白名单
+
+# SDK 缓存机制
+## 存储内容
+- 访客 ID、设备 ID、事件数据等
+- 调用小程序原生 setStorage 接口存储
+
+## 缓存数量限制
+- 默认最大缓存 200 条
+
+# 访客 ID（#distinct_id）
+## 默认格式
+- 随机数-当前时间戳，如 2267955649-1679397798804
+
+## 长度限制
+- 最大长度 128 位
+
+# Debug 模式
+## debugMode 三种取值
+- none：Normal 模式
+- debug：数据在 TE Debug 模式中看到，参与分析
+- debugOnly：只校验，不入库
+
+# 自动采集事件
+## ta_mp_launch
+- 小程序冷启动初始化完成时触发
+- 监听 onLaunch 回调
+
+## ta_mp_view
+- 小程序启动、后台回到前台、页面切换时触发
+- 监听 Page onShow 事件
+
+## ta_mp_share
+- 点击小程序页面分享按钮后触发
+- 需要配置 onShareAppMessage
+
+## ta_mp_show
+- 小程序启动、后台回到前台时触发
+- 监听 onShow 事件
+
+## ta_mp_hide
+- 前台切换到后台时触发
+- 监听 onHide 事件
+- #duration 为 onShow 到 onHide 时差
+
+# 公共事件属性
+## 静态公共事件属性
+```javascript
+ta.setSuperProperties({ channel: "渠道名", user_name: "用户名" });
+```
+
+## 动态公共事件属性
+```javascript
+ta.setDynamicSuperProperties(function () {
+    return { gold_coin: getGold() };
+});
+```
+
+## 属性优先级
+- 用户自定义 > 动态公共 > 静态公共
+
+# 预置属性
+## 设备 ID（#device_id）
+- 默认和访客 ID 一致
+
+## IP 地址（#ip）
+- 服务端从请求头解析
+- 可手动上报 #ip
+
+# 已知问题
+## 微信小程序
+- login 方法报错 TypeError: e.trim is not a function，需要传字符串
+
+## 淘宝小程序
+- 3.3.4 Uncaught TypeError，需升级 SDK 到 3.5.1

package/skills/data-integration-helper/references/python_sdk_faq.md

@@ -0,0 +1,232 @@
+# 一、环境配置
+
+```shell
+#下载
+pip(3) install ThinkingDataSdk
+#更新
+pip(3) install --upgrade ThinkingDataSdk
+```
+
+Python SDK 最低兼容 Python 2.7.5、建议使用 2.7.9 以上版本，以下基于SDK版本2.1.3进行说明。
+
+#### demo
+
+```python
+from tgasdk.sdk import *
+
+#运行日志开关，默认False
+TGAnalytics.enableLog(True)
+#初始化
+consumer = LoggingConsumer(log_directory="/Users/blank/Downloads/pytest")
+# consumer = BatchConsumer(server_uri="上报地址", appid="项目appid")
+# consumer = AsyncBatchConsumer(server_uri="上报地址", appid="项目appid")
+# consumer = DebugConsumer(server_uri="上报地址", appid="项目appid", device_id="123456789")
+te = TGAnalytics(consumer)
+#数据上报
+account_id = "11111"  # 账户id
+distinct_id = "ABD"  # 访客id
+testProperties = {
+    "#time": datetime.datetime.now(),  # 设置事件时间，不填默认取当前时间
+    "#ip": "123.123.123.123",  # 设置ip，默认不上报
+    "#zone_offset": 8,  # 设置时区
+    "a": "123",  # 文本
+    "b": 123,  # 数值
+    "c": False,  # 布尔
+    "e": datetime.datetime.now(),  # 时间
+    "f": ["123", "123"],  # 列表
+    "g": {  # 对象
+        "g1": "123",  # 对象内只识别普通属性，如果嵌套对象/对象组对应属性最终以文本入库
+    },
+    "h": [  # 对象组
+        {
+            "h1": "123",  # 对象组内每个对象只识别普通属性，如果嵌套对象/对象组对应属性最终以文本入库
+        },
+        {
+            "h1": "321",
+        }
+    ],
+}
+
+try:
+    # 上报用户属性
+    te.user_set(account_id=account_id, distinct_id=distinct_id, properties=testProperties)
+    # 上报事件名为test的事件
+    te.track(account_id=account_id, distinct_id=distinct_id, event_name="test", properties=testProperties)
+except Exception as e:
+    raise TGAIllegalDataException(e)
+
+te.flush()
+# te.close()  # 关闭sdk前自动调用flush()
+```
+
+# 二、工作原理
+
+#### **Python SDK支持几种工作模式？分别适用于什么场景？**
+
+Python SDK 支持以下四种工作模式：
+
+1. **LoggingConsumer** 批量实时将数据写入本地文件，文件可以按每天、每小时或指定文件大小分割，需要搭配 LogBus 上报数据。优点在于数据的储存与上报解耦，数据持久化存储不容易丢失；缺点在于需要另外部署 LogBus 进行上报，LogBus会占用一部分系统资源。
+2. **BatchConsumer** 批量实时地向TA服务器传输数据，不需要搭配上报工具。优点在于使用简单无需搭配上报工具；缺点在于数据没有持久化存储，仅在内存中做缓存，如果网络不稳定缓存数据超过缓存区上限后会丢失数据。
+3. **AsyncBatchConsumer** 异步批量实时地向TA服务器传输数据，其余同BatchConsumer
+4. **DebugConsumer** 逐条发送数据，服务端会对数据进行严格校验，当某个属性不符合规范时整条数据都不会入库，当数据格式错误时会打印详细错误信息。DebugConsumer 推荐在开发调试阶段使用，禁止生产环境使用。
+
+#### **如何获取上报地址和APP_ID？**
+
+项目管理者可以在数数WEB界面，选择具体项目后，进入项目管理 - 项目配置 - 接入配置界面获取项目appid。上报地址分为公网地址和私网地址，其中公网地址适用于客户端数据上报，以及公网环境下的服务端数据接入，如在公网设置上报域名，则咨询做该配置的运维工程师；私网地址适用于内网环境下的数据接入和测试，内网上报地址为集群每个节点的8991端口。
+
+#### **LoggingConsumer的工作原理是什么？有哪些配置参数？**
+
+原理：上报操作会先写入缓存，大于buffer_size（默认5条）才会写入磁盘，不满足写入条件时想要将数据写入文件需要自行调用flush方法。可多线程执行但本身是同步方法，多线程也要等锁执行反而浪费性能。写入文件时会加文件锁所以不能多进程写入同一个文件。
+
+LoggingConsumer 常用配置参数如下表：
+
+| 参数 | 描述 | 默认值 | 参数类型 | 是否必填 | 备注 |
+|------|------|--------|----------|----------|------|
+| log_directory | 日志文件路径 | - | String | 是 | 多级目录会自动创建 |
+| rotate_mode | 日志按时间切分 | DAILY | Enum | 否 | Enum('ROTATE_MODE', ('DAILY', 'HOURLY')) |
+| file_prefix | 日志文件名前缀 | 空 | String | 否 | 多实例时填写防止多进程写入同一个文件报错 |
+| log_size | 日志按大小切分 | 0 | Integer | 否 | 单位为MB，值为0时不切分，不建议使用 |
+| buffer_size | 缓存大小 | 5 | Integer | 否 | 单位为条，超过时从内存写到日志 |
+
+#### **BatchConsumer的工作原理是什么？有哪些配置参数？**
+
+原理：上报操作会写入缓存，当上报数据数量大于batch（默认20）或因网络通信失败等问题未上报数据导致cache_buffer不为空时调用flush，不满足条件需要自行调用flush方法。如果通信失败会存入cache_buffer，长时间通信失败导致 未成功发送总条数 / batch大于max_cache_size时会丢弃最早的batch条数据。
+
+BatchConsumer 常用配置参数如下表：
+
+| 参数 | 描述 | 默认值 | 参数类型 | 是否必填 | 备注 |
+|------|------|--------|----------|----------|------|
+| server_uri | 上报地址 | - | String | 是 | |
+| appid | 项目appid | - | String | 是 | |
+| batch | 批次大小，达到阈值触发数据上报 | 20 | Integer | 否 | 最大200 |
+| timeout | http请求超时时长 | 30000 | Integer | 否 | 单位为毫秒 |
+| compress | 数据是否压缩 | True | Boolean | 否 | |
+| max_cache_size | 内存保留数据批次数 | 50 | Integer | 否 | |
+
+#### **AsyncBatchConsumer的工作原理是什么？有哪些配置参数？**
+
+原理：上报操作会写入缓存，当上报数据数量大于flush_size或每隔interval秒调用flush。flush时如果通信失败会重试3次，依旧失败会放回队列等下次上报，长时间通信失败导致超出 queue_size时会丢弃最早的flush_size条数据。
+
+AsyncBatchConsumer 常用配置参数如下表：
+
+| 参数 | 描述 | 默认值 | 参数类型 | 是否必填 | 备注 |
+|------|------|--------|----------|----------|------|
+| server_uri | 上报地址 | - | String | 是 | |
+| appid | 项目appid | - | String | 是 | |
+| interval | 数据上报间隔 | 3 | Integer | 否 | 单位为秒 |
+| flush_size | 批次大小，达到阈值触发数据上报 | 20 | Integer | 否 | |
+| queue_size | 发送线程队列大小 | 100000 | Integer | 否 | 单位为条 |
+
+#### **DebugConsumer的工作原理是什么？有哪些配置参数？**
+
+原理：每条数据都直接走http请求上报数据，不用调flush。数据格式会进行严格校验。
+
+DebugConsumer 常用配置参数如下表：
+
+| 参数 | 描述 | 默认值 | 参数类型 | 是否必填 | 备注 |
+|------|------|--------|----------|----------|------|
+| server_uri | 上报地址 | - | String | 是 | |
+| appid | 项目appid | - | String | 是 | |
+| timeout | http请求超时时长 | 30000 | Integer | 否 | 单位为ms |
+| write_data | 数据是否入库 | True | Boolean | 否 | |
+| device_id | 设备ID | 空 | String | 否 | |
+
+# 三、常见问题
+
+#### **使用 LoggingConsumer 有哪些注意事项？**
+
+- **搭配Logbus上报**
+  - LoggingConsumer + LogBus为数数标准的数据上报方案，LoggingConsumer使得数据持久化，数据得到不丢失的保障；LogBus为数据传输作保证，同时将数据持久化和上报解耦。
+- **文件写权限**
+  - 写入日志目录需要有写入和读取的权限，通常Windows环境会有写入权限问题。
+- **磁盘空间**
+  - 磁盘空间保证充裕，并可以合理在LogBus上配置删除策略。
+- **磁盘性能NFS情况**
+- **UUID**
+  - 建议添加UUID，防止网络抖动及极端情况造成数据重复，但会稍微消耗效率，也可在LogBus侧打开。
+- **多进程写不同文件**
+  - 支持多进程写不同文件，但要保证不同进程的处理逻辑没有依赖关系（如不同服务器的用户行为写到不同日志）
+- **容器环境**
+  - 将数据写入路径映射到外部磁盘，防止容器关闭数据文件丢失
+
+#### **LoggingConsumer 是否支持多线程？是否支持多进程？**
+
+支持多线程，不支持多进程写同一个文件。
+
+#### **LoggingConsumer 性能指标如何？**
+
+4C16G下2w/s，不同平台不同Python版本有上下浮动
+
+#### **LoggingConsumer 是否存在丢数风险？如何避免？**
+
+如果磁盘写满或者服务器宕机可能导致数据丢失，建议：
+
+1. 定期检查写入日志路径磁盘剩余容量
+2. 降低buffer_size参数值，增加内存刷写频率，但会导致频繁IO，需结合具体场景综合考虑
+
+#### **BatchConsumer 为什么会存在丢数风险？如何避免？**
+
+`BatchConsumer`在内存中维护了两个队列，一个batch 大小的队列负责存放单批次数据，一个batch*max_cache_size大小的队列负责存放因为网络原因发送失败的批次数据队列。因为`BatchConsumer`基于内存存储，所以当发生内存溢出或者服务器宕机时，内存中未发送的数据会全部丢失，建议：
+
+1. 使用LoggingConsumer + LogBus搭配进行数据上报
+2. 提高max_cache_size参数值大小，在网络发生异常导致数据发送失败时，可以在内存中存储更多的数据，但是会导致服务器内存使用值增加，需结合具体场景综合考虑
+3. batch参数不宜设置过大，可能会导致单次发送数据时间增加，会增加发生网络错误的概率
+
+#### **BatchConsumer 性能指标如何？适合在什么场景下使用？**
+
+内网环境下适合在并发数据量较低、保证网络的环境下使用（比如与TE集群内网打通）。
+
+#### **DebugConsumer 为什么在生产环境禁用？**
+
+DebugConsumer上传数据时，每条数据都会进行post发送，生产环境使用会频繁创建连接影响效率。
+
+#### **什么时候需要调用 `close()` 方法？**
+
+程序需要正常结束时调用，close()方法会将内存中的数据进行写入文件或发送。
+
+#### **在程序中调用了 `track()` 或者 `user_set()` 方法， 为什么在 TE 后台没有看到数据？**
+
+请依次检查以下情况：
+
+- 检查上报地址和appid
+- 数据太少，未触发上报
+- 错误数据
+- 数据时间
+- 历史通道
+- 埋点方案
+
+#### **上报数据中为什么没有 "#ip"？**
+
+服务端的#ip需要单独上报，层级与#distinct_id、#event_name、#time、properties等同级。
+
+# 四、预置属性、特殊类型上报
+
+#### **Python SDK 如何上报对象和对象组类型？**
+
+Python SDK 1.7.0及以上版本支持上报对象和对象组类型，代码示例请参考服务端SDK复杂类型上报。
+
+#### **公共属性**
+
+服务端的公共属性无法精确到用户级，在多线程情况下报了用户级属性数据可能会导致用户数据对不上。仅建议在公共属性内放区服id等不会产生大变化的字段，其余均放入普通属性。
+
+#### **时区**
+
+默认时区以数数服务器为准，如果要实现时区偏移需上报#zone_offset字段。假设填0且事件时间为2023-04-17 01:02:03，偏移到东八区会以事件时间2023-04-17 09:02:03进行分析。
+
+# 五、异常报错
+
+1. **Pip 安装 Python SDK 失败，报错："ERROR: Could not find a version that satisfies the requirement ThinkingDataSdk (from version: none) ERROR: No matching distribution found for ThinkingDataSdk"**
+
+这是pip安装的常见问题，通常可以通过升级 pip 版本或更改 pip 源解决。
+
+2. **调用 user_set() 报错："error = year=1899 is before 1900; the datetime strftime() methods require year >= 1900"**
+
+Python SDK 里用 strftime() 函数做时间转换，不支持1900年之前的时间。
+
+3. **调用 track() 报错："gevent.Hub.LoopExit: This operation would block forever"**
+
+这个是客户使用了Python三方库gevent的报错，网上有很多相关资料和方案，可以协助客户分析，不属于Python SDK的异常。
+
+4. **BatchConsumer上报报错："Data transmission failed due to ConnectionError(ProtocolError('Connection aborted.', BadStatusLine('No status line received - the server has closed the connection',)),)"**
+
+这个报错来自 Python SDK 用于网络请求的内部类 _HttpServices 的 send() 函数，通常由于网络抖动导致。BatchConsumer 的 __cache_buffer 缓存区不会移除上报失败的数据，会在下一次继续上报，所以网络抖动不会导致数据丢失。

package/skills/data-integration-helper/references/restful_api_notes.md

@@ -0,0 +1,72 @@
+# Restful API 使用注意事项
+
+数数提供了 Restful API 支持以 HTTP Post 方式向 TE 集群上报数据，详细介绍见官方使用手册 [Restful API 使用指南](https://docs-v2.thinkingdata.cn/?code=restful_api&anchorId=)。本文介绍 Restful API 的使用注意事项。
+
+#### 使用场景
+
+由于 Restful API 无法像 SDK 或 Logbus 一样具备失败重试等容错能力，因此**建议应用于数据上报调试、数据格式验证等测试场景，或者少量数据一次性上报、低频上报场景。**
+
+上述场景以外，建议使用 Logbus 等更具保障的集成工具，详见 [LogBus2 使用指南](https://docs-v2.thinkingdata.cn/?version=latest&code=logbus2_installation&lan=zh-CN&anchorId=)。
+
+#### 请求方式
+
+Restful API 提供了 `form-data` 和 `raw` 两种请求方式，两种方式主要功能一致，但请求接口、传参方式等存在差异。
+
+| 请求方式 | 接口 | 支持数据压缩 | 支持Debug模式 |
+|----------|------|--------------|---------------|
+| form-data | http://YOUR_SERVER_URL/sync_data | 否 | 是 |
+| raw | http://YOUR_SERVER_URL/sync_json | 是 | 是 |
+
+#### 异常处理
+
+**如果将 Restful API 用于生产场景，请务必处理网络请求异常、上报失败等异常情况，采用重试等兜底策略，避免造成数据丢失。**
+
+根据请求返回的 code 可以判断请求是否成功， `"code": 0` 代表成功：
+
+```json
+{
+    "code": 0
+}
+```
+
+`"code": -1` 或其它非 0 值代表失败，可以根据 `msg` 分析失败原因：
+
+```json
+{
+    "code": -1,
+    "msg": "数据格式错误，非json格式"
+}
+```
+
+#### QPS
+
+Restful API 对应的 `sync_data` 和 `sync_json` 接口本身对并发并无限制，但集群连接数存在上限。若并发过高致使集群连接达到上限，将导致请求失败。
+
+请求中的数据量和数据长度会影响集群处理请求的时长和资源：
+
+- 单条请求中的数据量越大，请求处理耗时越长。如果请求中数据量过大，容易引发请求超时、集群连接打满等异常情况。
+- 相同数据量前提下，数据平均长度越大，请求体越大，请求处理消耗内存资源越大。如果请求中数据量和数据平均长度都比较大，可能引发集群收数组件 OOM。
+
+**因此，单条请求中的数据量需要控制在合理范围，建议不超过 1000 条。如果平均数据长度较大，需要减小请求中的数据量。**
+
+#### debug 参数
+
+debug 参数用于对数据格式、内容进行完整校验，默认值为 0，集群处理请求时只会对数据 JSON 格式、关键字段做简单校验。如果传入 `debug = 1`，集群会对数据内容进行完整校验并返回结果。
+
+由于开启 debug 模式后数据校验产生更大资源开销，集群的数据接收和处理性能将受到影响。
+
+**因此，debug 模式仅用于测试调试，请勿在生产环境中使用。**
+
+Restful API 的两种请求方式都支持传入 debug 参数，传参方式详见 [Restful API 使用指南](https://docs-v2.thinkingdata.cn/?code=restful_api&anchorId=)。
+
+#### client 参数
+
+client 参数用于标识是否将数据作为客户端上报数据处理。如果传入 `client = 1`，集群会将数据作为客户端上报数据处理，集群会记录请求中的 IP 信息并存入 `#ip` 属性，并将 IP 解析结果写入 `#country`，`#country_code`，`#province`，`#city` 属性。
+
+Restful API 的两种请求方式都支持传入 client 参数，传参方式详见 [Restful API 使用指南](https://docs-v2.thinkingdata.cn/?code=restful_api&anchorId=)。
+
+#### 数据压缩
+
+Raw 请求方式支持数据压缩，在 Header 中添加 `compress` 参数可以开启数据压缩并指定压缩格式，例如 `compress=gzip` 。开启数据压缩能够减少传输流量，但会对集群的数据接收与处理性能产生一定影响。
+
+由于不同编程语言的压缩解压实现可能存在兼容性问题，建议优先选择 gzip 格式，并在正式投入使用前进行测试调试。