闲谈萌推采集上报

[ajccom]

萌推项目的采集上报规范在立项之初基本已经定义完备，在后续业务迭代过程中也得到了充分的验证。

埋点规范

萌推的采集上报基于集团的采集上报工具，为了区分集团采集上报的预留字段，所有萌推项目上报的字段都以字母 x 开头。比如 type 字段，在原始报表中是 xtype 字段。

萌推所有业务上报字段的值，均为字符串格式或者 NULL。这个的缘由是原始数据落库处理时会将值根据其数据类型放入不同的字段，比如 a= 123，最终落库的数据为 a={int_type=123, long_type=0, float_type=0.0, string_type=0}，如果是 a="xyz"，落库后成了 a={int_type=0, long_type=0, float_type=0.0, string_type=xyz}。为了清洗数据方便，我们规定所有上报字段都用字符串格式。

通用字段

萌推项目每次上报都使用一些通用字段，通用字段中部分来自集团使用的字段，部分来自项目自定义字段，枚举如下：

字段	含义
member_id	用户 id，值为萌推 uid 的 hash 值
kuid	反作弊侧提供的设备识别码
ua	浏览器 ua 信息
ref	HTTP Referrer 信息
xtype	上报类型，有 pv、mt、res.imp 等
xpage_name	当前页 page name，比如商详页 goods_detail
xpage_id	当前页 page id
xkey_param	当前页的细分参数，不同页面，其所表述的内容含义不同
xref_page_name	来源页 page name
xref_page_id	来源页 page id
xref_key_param	来源页 key param 值
xref_pos_id	来源页位置 id
xplatform	平台信息 微信商城 2，小程序 4，iOS 30，安卓 40，QTT 导量 110
xe_time	上报产生时间点，同步服务器时间
xapp_ver	APP 版本号
xenv	环境信息，取值只有 NULL 和 test，test 表示非生产环境，一般清洗数据需要剔除 test 数据

kuid 和 tuid 关系

关于 kuid，kuid 在 iOS 和安卓下可以被解析为有效的 tuid，在其他非 APP 环境下皆无法正确解析为 tuid。

• kuid: 设备在某项目下唯一 id
• tuid：设备唯一 id，跨项目，不同项目的 kuid，同一设备解析出的 tuid 是相同的。

另外，萌推 H5 页面在 APP 环境下是使用 APP kuid 进行上报，所以无需区分 APP 下是 H5 还是原生上报。

xe_time 字段

集团上报 SDK 是收集上报机制，会在一个时间跨度之后将收集的上报一次性全部发送，即 N 条上报信息到达服务器的时间相同，所以上报产生时间需要通过 xe_time 字段记录。

类型枚举

上报的类型种类比较繁多，理论上是可以无限扩展的，常用的有 pv、action.click 等，这里先枚举一些常用的类型：

xtype 取值	表达类型
action.click	点击事件
launch	启动页上报，仅安卓 APP 有该上报
login	登陆上报
action.order	下单行为
action.order.pay	订单支付行为
action.click.cart	购物车行为
action.share	分享行为
action.search	搜索行为
action.download	下载行为，一般发生在站外

还有一些常用上报类型下面细述。

pv 上报

pv 上报一般指用户访问一个页面之初的上报，用来记录该页面的 page view，进而可以得到 user view 等数据。

pv 上报的 xtype 字段值为 pv。每个页面都设有独有的 page name 值。

可以查阅 km 文档：http://km.innotechx.com/pages/viewpage.action?pageId=76903202

另，每一次 pv 上报都使用不同的 page id。为了防止 page id 重复，其生成规则采用了时间和空间维度双重保障，具体规则如下：

page_name + 时间戳 + 10 位随机字符串

page id 的生命周期可以理解为页面访问到页面退出，可以合理用在比如路径查找、订单归因等数据清洗过程中。

在 qe 平台上有清洗的实时 pv 表：mengtuidw.dwd_bhv_pv_rt

曝光上报

曝光上报包含商品曝光上报、页面模块曝光上报等，其 xtype 值为 res.imp。

曝光上报一般伴随两个特别字段 pos_id 和 res_id。其含义如下：

字段	含义
pos_id	位置 id
res_id	资源 id

可以通过这两个字段精确到页面具体位置的上报，其知晓上报内容。比如 pos_id = 'recommend.1'，res_id = 'goods?id=1002832'，表示来源于页面的推荐列表，曝光的商品 id 是 1002832。

相关 pos_id 及 res_id 定义可以查看文档：http://km.innotechx.com/pages/viewpage.action?pageId=40140937

在 qe 平台上有清洗的实时曝光表：mengtuidw.dwd_bhv_exposure_rt

tdata 字段上报

tdata 字段是推荐这边比较关注的一个字段，它不仅限于一个特定类型的上报中，而是结合在包括 pv、res.imp 等上报中，通常以 xtdata 字段标识其值。

xtdata 字段值是一个 JSON String，其中包含了业务方需要的信息。

