ae-data-integration-helper

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

ae-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

术语对照表

中文EnglishNotes
埋点 / 数据上报Tracking / Data IngestionSending event data to TE
用户识别规则User Identification Ruledistinct_id / account_id mapping
访客 IDVisitor ID / Guest IDAnonymous user before login
登录 IDLogin ID / Account IDIdentified user after login
预置属性Preset Property
#device_id
,
#time
,
#ip
, etc.
系统字段System FieldTE built-in fields prefixed with
#
事件格式Event FormatEvent name + properties structure
属性类型Property TypeString / Number / Boolean / Date / Array
数据校验Data ValidationVerify event format & property types
公共事件属性Super PropertyProperties attached to all events. ⚠️ The correct Chinese AE term is "公共事件属性" or "公共属性". Never translate "Super Property" as "超级属性" — that is NOT a valid AE term.
可更新事件Updatable EventEvent whose properties can be updated after creation
首次事件校验First Event CheckValidate an event's first occurrence
自动采集Auto-trackAuto-collected events (app install, start, page view, etc.)
实时调试Real-time Debug / Debug ModeDevice binding + live data validation
合规 / 隐私Compliance / PrivacyGDPR, privacy policy, SDK data collection rules
数据导入Data ImportLogBus2 / RESTful API / DataX
缓存上报Batch Upload / Buffered UploadCache events locally, then upload in batches
重试策略Retry StrategyRe-upload failed data automatically
数据加密Data EncryptionEncrypt event data before upload
时间校准Time CalibrationSync device time with server time
多端上报Multi-platform TrackingReport events from multiple clients/services
用户割裂User FragmentationSame user split into multiple TE user profiles
上报模式Upload ModeNormal / Debug / Debug_Only
LoggerConsumerLoggerConsumerServer SDK consumer that writes events to local log files
BatchConsumerBatchConsumerServer SDK consumer that uploads events in batches
DebugConsumerDebugConsumerServer SDK consumer for debug mode (not for production)
中文English说明
埋点 / 数据上报Tracking / Data Ingestion向TE发送事件数据
用户识别规则User Identification Ruledistinct_id / account_id 映射规则
访客 IDVisitor ID / Guest ID登录前的匿名用户ID
登录 IDLogin ID / Account ID登录后的已识别用户ID
预置属性Preset Property
#device_id
#time
#ip
系统字段System FieldTE内置的以
#
开头的字段
事件格式Event Format事件名称+属性结构
属性类型Property TypeString / 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 / PrivacyGDPR、隐私政策、SDK数据采集规则
数据导入Data ImportLogBus2 / RESTful API / DataX
缓存上报Batch Upload / Buffered Upload在本地缓存事件,然后批量上传
重试策略Retry Strategy自动重新上传失败的数据
数据加密Data Encryption上传前加密事件数据
时间校准Time Calibration将设备时间与服务器时间同步
多端上报Multi-platform Tracking从多个客户端/服务上报事件
用户割裂User Fragmentation同一用户被拆分为多个TE用户画像
上报模式Upload ModeNormal / Debug / Debug_Only
LoggerConsumerLoggerConsumer将事件写入本地日志文件的Server SDK消费者
BatchConsumerBatchConsumer批量上传事件的Server SDK消费者
DebugConsumerDebugConsumer用于调试模式的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
      ,
      #time
      , etc.)
  • 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
    /
    user_set
    / LoggerConsumer, etc.
  • Configuration: Debug mode / data validation / retry strategy
  • Troubleshooting: Upload failures / missing data / format errors
Do NOT trigger: Inline Q&A within
ae-generate-tracking-plan
or
ae-generate-tracking-code
sessions (those skills have their own workflows).
当用户询问以下内容时触发:
  • 数据摄入前准备:
    • 用户识别规则(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
    /
    user_set
    / LoggerConsumer等
  • 配置:调试模式 / 数据校验 / 重试策略
  • 问题排查:上传失败 / 数据丢失 / 格式错误
请勿触发:在
ae-generate-tracking-plan
ae-generate-tracking-code
会话中的嵌入式问答(这些技能有各自的工作流程)。

Workflow

工作流程

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:
ScenarioMust 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 questionsFull 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):
  1. Read
    skills/ae-data-integration-helper/references/
    corresponding FAQ (e.g.,
    android_sdk_faq.md
    ,
    logbus2_guide.md
    , etc.)
  2. 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):
  1. Read
    ~/.ae-cli/wiki/te-docs/index.md
    to locate document paths
  2. Prefer overview documents under
    ~/.ae-cli/wiki/te-docs/synthesis/
  3. For detailed API references, check the corresponding main document under
    ~/.ae-cli/wiki/te-docs/raw/
Commonly used FAQ documents:
  • references/android_sdk_faq.md
    — Android SDK integration & FAQ
  • references/ios_sdk_faq.md
    — iOS SDK integration & FAQ
  • references/java_sdk_faq.md
    — Java SDK integration & FAQ
  • references/logbus2_guide.md
    — LogBus2 complete configuration guide
  • references/sdk_usage_notes.md
    — Client/server SDK usage notes
  • references/restful_api_notes.md
    — RESTful API usage notes
  • Full list: see
    references/index.md
优先使用FAQ文档(用于快速查找特定问题):
  1. 阅读
    skills/ae-data-integration-helper/references/
    下对应的FAQ(如
    android_sdk_faq.md
    logbus2_guide.md
    等)
  2. FAQ文档涵盖特定问题排查、代码示例、参数表及最佳实践
