2. Android埋点数据模型设计：事件、属性、用户标识、会话、时间戳

任何可靠埋点方案的基石都是一个设计良好的数据模型。它确保了从采集到分析的数据一致性，使团队能够信任其业务指标。本章深入探讨构成几乎所有商业化SDK基础的五个核心支柱，并给出在Android端的具体建模与实现建议。

2.1 核心概念与职责

这五个对象共同定义了“一条有效埋点数据”的完整边界。下表对比了它们的职责与在SDK中的典型实现方式：

2.2 数据模型关系与生命周期

下图展示了在Android客户端内部，一次埋点行为从触发到组装成完整的日志对象，五者之间的协作关系：

2.3 代码实现：Android端数据模型定义

在实际的Android工程中，推荐使用Kotlin数据类（Data Class）来强制约束字段类型。以下是核心数据模型的定义示例：

// Event.kt - 核心埋点数据结构
data class TrackEvent(
    @SerializedName("event_name")
    val eventName: String,                          // 必填：事件名
    @SerializedName("properties")
    val properties: Map,               // 必填：属性Map，可传入emptyMap()
    @SerializedName("user_info")
    val userInfo: UserInfo,                         // 必填：用户标识对象
    @SerializedName("session_info")
    val sessionInfo: SessionInfo,                   // 必填：会话对象
    @SerializedName("timestamp")
    val timestamp: Long,                            // 必填：事件触发时间戳
    @SerializedName("event_id")
    val eventId: String = UUID.randomUUID().toString() // 可选：幂等去重ID
)

// UserInfo.kt
data class UserInfo(
    @SerializedName("user_id")
    val userId: String = "",
    @SerializedName("device_id")
    val deviceId: String = ""
)

// SessionInfo.kt
data class SessionInfo(
    @SerializedName("session_id")
    val sessionId: String
)

2.4 数据上报接口示例

组装完成后的对象最终会被序列化为JSON，通过HTTP POST发送至埋点服务端。以下是最终上报的标准化载荷格式：

{
  "event_name": "purchase_complete",
  "properties": {
    "item_id": "sku_123456",
    "item_name": "高级会员订阅",
    "price": 199.00,
    "currency": "CNY"
  },
  "user_info": {
    "user_id": "u_98765",
    "device_id": "d_abc_xyz_0001"
  },
  "session_info": {
    "session_id": "s_20231027_14_001"
  },
  "timestamp": 1698400000123,
  "event_id": "evt_uuid_xxxx"
}

2.5 调试与常见错误分析

在实际开发中，数据模型层面的错误通常会导致埋点数据缺失或分析结果偏差。以下是三类高发错误的规避方式：