3. 手动埋点核心实现：Application、Activity、Fragment 生命周期埋点

3.1 埋点原理

手动埋点的核心思路是在 Android 系统组件的关键生命周期回调方法中，嵌入自定义事件采集代码。通过监听Application、Activity、Fragment的启动、可见、不可见、销毁等节点，能够精准捕获用户使用路径、页面停留时长、页面打开次数等基础指标。

每个周期埋入的事件经由内部队列缓存，按批次或实时发送至服务端。手动方式虽然代码侵入性稍高，但可完全控制采样率、过滤逻辑，以及自定义扩展字段。

3.2 核心实现流程

以下流程图展示了从应用启动到页面销毁的过程中，各生命周期方法中埋点事件的采集与上报步骤。

实现步骤如下：

1. 在自定义Application类的onCreate()中初始化埋点 SDK。
2. 调用registerActivityLifecycleCallbacks()注册全局 Activity 生命周期监听器。
3. 在监听器的回调（onActivityCreated、onActivityStarted、onActivityResumed、onActivityPaused、onActivityStopped、onActivityDestroyed）中插入埋点代码。
4. 对于 Fragment，使用fragmentManager.registerFragmentLifecycleCallbacks()做类似处理。
5. 将采集到的事件统一放入内存队列，通过工作线程或定时器调用上报接口。

public class MyApp extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        // 1. 初始化埋点 SDK
        TrackerSDK.init(this, "YOUR_APP_KEY");
        // 2. 注册全局 Activity 生命周期回调
        registerActivityLifecycleCallbacks(new ActivityLifecycleCallbacks() {
            @Override
            public void onActivityCreated(Activity activity, Bundle savedInstanceState) {
                TrackerSDK.trackEvent("activity_created", activity.getClass().getSimpleName());
            }
            @Override
            public void onActivityStarted(Activity activity) {
                // 可选：埋点页面开始
            }
            @Override
            public void onActivityResumed(Activity activity) {
                TrackerSDK.trackEvent("activity_resumed", activity.getClass().getSimpleName());
                // 记录页面开始时间
                PageTracker.start(activity.getClass().getSimpleName());
            }
            @Override
            public void onActivityPaused(Activity activity) {
                // 计算页面停留时长并上报
                long duration = PageTracker.stop(activity.getClass().getSimpleName());
                TrackerSDK.trackEvent("activity_paused", activity.getClass().getSimpleName(), duration);
            }
            @Override
            public void onActivityStopped(Activity activity) {
                // 可选：埋点页面停止
            }
            @Override
            public void onActivityDestroyed(Activity activity) {
                TrackerSDK.trackEvent("activity_destroyed", activity.getClass().getSimpleName());
            }
        });
    }
}

3.3 SDK 集成配置

在build.gradle模块级别添加依赖，并同步项目。

dependencies {
    implementation 'com.example:tracker-sdk:1.2.0'
}

在AndroidManifest.xml中声明自定义 Application（如果尚未配置）：

<application
    android:name=".MyApp"
    ... />

若项目使用了多进程，需要在Application中通过进程名判断只初始化主进程埋点，避免重复事件。

3.4 数据上报接口

埋点 SDK 内部通常提供同步/异步两种上报接口。以下为典型封装形式：

public class TrackerSDK {
    public static void trackEvent(String eventName, String label) {
        // 将事件加入内存队列，后台线程负责上报
        EventQueue.add(new Event(eventName, label, System.currentTimeMillis()));
    }

    public static void trackEvent(String eventName, String label, long duration) {
        EventQueue.add(new Event(eventName, label, duration, System.currentTimeMillis()));
    }

    public static void flush() {
        // 强制触发一次上报
        HttpUploader.upload(EventQueue.drainAll());
    }
}

网络请求部分采用 HTTP/HTTPS POST，数据格式为 JSON：

POST /api/v1/track HTTP/1.1
Host: tracker.example.com
Content-Type: application/json; charset=utf-8

[
  {
    "event": "activity_resumed",
    "label": "MainActivity",
    "duration": 0,
    "timestamp": 1712048100000,
    "device_id": "xxxx-xxxx-xxxx-xxxx"
  },
  {
    "event": "activity_paused",
    "label": "MainActivity",
    "duration": 3200,
    "timestamp": 1712048103200,
    "device_id": "xxxx-xxxx-xxxx-xxxx"
  }
]

3.5 调试与验证

推荐调试步骤如下：

1. 在 TrackerSDK.trackEvent() 中增加 Log 输出，打印事件名、类名、时间戳。
2. 使用 Android Studio 的 Logcat 过滤关键字 TrackerSDK 或 TrackEvent，观察每个生命周期节点是否被触发。
3. 在 onPause() 与 onResume() 之间切换 App 到后台再返回，确认成对出现。
4. 通过抓包工具（Charles / Wireshark）或 SDK 内置请求日志，检查上报 JSON 格式与字段正确性。

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

性能优化建议

• 事件合并：相同事件在短时间内多次触发时（如快速旋转屏幕），应合并为一条带次数字段的事件。
• 批量上报：每 30 秒或积攒 20 条事件集中上报一次，减少网络请求次数。
• 懒加载初始化：SDK 初始化可在 onCreate 中使用轻量级启动，上报线程等耗时操作延迟到首次 onResume 之后。
• 避免主线程挂起：flush() 方法应在后台线程调用，或者暴露 flushAsync() 接口。