埋点基础设计整理埋点系统设计方案总纲项目背景为了更好地了解用户行为，提升产品体验和业务决策，我们需要建立一套完整的埋

埋点系统设计方案总纲（一期简化版）

项目背景

为了更好地了解用户行为，提升产品体验和业务决策，我们需要建立一套埋点数据收集系统。一期重点实现批量上报功能，支持多平台（iOS、Android、H5）数据收集和基础存储。

一期核心需求

上报策略

批量上报：收集用户行为数据，在页面离开、应用切换到后台、达到阈值时批量上报，减少网络请求压力

数据格式规范

所有埋点事件必须包含以下核心字段：

字段名	类型	说明	示例
event_key	keyword	事件key	register_success
event_name	keyword	事件名称	完成注册
event_time	date	事件时间	2026-01-22 15:00:00
event_type	keyword	事件类型	查询
user_id	keyword	用户ID	123456
user_name	keyword	用户名	张三
device_id	keyword	设备id	abcdef123456
platform	keyword	操作系统类型	Android
network_type	keyword	网络型号	wifi
os_version	keyword	系统版本号	16.5.1
app_version	keyword	App 版本号	5.2.0
function_path	keyword	模块/页面/功能	注册/注册/完成注册
function_name	keyword	点击功能名称	注册
user_token	keyword	用户token	abcdefg1234561
extraParam	text	扩展参数JSON	{"attr1":"手机","attr2":"App Store"}

extraParam说明：

存储格式：JSON字符串格式存储扩展参数，用于客户端本地数据库
参数键名：使用 attr1, attr2, attr3... 格式作为键名
动态配置：根据不同事件类型动态传递所需参数
转换逻辑：SDK上报时将extraParam JSON解析并展开为接口需要的attr字段

数据转换流程：

采集阶段：SDK接收attr对象 → 转换为JSON字符串 → 存储到extraParam字段
上报阶段：从数据库读取extraParam → JSON解析 → 展开为attr1,attr2...字段 → 发送到接口
接口要求：服务器接收的是展开的attr字段，不是JSON字符串

转换代码示例：

// 存储时：对象 → JSON字符串
const eventData = {
  attr1: "手机",
  attr2: "App Store",
  attr3: "无"
};
const extraParam = JSON.stringify(eventData); // 存储到数据库

// 上报时：JSON字符串 → 展开对象
const parsedData = JSON.parse(extraParam); // 从数据库读取
const requestData = {
  event_key: "register_success",
  // ... 其他字段
  ...parsedData // 展开为 attr1, attr2, attr3...
};
// 发送到接口

数据存储格式示例（本地数据库）：

{
  "event_key": "register_success",
  "event_name": "完成注册",
  "function_name": "注册",
  "function_path": "注册/注册/完成注册",
  "event_time": "2026-01-22 15:00:00",
  "user_id": "user_001",
  "user_name": "张三",
  "device_id": "device_abc123",
  "platform": "android",
  "network_type": "wifi",
  "os_version": "13.2",
  "app_version": "1.0.5",
  "user_token": "token_123456",
  "extraParam": "{\"attr1\":\"手机\",\"attr2\":\"App Store\",\"attr3\":\"无\",\"attr4\":\"无\",\"attr5\":\"无\"}",
  "status": 0
}

数据传输格式示例（接口上报，extraParam会被展开）：

{
  "events": [
    {
      "event_key": "register_success",
      "event_name": "完成注册",
      "function_name": "注册",
      "function_path": "注册/注册/完成注册",
      "event_time": "2026-01-22 15:00:00",
      "user_id": "user_001",
      "user_name": "张三",
      "device_id": "device_abc123",
      "platform": "android",
      "network_type": "wifi",
      "os_version": "13.2",
      "app_version": "1.0.5",
      "user_token": "token_123456",
      "attr1": "手机",
      "attr2": "App Store",
      "attr3": "无",
      "attr4": "无",
      "attr5": "无"
    }
  ]
}

系统架构设计

整体架构图

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   iOS App       │    │   Android App   │    │     H5 App      │
│  (Obj-C SDK)    │    │   (Java SDK)    │    │  (JS SDK)       │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 │
                    ┌─────────────────┐
                    │   埋点数据服务    │
                    │   (Java Spring) │
                    └─────────────────┘

技术栈选型

服务端：Java Spring Boot + Elasticsearch + Redis
客户端存储：
- iOS：SQLite
- Android：SQLite
- H5：IndexedDB
数据压缩：GZIP + Protobuf（一期必选）
数据存储：Elasticsearch（埋点数据存储和检索）

一期核心功能

1. 数据采集SDK

提供统一的数据采集接口，支持多平台：

事件跟踪：track(eventName, properties)
用户管理：setUserId(), setUserProperties()
设备信息：自动采集设备和系统信息
配置管理：从后台获取上报策略配置
本地存储：SQLite/IndexedDB数据持久化（extraParam JSON格式）
数据转换：上报时将extraParam JSON解析并展开为attr字段
状态管理：跟踪数据上传状态，防止重复上传
数据压缩：GZIP + Protobuf压缩后传输
定时任务：根据配置定时批量上报

2. 数据处理服务

配置接口：/api/config/buried-point - 提供上报策略配置
数据接收：/api/events/track - 批量接收压缩的埋点数据
数据解压：自动解压GZIP + Protobuf数据
数据验证：格式校验、必填字段检查
数据存储：存储到Elasticsearch
响应格式：统一的API响应结构

