3. 埋点 SDK 初始化与依赖注入：Gradle 配置、Application 初始化、Hilt/手动注入

埋点 SDK 的初始化是数据采集的起点，决定了事件能否正常上报、生命周期是否对齐、模块间是否可解耦。本章围绕 Gradle 依赖声明、Application 启动阶段初始化、依赖注入（Hilt / 手动注入） 三条主线，给出可落地的实现方案与调试要点。

3.1 Gradle 依赖配置与版本管理

埋点 SDK（以开源组件 TrackerSDK 为例）需作为 module 级别依赖引入。建议在项目根 build.gradle.kts 统一版本号，避免多 module 冲突。

// 项目级 build.gradle.kts
ext {
    set("trackerVersion", "2.1.0")
    set("hiltVersion", "2.48")
}

// app/build.gradle.kts
dependencies {
    implementation("com.example:tracker-sdk:${rootProject.ext["trackerVersion"]}")
    implementation("com.google.dagger:hilt-android:${rootProject.ext["hiltVersion"]}")
    kapt("com.google.dagger:hilt-compiler:${rootProject.ext["hiltVersion"]}")
}

3.2 Application 初始化埋点 SDK

在 onCreate() 中尽早初始化，但需注意不要阻塞主线程。推荐使用 ContentProvider 启动方式（SDK 内置）或手动调用。

class App : Application() {
    override fun onCreate() {
        super.onCreate()
        // 手动初始化（适用于未使用自动启动的 SDK）
        val config = TrackerConfig.Builder()
            .appId("com.example.app")
            .channel("GooglePlay")
            .enableAutoPageTrack(true)
            .build()
        TrackerManager.init(this, config)
        // 注册 Activity 生命周期回调（自动采集页面停留）
        registerActivityLifecycleCallbacks(TrackerLifecycleCallbacks())
    }
}

3.3 Hilt 注入实现

将 TrackerManager 封装为 Hilt 单例，便于在 ViewModel / UseCase 中直接注入。

// TrackerModule.kt
@Module
@InstallIn(SingletonComponent::class)
object TrackerModule {

    @Provides
    @Singleton
    fun provideTrackerManager(@ApplicationContext context: Context): TrackerManager {
        return TrackerManager.getInstance(context)
    }

    @Provides
    @Named("trackerConfig")
    fun provideTrackerConfig(): TrackerConfig {
        return TrackerConfig.Builder()
            .appId("com.example.app")
            .channel("GooglePlay")
            .enableAutoPageTrack(true)
            .build()
    }
}

// 在 ViewModel 中使用
@HiltViewModel
class HomeViewModel @Inject constructor(
    private val trackerManager: TrackerManager
) : ViewModel() {
    fun onButtonClicked(buttonId: String) {
        trackerManager.track(
            Event("button_click")
                .put("button_id", buttonId)
        )
    }
}

3.4 手动注入（无 Hilt 场景）

在不引入 Dagger/Hilt 的旧项目或小型 Demo 中，通过 Application 单例或 ServiceLocator 模式手动传递。

object TrackerLocator {
    private lateinit var trackerManager: TrackerManager

    fun init(context: Context) {
        val config = TrackerConfig.Builder()
            .appId("com.example.app")
            .build()
        trackerManager = TrackerManager.init(context, config)
    }

    fun getTracker(): TrackerManager = trackerManager
}

// 初始化
class App : Application() {
    override fun onCreate() {
        super.onCreate()
        TrackerLocator.init(this)
    }
}

// ViewModel 中获取
class HomeViewModel : ViewModel() {
    private val tracker = TrackerLocator.getTracker()
    fun trackEvent() { tracker.track(Event("test")) }
}

3.5 初始化时序与性能优化

埋点 SDK 初始化通常涉及文件读写、网络配置请求（如动态开关）。建议遵循以下流程：

1. 第一阶段（onCreate）：加载本地缓存配置 + 创建核心实例（< 10ms）
2. 第二阶段（ContentProvider onCreate）：如果 SDK 支持自动启动，可在 ContentProvider 中初始化，优先级高于 Application（但需注意 ContentProvider 生命周期）
3. 第三阶段（首帧之后）：发起远程配置请求、初始化定时上传任务（使用 frameCallback 或 Handler.postDelayed 延迟 500ms）

// 延迟初始化示例（适用于非关键模块）
Handler(Looper.getMainLooper()).postDelayed({
    TrackerManager.fetchRemoteConfig()
    TrackerManager.startUploadScheduler()
}, 500L)

3.6 本章核心流程图

3.7 常见问题与调试