当FAQ无答案时查看wiki(用于框架级权威内容):
  1. 阅读
    ~/.ae-cli/wiki/te-docs/index.md
    定位文档路径
  2. 优先查看
    ~/.ae-cli/wiki/te-docs/synthesis/
    下的概述文档
  3. 如需详细API参考,查看
    ~/.ae-cli/wiki/te-docs/raw/
    下对应的主文档
常用FAQ文档:
  • references/android_sdk_faq.md
    — Android SDK集成与FAQ
  • references/ios_sdk_faq.md
    — iOS SDK集成与FAQ
  • references/java_sdk_faq.md
    — Java SDK集成与FAQ
  • references/logbus2_guide.md
    — LogBus2完整配置指南
  • references/sdk_usage_notes.md
    — 客户端/服务端SDK使用注意事项
  • references/restful_api_notes.md
    — RESTful API使用注意事项
  • 完整列表:查看
    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

集成/使用步骤

  1. <Step 1>
  2. <Step 2> ...
  1. <步骤1>
  2. <步骤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
    te-wiki-synthesize
    skill to generate a new synthesis document.
若FAQ和wiki均无相关内容:

Example Conversations

对话示例

User: What is distinct_id and how do I use it?
Agent:
  1. Read
    references/index.md
    to find user identification rule document paths
  2. If
    sdk_usage_notes.md
    or wiki has relevant sections, read those first
  3. Output in the Step 3 format
User: How do I configure LogBus2?
Agent:
  1. Read
    references/logbus2_guide.md
  2. Output in the Step 3 format
User: Java SDK is losing data — what should I do?
Agent:
  1. Read
    references/java_sdk_faq.md
    , section on "LoggerConsumer data loss risks"
  2. Output in the Step 3 format
User: How do I integrate the Android SDK?
Agent:
  1. Read
    references/android_sdk_faq.md
    or
    ~/.ae-cli/wiki/te-docs/index.md
    to find Android SDK path
  2. Read the relevant sections
  3. Output in the Step 3 format
undefined
用户: distinct_id是什么?如何使用?
Agent:
  1. 阅读
    references/index.md
    查找用户识别规则文档路径
  2. sdk_usage_notes.md
    或wiki有相关章节,优先阅读
  3. 按步骤3的格式输出
用户: 如何配置LogBus2?
Agent:
  1. 阅读
    references/logbus2_guide.md
  2. 按步骤3的格式输出
用户: Java SDK丢失数据——该怎么办?
Agent:
  1. 阅读
    references/java_sdk_faq.md
    中「LoggerConsumer数据丢失风险」章节
  2. 按步骤3的格式输出
用户: 如何集成Android SDK?
Agent:
  1. 阅读
    references/android_sdk_faq.md
    ~/.ae-cli/wiki/te-docs/index.md
    查找Android SDK文档路径
  2. 阅读相关章节
  3. 按步骤3的格式输出
undefined

Android 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)

  1. Add mavenCentral to project-level
    build.gradle
    :
    groovy
    repositories { mavenCentral() }
  2. Add dependency to module-level
    build.gradle
    :
    groovy
    dependencies {
        implementation 'cn.thinkingdata.android:ThinkingAnalyticsSDK:3.3.6'
    }
  3. Initialize SDK:
    java
    TDAnalytics.init(this, SERVER_URL, APPID);
  1. 在项目级
    build.gradle
    中添加mavenCentral:
    groovy
    repositories { mavenCentral() }
  2. 在模块级
    build.gradle
    中添加依赖:
    groovy
    dependencies {
        implementation 'cn.thinkingdata.android:ThinkingAnalyticsSDK:3.3.6'
    }
  3. 初始化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):
  • references/index.md
    — All FAQ document index
  • references/android_sdk_faq.md
    — Android SDK FAQ
  • references/logbus2_guide.md
    — LogBus2 complete guide
  • references/sdk_usage_notes.md
    — SDK usage notes
Wiki Documents (check when FAQ has no answer):
  • ~/.ae-cli/wiki/te-docs/index.md
    — All wiki document index
  • ~/.ae-cli/wiki/te-docs/schema.md
    — Wiki layout description
  • ~/.ae-cli/wiki/te-docs/raw/preparations-before-data-ingestion/user-identification-rules.md
    — User Identification Rules
  • ~/.ae-cli/wiki/te-docs/raw/preparations-before-data-ingestion/data-rules.md
    — Data Rules
  • ~/.ae-cli/wiki/te-docs/raw/preparations-before-data-ingestion/preset-properties-and-system-fields.md
    — Preset Properties
  • ~/.ae-cli/wiki/te-docs/raw/advanced-data-type/updated-event.md
    — Updatable Event
  • ~/.ae-cli/wiki/te-docs/raw/advanced-data-type/first-event-check.md
    — First Event Check
  • ~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/data-import-tools/logbus2-user-guide.md
    — LogBus2
FAQ文档(优先检查):
  • references/index.md
    — 所有FAQ文档索引
  • references/android_sdk_faq.md
    — Android SDK FAQ
  • references/logbus2_guide.md
    — LogBus2完整指南
  • references/sdk_usage_notes.md
    — SDK使用注意事项
Wiki文档(FAQ无答案时检查):
  • ~/.ae-cli/wiki/te-docs/index.md
    — 所有wiki文档索引
  • ~/.ae-cli/wiki/te-docs/schema.md
    — Wiki布局说明
  • ~/.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
    — 首次事件校验
  • ~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/data-import-tools/logbus2-user-guide.md
    — LogBus2