1. 埋点方案选型与架构概览

埋点是移动端数据采集的基石，直接决定数据质量与研发效率。本章从方案选型出发，对比三种主流埋点方案的技术原理与适用场景，并深入 SDK 核心架构，为后续章节打下完整的技术认知框架。

1.1 三种埋点方案对比

1.2 手动埋点原理与代码实现

手动埋点要求在业务代码中显式调用 SDK 提供的数据上报接口。优点是数据语义明确、字段可控；缺点是代码侵入性强，埋点逻辑与业务逻辑耦合。

典型接入流程：

1. 在 Application.onCreate() 中初始化 SDK，传入应用标识与配置参数。
2. 在需要采集事件的页面或控件事件中调用 reportEvent 接口。
3. SDK 内部将事件封装为标准化对象，经加工后写入本地缓存队列。
4. 触发上报条件（定时/阈值/应用切后台）时将缓存数据发送至服务端。

初始化代码示例：

public class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();

        TrackingConfig config = new TrackingConfig.Builder()
                .setAppKey("android_app_demo_2024")
                .setChannel("official")
                .setReportUrl("https://api.example.com/track")
                .setUploadInterval(15)          // 单位：秒
                .setBatchSize(50)               // 单次最大事件数
                .enableAutoTrack(true)          // 开启自动采集基础事件
                .build();

        TrackingSDK.init(this, config);
    }
}

手动埋点调用示例（按钮点击事件）：

button.setOnClickListener(v -> {
    // 采集业务事件
    TrackingSDK.reportEvent("button_click", new EventParams()
            .put("page_name", "home_fragment")
            .put("button_id", "btn_start_order")
            .put("user_id", getCurrentUserId())
    );
});

1.3 无埋点原理与实现

无埋点通过字节码插桩或运行时 Hook 自动采集所有界面事件，开发者在业务层 无需编写任何埋点代码。实现路径分为编译期 AOP 和运行期反射两种。

• 编译期 AOP（ASM / AspectJ）：在 .class 字节码中插入采集逻辑，对 onClick、onItemClick、onPageSelected 等回调进行切面增强。
• 运行期反射：通过动态代理或 View 树遍历，在触摸事件分发阶段采集控件信息，性能开销较大，不推荐在生产环境大规模使用。

无埋点切面采集核心逻辑示意：

@Aspect
public class ViewClickAspect {

    @Pointcut("execution(* android.view.View.OnClickListener.onClick(..))")
    public void viewClick() {}

    @Around("viewClick()")
    public void aroundViewClick(ProceedingJoinPoint joinPoint) throws Throwable {
        // 采集事件前记录上下文
        View view = (View) joinPoint.getArgs()[0];
        String viewId = view.getResources().getResourceName(view.getId());
        String pageName = getPageNameFromView(view);

        // 执行原始点击逻辑
        joinPoint.proceed();

        // 上报事件（异步）
        TrackingSDK.reportEvent("$view_click", new EventParams()
                .put("page_name", pageName)
                .put("view_id", viewId)
                .put("view_type", view.getClass().getSimpleName())
        );
    }
}

1.4 可视化埋点原理与实现

可视化埋点允许运营或产品同学通过 Web 圈选工具在 App 界面上直接选择控件，配置事件名称与属性。配置实时下发到客户端，SDK 动态绑定事件采集逻辑。

实现链路：

• 圈选端：App 开启圈选模式，实时上传当前页面的 View 树快照（包括控件 ID、类型、坐标、文本）。
• 配置平台：运营者在 Web 界面上标记控件并绑定事件元信息，生成 JSON 配置文件。
• 下发通道：配置通过长连接或轮询推送到客户端，SDK 解析后注册对应的 View 监听器。
• 运行时绑定：SDK 在 View 树遍历或事件分发时匹配配置规则，命中后自动上报。

配置下发 JSON 示例：

