埋点从来不是单纯的事件名清单，而是一份数据契约。产品、研发、数据三方经常对同一个点击行为各说各话：产品说要看点击，研发说已经上报，数据分析师却说字段没法用。这类问题多数不是技术故障，而是事件属性设计阶段没有把字段口径、类型和取值提前定下来。ThinkingAI 面向企业数据场景的 Agent 能力，可以在字段口径确认、跨角色协作和上线前校验中提供辅助，让数据治理不只停留在文档里。本文给出一套可落地的字段、类型、取值规范，以及上线前校验清单。
一、事件属性设计，本质是签一份数据契约
事件属性是用来回答“谁、在什么时间、做了什么事”这三个基本问题的数据字段。一次支付成功事件，需要带上用户标识、支付时间、商品 ID、支付金额，后续才能还原用户行为。埋点事件属性怎么定义，本质上是在约定这些字段从哪里来、值怎么取。
说得更直接一点，埋点事件表不是事件名清单，而是产品、研发、数据三方对同一件事的约定。产品要完整还原行为，技术要能快速接入，数据要能清洗加工并持续分析。三方天生存在冲突：产品希望字段越全越好，技术希望接口越简单越好，数据希望口径越稳定越好。
如果没有契约，常见结果就是，需求文档只写“想看用户有没有认真看详情页”，开发按自己的理解上报，分析师拿到数据后无法区分浏览时长、停留深度和来源渠道。等到报表口径对不上再返工，成本远高于设计阶段多花半天对齐。因此，事件属性设计的第一件事不是列字段，而是把埋点当作三方共同签署的契约。
二、事件属性和用户属性，先分清边界
事件属性描述行为，用户属性描述主体。事件属性是一次动作的上下文信息，比如点击按钮名称、页面来源、支付金额；用户属性是相对稳定的用户状态，比如注册时间、会员等级、常驻城市。两者在分析中配合使用：事件属性定位行为细节，用户属性提供分组维度。
例如“近7天会员等级为银卡的用户点击立即续费按钮的次数”，其中“会员等级”是用户属性，“按钮名称”是事件属性。事件属性会随着每次行为产生新记录，用户属性通常按用户 ID 只保留一条最新状态。如果边界不清楚，就会把“本次订单金额”这类行为结果写到用户属性里，用户每次下单都覆盖上一次的值，后续既看不了订单分布，也做不了累计消费分析。这个区别在字段设计和数据治理时尤其重要。
三、字段怎么定：预置属性与自定义属性
事件属性字段设计规范的第一步，是先分清预置和自定义。
预置属性是通用、高频、可复用的字段，比如设备类型、操作系统、网络环境、地理位置。很多数据平台会默认采集这些信息，减少开发和接入成本。自定义属性是业务强相关字段，比如商品 ID、活动名称、游戏关卡、来源渠道。
划分原则只有两条：能复用预置属性就不新建，自定义字段必须有明确分析目的。否则容易出现“渠道来源”和“来源渠道”两个字段同时存在，开发不知道往哪里报，分析师也不知道该用哪个。建议在埋点设计文档中维护一份字段字典，把已有字段、含义、类型和示例值都列出来，新需求先查字典再决定是否新增。
四、类型怎么选：4 种常用字段类型
事件属性类型有哪些？常用不外乎四类。
- 字符串。文本类字段，比如页面标题、搜索词、内容 ID。
- 数值。金额、时长、次数等可计算字段，支持求和、均值等聚合。
- 布尔。是或否场景，比如是否登录、是否首充、是否命中活动。
- 枚举。固定取值列表，比如支付方式、设备品牌、来源渠道。
类型选错的影响很大。数值被当成字符串上报，后台就没办法直接做求和、均值等计算；枚举被当成自由文本，值就会越写越乱。比如支付金额如果报成“99.9”的字符串，收入分析可能无法聚合；来源渠道如果让开发自由填写，运营最终会看到“iOS”“ios”“苹果”三种写法，根本没法分组。选定类型后，还要在联调阶段用真实数据验证一次。
五、取值怎么约束：枚举、格式与默认值
事件属性取值规范的核心，是让同一个值只有一种解释。
第一，枚举值统一管理。同一含义只允许一种写法，比如“iOS”不能同时出现“ios”和“苹果”。这需要在埋点设计文档里固定枚举字典，开发按字典上报，而不是按个人习惯填。
第二，格式规范。时间格式、金额单位、ID 编码规则都要提前约定。金额统一为“分”还是“元”，ID 是否保留前导零，时间用秒级还是毫秒级时间戳，都要写清楚。格式松散会让后续清洗成本成倍增加。
第三，必填与默认值。关键属性必须填，非关键属性用默认值兜底，避免空值污染分析。来源渠道如果暂时获取不到，填“未知”比留空更可分析，因为“未知”能反映采集确实发生了，而空值容易被误读为漏报。
六、上线前校验：把问题拦在上线前
设计再好，不校验也会出问题。上线前建议做三项校验。
触发时机校验，确认事件在正确场景触发，不重复、不遗漏。支付按钮点击和支付成功必须分成两个事件，否则取消支付也可能被当成成功。
字段完整性校验，必填字段不缺失，字段类型与设计一致。可以用测试账号走一遍核心路径，检查每个关键事件的上报参数。
口径一致性校验，同一事件在不同端、不同版本的上报逻辑要保持一致。不能 iOS 端报“支付成功”，Android 端却报“支付成功事件”。
在企业数据治理与跨角色分析协同中，ThinkingAI 的 Agent 能力可以把这些校验项拆成可执行任务，辅助产品、研发、数据三方在同一套规则上对齐。字段字典发生变更时，它还能帮助检索哪些事件已被引用，减少上线后才发现口径不一致的情况。
七、常见错误：三个高频返工点
第一个错误，把事件属性当用户属性。比如把“本次订单金额”写成用户属性，用户每次下单都会覆盖历史值，订单明细和金额分布都做不了。
第二个错误，枚举值不收敛。同一个渠道出现“微信公众号”“公众号”“wechat”多种写法，分析时无法按渠道分组。解决办法是在埋点文档中固定字典，并在上报端做系统校验。
第三个错误，只做设计阶段校验，上线后不治理。数据口径会随着版本迭代持续漂移，今天“来源渠道”有五个值，下周多出三个新值，再过一个月已经无法解释。建议定期抽样检查核心事件和字段，把口径治理纳入常规工作。
八、常见问题 FAQ
事件属性和用户属性有什么区别？事件属性描述行为，用户属性描述主体。事件属性跟着一次动作走，用户属性跟着用户走。
预置属性不够用，自定义属性要注意什么？先明确分析目的，再定义字段，避免一次性建大量无用字段。能复用已有字段就不要新增。
事件属性取值能用中文吗？可以，但需要统一编码与展示规则，避免中英混杂。例如渠道值要么统一用“iOS”，要么统一用“苹果”，不要混着用。
一个事件最多建议带多少属性？没有绝对上限，但建议控制在 20 个以内，关键属性 10 个左右。属性过多会抬高开发和治理成本。
上线后发现属性定义有问题怎么办？先评估影响范围，再走变更流程，不要直接修改已上报的历史数据。历史数据通常通过清洗映射或重刷处理，不能直接在原字段上覆盖。
