4. 自定义Composable埋点包装器：通用 trackable 函数

在前几章我们学习了手动埋点与状态驱动埋点，但在实际项目中往往需要覆盖数十甚至上百个界面/组件。如果每个Composable都重复编写LaunchedEffect+DisposableEffect片段，代码会变得臃肿且难以维护。本章实现一个通用的高阶Composable包装器——trackable函数，它将埋点逻辑抽象到单一入口，通过参数化配置实现“声明式埋点”。

4.1 原理：高阶Composable + 生命周期委托

trackable本质上是一个高阶Composable（接受另一个Composable lambda作为内容），在其内部注入埋点观察逻辑。它利用Compose的DisposableEffect监听组件的挂载与卸载，利用LaunchedEffect监听参数变化并触发自定义事件。核心思路是：

• 挂载时：自动上报view（曝光）事件。
• 参数更新时：对比前后状态，上报update或属性变更事件。
• 卸载时：上报disappear或埋点清理事件。

4.2 参数设计

4.3 生命周期绑定实现

包装器内部利用三个Compose副作用函数精确绑定生命周期：

• DisposableEffect：挂载时触发曝光，卸载时触发消失；其onDispose块保证清理。
• LaunchedEffect(trackProperties)：当trackProperties变化时执行更新事件逻辑。
• remember：缓存TrackableSession对象，避免重复创建。

@Composable
fun <T> trackable(
    trackName: String,
    trackProperties: Map<String, String> = emptyMap(),
    onView: ((String, Map<String, String>) -> Unit)? = null,
    onDisappear: ((String, Map<String, String>) -> Unit)? = null,
    onUpdate: ((String, Map<String, String>, Map<String, String>) -> Unit)? = null,
    content: @Composable () -> Unit
) {
    // 1. 获取全局上报器（CompositionLocal或依赖注入）
    val tracker = LocalTracker.current

    // 2. 记录旧属性用于对比
    val oldProperties = remember { mutableStateOf(emptyMap<String, String>()) }

    // 3. 挂载/卸载生命周期
    DisposableEffect(trackName) {
        val viewEvent = TrackEvent.View(trackName, trackProperties)
        // 执行曝光事件
        onView?.invoke(trackName, trackProperties) ?: tracker.track(viewEvent)

        onDispose {
            val disappearEvent = TrackEvent.Disappear(trackName, trackProperties)
            onDisappear?.invoke(trackName, trackProperties) ?: tracker.track(disappearEvent)
        }
    }

    // 4. 属性更新监听（仅在属性变化时触发）
    LaunchedEffect(trackProperties) {
        if (oldProperties.value.isNotEmpty() && oldProperties.value != trackProperties) {
            val updateEvent = TrackEvent.Update(trackName, oldProperties.value, trackProperties)
            onUpdate?.invoke(trackName, oldProperties.value, trackProperties)
                ?: tracker.track(updateEvent)
        }
        oldProperties.value = trackProperties
    }

    // 5. 渲染原始内容
    content()
}

4.4 完整使用示例

// 在项目中定义Tracker接口
interface Tracker {
    fun track(event: TrackEvent)
}

// 使用CompositionLocal提供
val LocalTracker = staticCompositionLocalOf<Tracker> {
    error("No Tracker provided")
}

// 实际组件中使用
@Composable
fun ProductCard(product: Product) {
    trackable(
        trackName = "home_productCard",
        trackProperties = mapOf(
            "productId" to product.id,
            "category" to product.category
        ),
        onView = { name, props ->
            // 自定义埋点，例如Firebase Analytics
            FirebaseAnalytics.logEvent(name, props)
        }
    ) {
        // 正常UI
        Card(modifier = Modifier.fillMaxWidth()) {
            Text(product.name)
            Text("¥${product.price}")
        }
    }
}

4.5 调试技巧

• 日志模式：在调试构建中给LocalTracker注入一个LogcatTracker，直接在Logcat输出所有埋点事件。
• 验证生命周期顺序：启用Compose的compose:trackLifecycle指标（需开启Compose Compiler Metrics）查看DisposableEffect是否配对。
• 属性变化检测：在LaunchedEffect内打印oldProperties与trackProperties，确保Map比较正确。

4.6 性能优化

4.7 架构流程图

4.8 小结

trackable包装器将埋点生命周期管理收敛到一处，通过参数化配置覆盖了曝光、更新、消失三种核心事件。配合CompositionLocal注入上报器，开发者只需一行trackable(...)即可完成组件埋点，极大提升了代码复用性与可维护性。在下一实战章节将基于此包装器构建立即埋点SDK。