ae-data-integration-helper
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
Chineseae-data-integration-helper
ae-data-integration-helper
Conversation language: This skill document is in English, but all output to the user MUST be in the user's input language. Chinese input → Chinese reply; English input → English reply; Japanese input → Japanese reply. If uncertain, default to English. This applies to all output: headings, step descriptions, code comments, examples, etc. ⚠️ CRITICAL: Many reference documents (FAQ, wiki) are in Chinese. When reading Chinese source material to answer an English/Japanese user, you MUST translate the content to the user's language. The source document's language is NOT the user's language. Never output Chinese to an English user just because the wiki page is in Chinese. Use the Terminology Glossary above to map terms accurately. Do NOT copy Chinese text verbatim from this document into English/Japanese replies.
对话语言:本技能文档为英文,但所有输出必须使用用户输入的语言。 中文输入→中文回复;英文输入→英文回复;日文输入→日文回复。 若不确定,默认使用英文。 此要求适用于所有输出:标题、步骤说明、代码注释、示例等。 ⚠️ 重要提示:许多参考文档(FAQ、wiki)为中文。当阅读中文源文档为英文/日文用户解答时,必须将内容翻译为用户使用的语言。源文档的语言不等于用户的语言。绝不能因为wiki页面是中文就向英文用户输出中文内容。请使用上方术语对照表准确映射术语。 请勿直接将本文档中的中文文本复制粘贴到英文/日文回复中。
Terminology Glossary
术语对照表
| 中文 | English | Notes |
|---|---|---|
| 埋点 / 数据上报 | Tracking / Data Ingestion | Sending event data to TE |
| 用户识别规则 | User Identification Rule | distinct_id / account_id mapping |
| 访客 ID | Visitor ID / Guest ID | Anonymous user before login |
| 登录 ID | Login ID / Account ID | Identified user after login |
| 预置属性 | Preset Property | |
| 系统字段 | System Field | TE built-in fields prefixed with |
| 事件格式 | Event Format | Event name + properties structure |
| 属性类型 | Property Type | String / Number / Boolean / Date / Array |
| 数据校验 | Data Validation | Verify event format & property types |
| 公共事件属性 | Super Property | Properties attached to all events. ⚠️ The correct Chinese AE term is "公共事件属性" or "公共属性". Never translate "Super Property" as "超级属性" — that is NOT a valid AE term. |
| 可更新事件 | Updatable Event | Event whose properties can be updated after creation |
| 首次事件校验 | First Event Check | Validate an event's first occurrence |
| 自动采集 | Auto-track | Auto-collected events (app install, start, page view, etc.) |
| 实时调试 | Real-time Debug / Debug Mode | Device binding + live data validation |
| 合规 / 隐私 | Compliance / Privacy | GDPR, privacy policy, SDK data collection rules |
| 数据导入 | Data Import | LogBus2 / RESTful API / DataX |
| 缓存上报 | Batch Upload / Buffered Upload | Cache events locally, then upload in batches |
| 重试策略 | Retry Strategy | Re-upload failed data automatically |
| 数据加密 | Data Encryption | Encrypt event data before upload |
| 时间校准 | Time Calibration | Sync device time with server time |
| 多端上报 | Multi-platform Tracking | Report events from multiple clients/services |
| 用户割裂 | User Fragmentation | Same user split into multiple TE user profiles |
| 上报模式 | Upload Mode | Normal / Debug / Debug_Only |
| LoggerConsumer | LoggerConsumer | Server SDK consumer that writes events to local log files |
| BatchConsumer | BatchConsumer | Server SDK consumer that uploads events in batches |
| DebugConsumer | DebugConsumer | Server SDK consumer for debug mode (not for production) |
| 中文 | English | 说明 |
|---|---|---|
| 埋点 / 数据上报 | Tracking / Data Ingestion | 向TE发送事件数据 |
| 用户识别规则 | User Identification Rule | distinct_id / account_id 映射规则 |
| 访客 ID | Visitor ID / Guest ID | 登录前的匿名用户ID |
| 登录 ID | Login ID / Account ID | 登录后的已识别用户ID |
| 预置属性 | Preset Property | |
| 系统字段 | System Field | TE内置的以 |
| 事件格式 | Event Format | 事件名称+属性结构 |
| 属性类型 | Property Type | String / Number / Boolean / Date / Array |
| 数据校验 | Data Validation | 验证事件格式与属性类型 |
| 公共事件属性 | Super Property | 附加到所有事件的属性。⚠️ 在AE中的正确中文术语为「公共事件属性」或「公共属性」。绝不能将「Super Property」翻译为「超级属性」——这不是有效的AE术语。 |
| 可更新事件 | Updatable Event | 创建后可更新属性的事件 |
| 首次事件校验 | First Event Check | 验证事件的首次触发情况 |
| 自动采集 | Auto-track | 自动采集的事件(如应用安装、启动、页面浏览等) |
| 实时调试 | Real-time Debug / Debug Mode | 设备绑定+实时数据验证 |
| 合规 / 隐私 | Compliance / Privacy | GDPR、隐私政策、SDK数据采集规则 |
| 数据导入 | Data Import | LogBus2 / RESTful API / DataX |
| 缓存上报 | Batch Upload / Buffered Upload | 在本地缓存事件,然后批量上传 |
| 重试策略 | Retry Strategy | 自动重新上传失败的数据 |
| 数据加密 | Data Encryption | 上传前加密事件数据 |
| 时间校准 | Time Calibration | 将设备时间与服务器时间同步 |
| 多端上报 | Multi-platform Tracking | 从多个客户端/服务上报事件 |
| 用户割裂 | User Fragmentation | 同一用户被拆分为多个TE用户画像 |
| 上报模式 | Upload Mode | Normal / Debug / Debug_Only |
| LoggerConsumer | LoggerConsumer | 将事件写入本地日志文件的Server SDK消费者 |
| BatchConsumer | BatchConsumer | 批量上传事件的Server SDK消费者 |
| DebugConsumer | DebugConsumer | 用于调试模式的Server SDK消费者(不用于生产环境) |
When to Trigger
触发场景
Trigger when a user asks about:
- Pre-ingestion Preparation:
- User identification rules (distinct_id / account_id / visitor ID / login ID)
- Data rules (event format / property types / validation)
- Preset properties & system fields (,
#device_id, etc.)#time
- Client SDK Integration: Android / iOS / JavaScript / Unity / OpenHarmony / Mini-program, etc.
- Server SDK Integration: Java / Python / Go / Node.js / PHP / C#, etc.
- Data Import: LogBus2 / RESTful API / DataX
- Advanced Data Types: Updatable events / first event check
- Auto-tracking: Page view / button click / app start, etc.
- Real-time Debugging: Debug mode / device binding / data validation
- Compliance / Privacy: GDPR / privacy policy / SDK data collection rules
- API Usage: /
init/track/ LoggerConsumer, etc.user_set - Configuration: Debug mode / data validation / retry strategy
- Troubleshooting: Upload failures / missing data / format errors
Do NOT trigger: Inline Q&A within or sessions (those skills have their own workflows).
ae-generate-tracking-planae-generate-tracking-code当用户询问以下内容时触发:
- 数据摄入前准备:
- 用户识别规则(distinct_id / account_id / 访客ID / 登录ID)
- 数据规则(事件格式 / 属性类型 / 校验)
- 预置属性与系统字段(、
#device_id等)#time
- 客户端SDK集成:Android / iOS / JavaScript / Unity / OpenHarmony / 小程序等
- 服务端SDK集成:Java / Python / Go / Node.js / PHP / C#等
- 数据导入:LogBus2 / RESTful API / DataX
- 高级数据类型:可更新事件 / 首次事件校验
- 自动采集:页面浏览 / 按钮点击 / 应用启动等
- 实时调试:调试模式 / 设备绑定 / 数据验证
- 合规与隐私:GDPR / 隐私政策 / SDK数据采集规则
- API使用:/
init/track/ LoggerConsumer等user_set - 配置:调试模式 / 数据校验 / 重试策略
- 问题排查:上传失败 / 数据丢失 / 格式错误
请勿触发:在或会话中的嵌入式问答(这些技能有各自的工作流程)。
ae-generate-tracking-planae-generate-tracking-codeWorkflow
工作流程
Step 1: Parse the Question
步骤1:解析问题
Extract from the user's query:
- Topic category:
- Pre-ingestion Prep: User identification / data rules / preset properties
- Client SDK: Android / iOS / JavaScript / Unity / OpenHarmony / Mini-program, etc.
- Server SDK: Java / Python / Go / Node.js / PHP / C#, etc.
- Data Import: LogBus2 / RESTful API / DataX
- Advanced Data Types: Updatable events / first event check
- Auto-tracking: Page view / button click / app start
- Real-time Debug: Debug mode / device binding / data validation
- Compliance: GDPR / privacy policy / SDK data collection rules
- Query type: Integration method / API usage / configuration / deployment / error / logging
从用户查询中提取:
- 主题类别:
- 数据摄入前准备:用户识别 / 数据规则 / 预置属性
- 客户端SDK:Android / iOS / JavaScript / Unity / OpenHarmony / 小程序等
- 服务端SDK:Java / Python / Go / Node.js / PHP / C#等
- 数据导入:LogBus2 / RESTful API / DataX
- 高级数据类型:可更新事件 / 首次事件校验
- 自动采集:页面浏览 / 按钮点击 / 应用启动
- 实时调试:调试模式 / 设备绑定 / 数据验证
- 合规:GDPR / 隐私政策 / SDK数据采集规则
- 查询类型:集成方法 / API使用 / 配置 / 部署 / 报错 / 日志
Step 1.5: Information Gathering
步骤1.5:收集信息
⚠️ Key principle: When the question is vague, gather information FIRST before answering. Do NOT guess or ramble.
If the user's question involves any of the following scenarios, collect critical information before proceeding:
| Scenario | Must Collect |
|---|---|
| "Data not showing up" / "Can't see data" / "Upload successful but nothing in the dashboard" | Upload method (SDK / LogBus / HTTP), data type (event / user property), specific symptom (no data at all / partial data) |
| "Error" / "Failure" type questions | Full error message, reproduction steps |
| "Can't connect" / "Unable to upload" | Platform/language used, error symptoms |
| "How to implement X" | Platform/language used, what X specifically means |
Ask first, then answer. Examples:
- "Data logs show success but the dashboard shows nothing — are you using SDK, LogBus, or HTTP upload?"
- "Can't connect — which language/platform are you using? Can you share the error message?"
⚠️ 核心原则:当问题模糊时,先收集信息再作答。请勿猜测或随意发挥。
如果用户的问题涉及以下场景,必须先收集关键信息再继续:
| 场景 | 必须收集的信息 |
|---|---|
| "数据未显示" / "看不到数据" / "上传成功但仪表盘无数据" | 上传方式(SDK / LogBus / HTTP)、数据类型(事件 / 用户属性)、具体症状(完全无数据 / 部分数据缺失) |
| "错误" / "失败"类问题 | 完整错误信息、复现步骤 |
| "无法连接" / "无法上传" | 使用的平台/语言、错误症状 |
| "如何实现X" | 使用的平台/语言、X的具体含义 |
先询问,再作答。示例:
- "日志显示上传成功但仪表盘无数据——您使用的是SDK、LogBus还是HTTP上传?"
- "无法连接——您使用的是哪种语言/平台?能否分享错误信息?"
Step 2: Find Relevant Documentation
步骤2:查找相关文档
Prefer FAQ documents first (for quick lookup of specific issues):
- Read corresponding FAQ (e.g.,
skills/ae-data-integration-helper/references/,android_sdk_faq.md, etc.)logbus2_guide.md - FAQ documents cover specific troubleshooting, code examples, parameter tables, and best practices
Check wiki when FAQ has no answer (for framework-level and authoritative content):
- Read to locate document paths
~/.ae-cli/wiki/te-docs/index.md - Prefer overview documents under
~/.ae-cli/wiki/te-docs/synthesis/ - For detailed API references, check the corresponding main document under
~/.ae-cli/wiki/te-docs/raw/
Commonly used FAQ documents:
- — Android SDK integration & FAQ
references/android_sdk_faq.md - — iOS SDK integration & FAQ
references/ios_sdk_faq.md - — Java SDK integration & FAQ
references/java_sdk_faq.md - — LogBus2 complete configuration guide
references/logbus2_guide.md - — Client/server SDK usage notes
references/sdk_usage_notes.md - — RESTful API usage notes
references/restful_api_notes.md - Full list: see
references/index.md
优先使用FAQ文档(用于快速查找特定问题):
- 阅读下对应的FAQ(如
skills/ae-data-integration-helper/references/、android_sdk_faq.md等)logbus2_guide.md - FAQ文档涵盖特定问题排查、代码示例、参数表及最佳实践
当FAQ无答案时查看wiki(用于框架级权威内容):
- 阅读定位文档路径
~/.ae-cli/wiki/te-docs/index.md - 优先查看下的概述文档
~/.ae-cli/wiki/te-docs/synthesis/ - 如需详细API参考,查看下对应的主文档
~/.ae-cli/wiki/te-docs/raw/
常用FAQ文档:
- — Android SDK集成与FAQ
references/android_sdk_faq.md - — iOS SDK集成与FAQ
references/ios_sdk_faq.md - — Java SDK集成与FAQ
references/java_sdk_faq.md - — LogBus2完整配置指南
references/logbus2_guide.md - — 客户端/服务端SDK使用注意事项
references/sdk_usage_notes.md - — RESTful API使用注意事项
references/restful_api_notes.md - 完整列表:查看
references/index.md
Step 3: Read & Summarize
步骤3:阅读与总结
After reading relevant documentation, output in the following format:
undefined阅读相关文档后,按以下格式输出:
undefined<Topic> (<Platform>)
<主题>(<平台>)
Summary
概述
<1-2 sentence description>
<1-2句话描述>
Integration / Usage Steps
集成/使用步骤
- <Step 1>
- <Step 2> ...
- <步骤1>
- <步骤2> ...
Code Example
代码示例
<code><code>Notes / Caveats
注意事项
- <Note 1>
- <Note 2>
- <注意事项1>
- <注意事项2>
Source Document
源文档
<Prefer wiki document sourceUrl. Language rules:
- User interacts in Chinese → provide Chinese doc (lan=zh-CN)
- User interacts in other languages → provide English doc (lan=en-US)
- Chinese-only SDKs (Mini-program / OpenHarmony / Cocos2d-Lua / LayaAir / Egret) → Chinese only Example: https://docs-v2.thinkingdata.cn/?version=v6.0&lan=en-US&code=xxx> (If no sourceUrl, provide local .md file path)
**⚠️ Terminology Rules**:
- **Only output what is in the documentation**. Do NOT speculate, imagine, or fill in defaults.
- **Never translate "Super Property" as "超级属性"** — the correct AE Chinese term is "公共事件属性" or "公共属性". This applies to all user-facing output: headings, step descriptions, code comments, examples, etc.
- For uncertain information (e.g., data delay times, specific limit values), **do NOT fabricate**.
- If the document has no direct answer but allows inference: mark under "Source Document" as "Synthesized inference; recommend verification".
- If the documentation truly does not cover the question, fall back to Step 4. Do NOT force an answer.<优先提供wiki文档的sourceUrl。语言规则:
- 用户使用中文交互→提供中文文档(lan=zh-CN)
- 用户使用其他语言交互→提供英文文档(lan=en-US)
- 仅支持中文的SDK(小程序 / OpenHarmony / Cocos2d-Lua / LayaAir / Egret)→仅提供中文文档 示例:https://docs-v2.thinkingdata.cn/?version=v6.0&lan=en-US&code=xxx> (若无sourceUrl,提供本地.md文件路径)
**⚠️ 术语规则**:
- **仅输出文档中存在的内容**。请勿推测、臆想或自行补充默认值。
- **绝不能将「Super Property」翻译为「超级属性」**——在AE中的正确中文术语为「公共事件属性」或「公共属性」。此要求适用于所有面向用户的输出:标题、步骤说明、代码注释、示例等。
- 对于不确定的信息(如数据延迟时间、具体限制值),**请勿编造**。
- 若文档无直接答案但可推导:在「源文档」下标注「综合推导内容;建议验证」。
- 若文档确实未覆盖问题,进入步骤4。请勿强行作答。Step 4: Fallback
步骤4: fallback方案
If neither FAQ nor wiki has relevant content:
- Provide the official online documentation link: https://docs-v2.thinkingdata.cn
- Optionally suggest running the skill to generate a new synthesis document.
te-wiki-synthesize
若FAQ和wiki均无相关内容:
- 提供官方在线文档链接:https://docs-v2.thinkingdata.cn
- 可建议运行技能生成新的综合文档。
te-wiki-synthesize
Example Conversations
对话示例
User: What is distinct_id and how do I use it?
Agent:
- Read to find user identification rule document paths
references/index.md - If or wiki has relevant sections, read those first
sdk_usage_notes.md - Output in the Step 3 format
User: How do I configure LogBus2?
Agent:
- Read
references/logbus2_guide.md - Output in the Step 3 format
User: Java SDK is losing data — what should I do?
Agent:
- Read , section on "LoggerConsumer data loss risks"
references/java_sdk_faq.md - Output in the Step 3 format
User: How do I integrate the Android SDK?
Agent:
- Read or
references/android_sdk_faq.mdto find Android SDK path~/.ae-cli/wiki/te-docs/index.md - Read the relevant sections
- Output in the Step 3 format
undefined用户: distinct_id是什么?如何使用?
Agent:
- 阅读查找用户识别规则文档路径
references/index.md - 若或wiki有相关章节,优先阅读
sdk_usage_notes.md - 按步骤3的格式输出
用户: 如何配置LogBus2?
Agent:
- 阅读
references/logbus2_guide.md - 按步骤3的格式输出
用户: Java SDK丢失数据——该怎么办?
Agent:
- 阅读中「LoggerConsumer数据丢失风险」章节
references/java_sdk_faq.md - 按步骤3的格式输出
用户: 如何集成Android SDK?
Agent:
- 阅读或
references/android_sdk_faq.md查找Android SDK文档路径~/.ae-cli/wiki/te-docs/index.md - 阅读相关章节
- 按步骤3的格式输出
undefinedAndroid SDK Integration
Android SDK集成
Summary
概述
Android SDK supports both Gradle and manual AAR integration. Gradle is recommended.
Android SDK支持Gradle和手动AAR两种集成方式,推荐使用Gradle。
Integration Steps (Gradle)
集成步骤(Gradle)
- Add mavenCentral to project-level :
build.gradlegroovyrepositories { mavenCentral() } - Add dependency to module-level :
build.gradlegroovydependencies { implementation 'cn.thinkingdata.android:ThinkingAnalyticsSDK:3.3.6' } - Initialize SDK:
java
TDAnalytics.init(this, SERVER_URL, APPID);
- 在项目级中添加mavenCentral:
build.gradlegroovyrepositories { mavenCentral() } - 在模块级中添加依赖:
build.gradlegroovydependencies { implementation 'cn.thinkingdata.android:ThinkingAnalyticsSDK:3.3.6' } - 初始化SDK:
java
TDAnalytics.init(this, SERVER_URL, APPID);
Source Document
源文档
~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/client-sdk/android.md
**User**: How do I enable real-time debugging for Android SDK?
**Agent**:
1. Read `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/client-sdk/android/android-advanced/debugging-and-logging.md`
2. Output in the Step 3 format~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/client-sdk/android.md
**用户**: 如何为Android SDK开启实时调试?
**Agent**:
1. 阅读`~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/client-sdk/android/android-advanced/debugging-and-logging.md`
2. 按步骤3的格式输出Internal Reference
内部参考
FAQ Documents (check first):
- — All FAQ document index
references/index.md - — Android SDK FAQ
references/android_sdk_faq.md - — LogBus2 complete guide
references/logbus2_guide.md - — SDK usage notes
references/sdk_usage_notes.md
Wiki Documents (check when FAQ has no answer):
- — All wiki document index
~/.ae-cli/wiki/te-docs/index.md - — Wiki layout description
~/.ae-cli/wiki/te-docs/schema.md - — User Identification Rules
~/.ae-cli/wiki/te-docs/raw/preparations-before-data-ingestion/user-identification-rules.md - — Data Rules
~/.ae-cli/wiki/te-docs/raw/preparations-before-data-ingestion/data-rules.md - — Preset Properties
~/.ae-cli/wiki/te-docs/raw/preparations-before-data-ingestion/preset-properties-and-system-fields.md - — Updatable Event
~/.ae-cli/wiki/te-docs/raw/advanced-data-type/updated-event.md - — First Event Check
~/.ae-cli/wiki/te-docs/raw/advanced-data-type/first-event-check.md - — LogBus2
~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/data-import-tools/logbus2-user-guide.md
FAQ文档(优先检查):
- — 所有FAQ文档索引
references/index.md - — Android SDK FAQ
references/android_sdk_faq.md - — LogBus2完整指南
references/logbus2_guide.md - — SDK使用注意事项
references/sdk_usage_notes.md
Wiki文档(FAQ无答案时检查):
- — 所有wiki文档索引
~/.ae-cli/wiki/te-docs/index.md - — Wiki布局说明
~/.ae-cli/wiki/te-docs/schema.md - — 用户识别规则
~/.ae-cli/wiki/te-docs/raw/preparations-before-data-ingestion/user-identification-rules.md - — 数据规则
~/.ae-cli/wiki/te-docs/raw/preparations-before-data-ingestion/data-rules.md - — 预置属性
~/.ae-cli/wiki/te-docs/raw/preparations-before-data-ingestion/preset-properties-and-system-fields.md - — 可更新事件
~/.ae-cli/wiki/te-docs/raw/advanced-data-type/updated-event.md - — 首次事件校验
~/.ae-cli/wiki/te-docs/raw/advanced-data-type/first-event-check.md - — LogBus2
~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/data-import-tools/logbus2-user-guide.md