3. 批量上报机制

上报策略配置

配置接口：/api/config/buried-point - 获取上报配置参数
配置参数：
- batch_size：批量上报条数阈值（默认50条）
- report_interval：定时上报间隔（秒，默认30秒）

触发条件

页面离开时（beforeunload事件）
应用切换到后台时
数据条数达到阈值（从配置接口获取）
定时上报（从配置接口获取时间间隔）
网络恢复时

数据传输格式

原始格式：JSON数组批量提交
字段转换：extraParam JSON → 展开为attr1,attr2,attr3...字段
压缩格式：JSON → Protobuf序列化 → GZIP压缩
Content-Type：application/x-protobuf-gzip
解压处理：服务端自动解压并解析

本地存储策略

数据库：SQLite（iOS/Android）/ IndexedDB（H5）
存储原则：每一条记录存储完整的埋点数据结构，便于管理和查询

数据表结构：

CREATE TABLE buried_point_events (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    -- 核心必填字段
    event_key TEXT NOT NULL,
    event_name TEXT,
    event_time TEXT NOT NULL,
    event_type TEXT DEFAULT 'batch',
    user_id TEXT,
    user_name TEXT,
    device_id TEXT NOT NULL,
    platform TEXT,
    network_type TEXT,
    os_version TEXT,
    app_version TEXT,
    function_path TEXT,
    function_name TEXT,
    user_token TEXT,
    extraParam TEXT,  -- JSON字符串存储扩展参数，如：{"attr1":"value1","attr2":"value2"}
    -- 状态管理字段
    status INTEGER DEFAULT 0,  -- 0:未上传 1:上传中 2:已上传 3:上传失败
    create_time DATETIME DEFAULT CURRENT_TIMESTAMP,
    update_time DATETIME DEFAULT CURRENT_TIMESTAMP,
    -- 索引优化
    UNIQUE(event_key, device_id, event_time)  -- 防止重复数据
);

-- 创建索引提升查询性能
CREATE INDEX idx_status ON buried_point_events(status);
CREATE INDEX idx_create_time ON buried_point_events(create_time);
CREATE INDEX idx_event_key ON buried_point_events(event_key);

上传状态管理

0-未上传：新采集的数据，等待上报
1-上传中：正在上传，防止重复上传
2-已上传：上传成功，可清理
3-上传失败：上传失败，下次上报时重新尝试

数据压缩策略

压缩算法：GZIP + Protobuf
压缩时机：批量数据上报前进行压缩
解压处理：服务端接收后自动解压
压缩效果：显著减少传输数据量，提高网络效率

防重复上传机制

上传前检查状态，避免重复上传
上传中状态锁定，上传完成后更新状态
失败数据保持状态，下次触发上报时重新尝试
定期清理已上传的过期数据

二期规划功能

核心功能扩展

实时上报：支持关键事件实时上报，确保数据不丢失
崩溃数据优先上报：应用崩溃时优先上报关键数据
去重机制：10秒内相同事件仅上报一次，避免数据冗余
敏感数据脱敏：自动脱敏手机号、身份证等敏感信息

管理后台系统

事件管理：配置和管理埋点事件
数据查询：支持多维度数据检索和统计
监控告警：系统状态监控和异常告警

高级功能

数据分析：基于Elasticsearch的实时数据分析
可视化报表：用户行为数据可视化展示
API管理：开放数据查询API接口

一期实施计划

第一阶段：服务端开发（2周）

设计Elasticsearch索引结构
实现上报策略配置API接口（/api/config/buried-point）
实现批量数据接收API接口（/api/events/track）
实现数据解压功能（GZIP + Protobuf）
实现基础数据验证和存储
搭建Spring Boot项目框架

第二阶段：SDK开发（3周）

iOS Objective-C SDK开发（本地SQLite存储、状态管理、GZIP+Protobuf压缩、批量上报）
Android Java SDK开发（本地SQLite存储、状态管理、GZIP+Protobuf压缩、批量上报）
H5 JavaScript SDK开发（IndexedDB存储、状态管理、GZIP+Protobuf压缩、批量上报）
各平台配置接口集成和压缩功能测试

第三阶段：测试上线（1周）

功能测试和性能测试
各平台集成验证
上线部署和监控

总结

一期埋点系统专注于批量上报的核心功能，采用简洁的数据格式（attr1-attr7传递事件特定参数），通过后台配置接口控制上报策略，客户端本地数据库存储确保数据可靠性。状态管理机制有效防止重复上传，确保数据的完整性和准确性。

核心特性：

配置驱动：上报策略通过后台接口动态配置
完整存储：本地存储完整埋点数据结构，便于管理和查询
灵活扩展：extraParam JSON字段支持动态参数配置
数据转换：本地JSON存储 → 接口展开字段的自动转换
状态管理：四种状态标记防止重复上传和数据丢失
简化重试：失败数据通过下次上报重新尝试，降低复杂性
数据压缩：GZIP + Protobuf压缩显著减少传输量
定时定量：灵活的上报触发机制适应不同场景

二期将扩展实时上报、去重机制、敏感数据脱敏、管理后台等高级功能，形成完整的埋点数据分析体系。

当前设计以实用性和快速上线为优先，满足业务方对基础数据收集的需求。