上报路径

tdata 上报拥有一条包含曝光到下单，比较完整的上报链路，如下所示：

算法推荐 -> GO 商品列表接口 -> 客户端曝光 -> 用户点击至商详 -> 用户下单

通过这个路径，能够保障 tdata 字段可以最终关联上商品产生的订单。

字段透传

在上述路径中，tdata 字段值会被一直透传，直至后续路径断开。该过程中，对 tdata 字段值一律不作处理，所以最终上报内容是等于下发内容的。了解这一点有助于快速排出问题。

业务划分

另外，tdata 字段目前有 2 个业务在使用，一个是算法推荐，另一个是广告系统。算法推荐使用 5 个 key，分别是 req_id, p_score, o_score, from, s_score，目前除了 req_id 字段，其他几个字段比较鲜见；广告系统使用 1 个 key: ads_report。 所以在调整 tdata 字段时需要注意不影响其他业务，并且及时通知维护文档：http://km.innotechx.com/pages/viewpage.action?pageId=97708332

session 上报

session 上报是在发生和商品相关的上报时，增加的一种冗余上报，

上报规则

session 上报的 type 值为 session。该上报中使用 xsession 字段表达上报内容，xsession 字段值是一个 JSON String，其中 key 枚举如下：

字段	含义
member_id	用户 id
opid	kuid
gid	goods id
time	上报时间
from_page_id	来源页 page id
page_id	当前页 page id
action_type	session 上报的前置上报类型
page_name	当前页 page name
from_page_name	来源页 page name
key_param	当前页 key param
from_pos_id	来源页位置 id
ext	额外信息，JSON String

上报时机

在任何上报中含有 goods_id 字段时，即产生 session 上报。

产生 session 上报的重要来源有：

• 商详页 PV
• 结算页 PV
• 生成订单
• 商品曝光

mt 上报

业务迭代过程中，为了减少清洗数据带来的人力和资源成本，所以增加了字段含义更为抽象的 mt 上报。

上报规则

字段	含义
xtype	类型，值为 mt
xaction	描述具体行为
xaction2	更细化的行为描述
xext1	通用字段，视具体上报内容而定
...	...
xext10	通用字段，视具体上报内容而定

mt 上报中，ext1 到 ext10 这 10 个字段都是根据具体上报定其含义。

这带来的好处是清洗一次表后，任何上报都可以在 mt 上报中得到表达。不便之处是具体上报中 ext 字段含义需要对照文档进行识别。

辅助工具

萌推 APP 在测试版 APP 中增加了一些辅助工具帮助数分及其他同学可以方便查看上报信息。

首页是下载测试版 APP，

下载地址：

• 安卓 https://www.pgyer.com/mengtui_android
• IOS https://www.pgyer.com/mengtui_iOS

iOS 版本的安装需要在 plist 中增加手机设备识别号，需要联系 杰伦、女巫 进行步骤指导和安装

安装完成后需要设置一下 APP，

进入 我的 - 设置

安卓步骤：

进入 调试工程模式 切换环境 正式环境 开启 H5 DEBUG 模式 开启 强制关闭HTML本地资源包映射 点击顶部 保存重启

如提示 “当前环境，无需切换”，可以手动杀死 APP，再次打开生效

iOS 步骤：

进入 Debug 切换环境 线上环境 开启 是否强制使用远程资源包 开启 是否使用H5Debug 点击顶部 立即生效

如点击 立即生效 无反馈，可以手动杀死 APP，再次打开生效

上报内容查看工具

设置完成后，进入 H5 页面会发现右上角多了一个 toggle 按钮，表示已经生效。

点击 toggle 按钮可以切换可视化数据显示/隐藏。

一般的 PV 信息和曝光信息会在页面上直观呈现。

商品信息查看工具

设置完成后，H5 页面的右下角会多一个绿色的原型按钮。通过该按钮，可以直接查看商品数据。

具体操作是，先点击按钮，按钮此时会变成红色，表示进入选区模式。

在选区模式时，手指滑动屏幕，会出现一个选区。将选区选定一个商品名称，此时会出现一个遮罩层，展示出该商品相关的原始数据。

附录

文档

埋点规则：http://km.innotechx.com/pages/viewpage.action?pageId=34799684 page name 一览：http://km.innotechx.com/pages/viewpage.action?pageId=76903202 mt 上报一览：http://km.innotechx.com/pages/viewpage.action?pageId=72857273 session 上报规则：http://km.innotechx.com/pages/viewpage.action?pageId=69748056 pos_id/res_id 规则及一览：http://km.innotechx.com/pages/viewpage.action?pageId=40140937 字段解释：http://km.innotechx.com/pages/viewpage.action?pageId=69731721 APP 采集上报文档：http://km.innotechx.com/pages/viewpage.action?pageId=82251637

数据查询工具

QE 平台：http://dataplatform.qutoutiao.net/qe_vue/#/search

Thanks