{
    "config_id": 1024,
    "version": 3,
    "rules": [
        {
            "page": "com.example.MainActivity",
            "view_id": "btn_start_order",
            "event_name": "order_start_click",
            "properties": {
                "source": "visual_config"
            },
            "ttl_ms": 86400000
        },
        {
            "page": "com.example.DetailActivity",
            "view_id": "iv_product",
            "event_name": "product_image_click",
            "properties": {
                "from_visual": true
            },
            "ttl_ms": 86400000
        }
    ]
}

1.5 SDK 架构设计

无论选择哪种埋点方案，底层 SDK 均遵循 采集 → 加工 → 存储 → 上报 的管道架构。各模块职责清晰，支持独立扩展与性能调优。

1.6 SDK 集成配置

在 Android 工程中集成埋点 SDK 通常只需添加依赖并在 AndroidManifest.xml 中声明必要权限。以下为标准配置模板：

build.gradle（Module 级）依赖添加：

dependencies {
    // 埋点 SDK 核心库
    implementation 'com.example:tracking-sdk:2.5.0'

    // 如果使用无埋点方案，需要添加编译期插件
    implementation 'com.example:tracking-sdk-aop:2.5.0'
    annotationProcessor 'com.example:tracking-sdk-compiler:2.5.0'
}

AndroidManifest.xml 权限声明：

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

<!-- 无埋点模式需添加系统窗口权限，用于圈选功能 -->
<uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />

1.7 数据上报接口与格式

SDK 统一将采集到的事件序列化为 JSON 对象，通过 HTTP POST 批量上报。上报接口设计遵循幂等、可重试、压缩传输原则。

单次上报请求体结构：

{
    "app_key": "android_app_demo_2024",
    "device_id": "866b8c3a-2f4e-4a1d-9e7c-0f1a2b3c4d5e",
    "session_id": "sess_20240918_183200_abc123",
    "events": [
        {
            "event_name": "button_click",
            "properties": {
                "page_name": "home_fragment",
                "button_id": "btn_start_order"
            },
            "timestamp_ms": 1726653120000,
            "event_id": "evt_001a2b3c"
        },
        {
            "event_name": "$page_view",
            "properties": {
                "page_name": "home_fragment",
                "referrer": "splash_activity"
            },
            "timestamp_ms": 1726653118000,
            "event_id": "evt_004d5e6f"
        }
    ],
    "batch_id": "batch_20240918_183201",
    "upload_time_ms": 1726653121000
}

服务端响应（HTTP 200）：

{
    "code": 0,
    "message": "success",
    "data": {
        "accepted_count": 2,
        "rejected_count": 0,
        "next_upload_interval_sec": 15
    }
}

1.8 调试与验证

在开发阶段快速验证埋点是否正确上报，推荐以下两种调试手段：

• Logcat 日志过滤：SDK 内部使用统一 Tag（如 TrackingSDK）输出事件采集与上报日志。
• Stetho / Charles 抓包：代理到本地服务，检查请求体 JSON 结构与字段完整性。

常用调试命令：

# 查看 SDK 初始化和事件采集日志
adb logcat -s TrackingSDK:V

# 过滤上报请求与响应
adb logcat -s TrackingSDK:V | grep -E "report|upload|response"

# 查看无埋点切面是否生效
adb logcat -s ViewClickAspect:V

1.9 常见错误分析与性能优化

性能优化核心策略：

1. 批量上报：将多个事件合并为一个 HTTP 请求，减少网络连接开销。默认阈值建议 30–50 条或 15 秒间隔。
2. 数据压缩：上报请求体使用 gzip 压缩，压缩率可达 70%–85%，显著降低流量消耗。
3. 采样率控制：对高频事件（如 $view_click）按百分比采样，非核心事件降低采样率至 10%–30%。
4. 缓存分级：热数据驻留内存环形缓冲区，冷数据写入 SQLite，防止频繁 I/O 拖慢 UI 线程。