323a720b
 tangwang
docs
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
|
# UA 站内全站埋点数据结构定义（推荐/搜索/画像统一口径）
本文档用于定义站内全量行为采集（基于“全站埋点采集”，可落地到神策 JS SDK 二次开发），覆盖推荐、搜索、画像、转化分析等核心场景。
## 1. 目标与约束
- **目标**：用一套统一事件模型覆盖全站行为（Pageview / Exposure / Click / View Product / Add to Cart / Purchase / Search&Filtering / Cart&Checkout）。
- **约束**：事件需要能在“推荐/搜索请求”与“曝光-点击-加购”等链路上串联；同时需要能表达购物车/结账阶段的状态快照，用于搭配、互补、凑单、替代品推荐。
## 2. 关键设计原则
- **统一事件骨架**：所有事件共享同一套顶层字段（用户标识、时间、页面、trace、设备、扩展字段），业务差异放到 `event`（oneof）里。
- **可串联**：用 `trace_id` 串联一次搜索/推荐请求与后续点击、加购、详情浏览等行为；用 `session_id` 串联同一次访问会话。
- **可回放/可训练**：曝光事件尽量携带曝光商品列表、位置、模块；购物车/结账事件携带快照（items + 国家/币种/价格等）。
- **停留时长口径一致**：对 `page_view`/`view_item` 统一给出 `dwell_time_ms` 的采集口径与上报方式。
## 3. 顶层事件模型（概念）
每条 UA 事件为一个 `UserActionEvent`，包含：
- **identity**：tenant / user / anonymous / device / cookie
- **time**：事件发生时间（毫秒时间戳）
- **page**：页面类型、URL、来源、模块位置信息
- **trace**：`trace_id`、`session_id`、实验信息
- **device**：OS / UA / viewport 等
- **event**：具体业务事件（page_view、exposure、click、view_item、search、filter、cart、checkout、purchase…）
- **extra**：业务扩展 KV
> proto 草案见 `docs/proto/user_action.proto`（本次补充文件）。
## 4. 核心字段说明
### 4.1 标识体系（强烈建议）
- **tenant_id**：租户/店铺/商家维度的隔离主键。
- **user_id**：登录用户 ID（未登录可为空）。
- **anonymous_id**：匿名用户 ID（建议 Cookie 级别稳定，登录后可与 user_id 做归因合并）。
- **device_id**：设备指纹（可选；Web 端更推荐 anonymous_id + cookie_id）。
- **cookie_id**：首次访问生成的持久化 Cookie ID（与 anonymous_id 可以一致，也可分开）。
### 4.2 trace_id（最重要）
**定义**：串联一次“搜索/推荐请求（曝光）”与后续点击、详情、加购等行为的请求级会话 ID，同时用于串联内部技术模块（召回/排序/重排等子模块日志）。
**规则建议**：
- **新搜索/新推荐刷新**：生成新的 `trace_id`。
- **搜索翻页**：沿用原 `trace_id`，用 `page_number` 区分页（见 `SearchEvent`）。
- **曝光 → 点击/详情/加购**：沿用产生曝光的 `trace_id`，用于表达“该转化源自哪一次曝光/哪一次请求”。
- **购买/支付**：如果链路被购物车长时间阻隔，串联成本高，可不强制要求延续 `trace_id`；但建议在 `PurchaseEvent.attribution_trace_id` 上尽力保留“主要来源”的 trace（若可得）。
### 4.3 停留时长（dwell_time_ms）
**适用事件**：
- `PageViewEvent`：用户在该页面的停留时长
- `ViewItemEvent`：用户在详情页/商品内容上的停留时长（可与 pageview 相同，也可更精细）
**采集口径建议（Web）**：
- 在 `pagehide` / `beforeunload` / SPA 路由切换时计算当前页面停留：`now - enter_time`。
- 若页面进入后立即产生 `page_view`，则可在离开页面时补发一条 `page_view_end`（或在同一条事件里填充 `dwell_time_ms`，需要延迟上报）。
- 对详情页：可按“进入详情页到离开详情页”计算；若停留时长无法计算，允许不上报或置 0，但需要在文档/ETL 中区分“缺失 vs 真实 0”。
## 5. 必须覆盖的事件清单（推荐）
- **Pageview**
- 分类页、活动页、列表页、首页、店铺页、购物车页、结账页等
- *最好携带该页面曝光的商品列表*（见 `ExposureEvent`，或在 `PageViewEvent.exposed_items` 携带“本页首屏/本次渲染”曝光）
- **Exposure / Click**
- 列表/推荐位曝光与点击（必须包含 position / module_id / item）
- **View product（详情页浏览）**
- 包含 `dwell_time_ms`
- **Add to cart**
- 商品信息 + 数量 + 价格（若可得）+ 当前 cart 快照（若可得）
- **Purchase**
- 订单信息（order_id / currency / total）+ 购买 items
- **On-site Search & Filtering**
- 搜索词、建议词、排序、筛选条件（结构化，避免仅 JSON 字符串）
- 搜索结果曝光/点击建议归入 Exposure/Click，但必须携带 `search_context`
- **Cart Logic / Checkout 状态**
- `cart_snapshot`：购物车当前 items 及属性（qty、price、category、brand…）
- `checkout`：shipping_country、step、payment_method（如可得）
## 6. 落地建议（神策 JS SDK 二次开发）
- **事件名**：建议统一用一个事件名（如 `ua_event`），将 `action_type`（主类型）+ `event_id`（子类型，可选）作为属性；或按神策习惯拆分事件名，但必须保证字段一致。
- **批量上报**：曝光事件可批量（一屏/一次渲染一次上报）以降低量级；点击/加购/购买等强转化事件单条实时上报。
- **字段扩展**：放入 `extra.debug_info`，严禁在顶层无限加字段造成版本失控。
## 7. proto 草案
见 `docs/proto/user_action.proto`。
### 7.1 枚举命名说明（避免 proto 枚举值冲突）
为兼容较旧版本 `protoc`（枚举值采用 package 级作用域），本 proto 中枚举值都带前缀：
- **ActionType**：`ACTION_TYPE_*`（如 `ACTION_TYPE_PAGEVIEW`）
- **EventId**：`EVENT_ID_*`（如 `EVENT_ID_ADD_TO_CART`）
- **PageType**：`PAGE_TYPE_*`
- **SortType**：`SORT_TYPE_*`
- **CheckoutStep**：`CHECKOUT_STEP_*`
|