· 更新于 2024-08-26
Architecture►第三章：基础规范

埋点规范

参考文档：

埋点作用

曝光率（曝光率= 点击量 / 曝光量）来分析用户（比如用户的喜好推荐数据的统计）

一、埋点入参

1、【固定的】公共入参

1.1、【固定的】的【基本】公共入参7个

建议和《基础规范-请求规范》 中的request公共入参保持一致

属性名 说明 备注
app_id App的唯一标识 com.ciyouzen.beyond
app_name App的应用名称 XXX测试版
app_version App的应用版本 1.16.30
app_buildNumber App的应用编译号 16301610
channel_name 渠道名称 【《请求规范》 中的request公共入参的渠道】
platform/lib SDK 类型 Android/iOS
account_id 用户唯一标识 用户没有登录时，客户端自动生成唯一标识

1.2、【固定的】的【设备及系统信息】公共入参

属性名 说明 备注
systemVersion/lib_version 操作系统版本 16.1.1
manufacturer 设备制造商
brand 设备品牌 iPhone
model 设备型号 iPhone
os 操作系统 iPhone13,3
os_version 操作系统版本
screen_width 屏幕宽度 390.0
screen_height 屏幕高度 844.0
screen_devicePixelRatio 设备像素比率 3.0
carrier SIM 卡的运营商名称
device_id 设备ID Android 端主要取 Android ID ，
iOS 端先尝试获取 IDFA，如果获取不到，则取 IDFV
geo_coordinate_system 坐标系：iOS 端默认为 WGS84, Android 端需要手动传入 bd09ll

1.3、【固定的】的【其他】公共入参

属性名 说明 备注
lib_method 埋点方式 固定值为code

2、【可变的】的Body入参

2.1、单记录Body：【可变的】的【基本】入参

属性名 说明 备注 是否可全局按需时时获取
network_type 网络类型
mobile / wifi / bluetooth / vpn / other		 mobile √
timezone App 或系统的时区
Duration timezoneOffset = DateTime.now().timeZoneOffset;		 Asia/Shanghai √
timezone_offset 时区偏移量（以分为单位）
int timezoneOffsetMinutes = timezoneOffset.inMinutes;		 480 √
latitude GPS信息-纬度 √
longitude GPS信息-经度 √
request_time 单条记录生成时间，精确到毫秒 批量时，多条应是同一个时间 √

2.2、单记录Body：【可变的】的【其他】入参

属性名 说明 备注
param 服务端下发 如算法标识等
event_name 事件名称 如“AppInstall”
event_attr 事件属性对象集合 event_name=”AppInstall”,event_attr={“accountId”:”1234”,”city”:”厦门”}

1、event_attr 希望的其他参数

属性名 说明 备注 是否可全局按需时时获取
cur_page 当前页面，用于标明 position/scene “goods_detail_page” 可全局记录旧页面
cur_view 当前视图，用于标明 position/scene “sku_choose_window” 必须请求单独设置
referrer_title 前一个页面标题

二、埋点事件

1、App事件

事件描述 事件名
冷启动 appStart
关闭应用 appEnd
返回前台/热启动 appResumed
进入后台 appPaused

1.1、打开/冷启动 appStart

参数 说明 示例
—- —-

1.2、关闭应用 appEnd

参数 说明 示例
—- —-

1.3、返回前台/热启动 appResumed

参数 说明 示例
—- —-

1.4、进入后台 appPaused

参数 说明 示例
duration 页面停留的时长(毫秒)

2、页面停留事件

事件描述 事件名
显示页面 viewDidAppear
离开页面 viewDidDisappear 
1
2
3
4
5
enum AppearBecause {
  newCreate, // 新显示
  pop, // 从其他界面pop回来的
  resume, // 从后台进入前台
}
1
2
3
4
5
enum DisAppearBecause {
  goNew, // 去新的页面
  pop, // 退出当前界面
  pause, // 从前台进入后台
}

2.1、原生页面停留

2.1.1、进入页面 viewDidAppear
参数 示例 其他
page 页面类名 Goods_detail_page
cause 进入的方式 newCreate / pop
2.1.2、离开页面 viewDidDisappear
参数 说明 示例
page 页面类名 Goods_detail_page
cause 离开的方式 goNew / pop
duration 页面停留的时长(毫秒)
2.1.3、页面/视图进入、离开的监控方案

页面/视图进入、离开的监控方案：ShowMonitorMethod，详见《埋点方案-页面和视图的进入和离开》

2.2、游戏页面停留

2.2.1、进入页面 viewDidAppear
参数 示例 其他
page 页面类名 WebViewPage
cause 进入的方式 newCreate / pop
url 网页地址
2.2.2、离开页面 viewDidDisappear
参数 说明 示例
page 页面类名 WebViewPage
cause 离开的方式 newCreate / pop
duration 页面停留的时长
url 网页地址

3、页面加载事件

事件描述 事件名
页面加载开始 firstStart
页面首帧绘制结束 firstAppFrameEnd
页面首屏绘制结束
(取到数据即算，不论是后台还是网络)		 firstUserScreenEnd
页面首屏绘制结束
(以相关请求的最后一个为结束为结束)		 firstNetworkScreenEnd

3.1、页面加载开始 firstStart

参数 示例 其他
page 页面类名 GoodsDetailPage

3.2、页面首屏绘制结束 firstNetworkScreenEnd

参数 说明 示例
page 页面类名 GoodsDetailPage
requestCount 请求的网络个数 3
duration 页面加载的时长(毫秒)

4、点击与曝光事件(非页面)

描述 点击事件名 曝光事件名 属性示例
商品 click_goods exposure_goods {“id”: id, “sku_id”: sku_id}
用户 click_user exposure_user {
“userId”: userId,
“userType”: avatar/name/other
}
订单 click_order exposure_order {“id”: id}
卡片 click_card exposure_card {
“cardId”: cardId,
“cardType”: user/goods/banner,
“cardOwnerId”: cardOwnerId
}
tab(一个页面多tab) click_tab 无
(使用该tab的视图曝光)		 {“tab_name”: tab_name}
照片切换 click_photo_change 无(不需要) {“count”: 3, “old_index”: 0, “cur_index”: 2}
照片浏览 click_photo_browse 无(不需要) {count”: 3, “index”: 0}

4.1、卡片参数

参数 说明 示例
cardPosition/cardScene 卡片位置/场景
cardType 卡片类型(banner、user、goods)
cardId 卡片id
cardOwnerId 卡片持有者id（可空）

三、埋点数据不准的修复

1、启动app的人数

序号 方案 结果
1 通过appStart计算启动app的人数 不准确❌
2 通过登录后必进入的接口请求 准确✅
3

方案1：通过appStart计算启动app的人数，结果不准确

原因说明：

appStart 用户为冷启动（杀掉再进）
当用户未登录：有appStart，但没userId。
进行登录后，有首页的访问记录，但是appStart已上报过。

所以，首页的访问记录 >= appStart(99.99999%是大于)

其他：
userId登录时候，未登录无；deviceId：登录和未登录都有

2、页面的停留时长

页面的停留时长不应该只以系统didAppear和disAppear为判断依据。

还要扣除页面进入后台的时间。

解决：

进入后台的时候，触发消失的埋点；进入前台的时候触发显示的埋点。

相当于，如果用户 进入页面 – 退到后台 – 返回前台 – 离开页面

会等价于：显示 – 消失 – 显示 – 消失 。两次记录。而不是只有 进入页面– 离开页面的一次记录。

3、未显示的tab页面，也有使用时长

4、后台筛选出的数据不准确

可能原因：

4.1、未区分版本

可能旧版本有问题，新版本上修复后，筛选的数据要以新版本为主。

举例：

4.2、会区分时间段

比如：计算页面的在某一天的时候时长。

实际举例：用户从昨天22:59开始进入app或者一直在app内的某个页面，直到第二天的23:59才退出。

则app获取到的数据是，用户使用了25个小时的应用。

如果计算当天，实际上，只用了23小时59分钟。

为方便后台计算该次记录的初始显示时间，客户端在消失的埋点里添加显示的时间。

四、埋点的数据上报

将监听到的数据添加到 final List<Map<String, dynamic>> _buriedPointModels = []; 中

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
	_init() {
 // print('BuriedPointManager _init');
		/// 每5秒上传一次，避免请求太多
 _uploadTimer = Timer.periodic(const Duration(milliseconds: 5000), (timer) {
   _uploadBuriedPoints();
 });
}

addEvent(String eventName, Map<String, dynamic> eventAttr) async {
 Map<String, dynamic> eventMap = {};

 eventMap.addAll({
   "event_name": eventName,
   "event_attr": eventAttr,
   "request_time": DateTime.now().millisecondsSinceEpoch, // 单条记录生成时间，精确到毫秒
 });

 _buriedPointModels.add(eventMap);
}

五、曝光

曝光（曝光结束才计算曝光。曝光过程不计算，那初始曝光的怎么办）

当然我们对滑动曝光有一些额外的要求：

  • 需要滑出一定比例(只出现一点点不算)、一定时间(太快划走不算)的时候才出发曝光
  • 滑出视野的模块，再次滑入视野时需要再次上报
  • 模块在视野中上下反复移动只触发一次曝光（还未实现）

六、全埋点

参考文章：

1、点击自动埋点 autoTrackClick

参数 示例 其他
path 按钮路径
content 按钮上的文本，如果存在
screentName 当前页面名，同于page，却值不同

七、埋点页面名

1、一级页

页面描述 页面类名 页面埋点名
主页
作品首页 WishHomePage WishHomePage
商城首页 MallHomePage MallHomePage
发布页面
消息首页
我的首页

1.1、一级页中的标签页

页面描述 页面类名 页面埋点名
作品–推荐
作品–同城 WishDiscoverNearby WishDiscoverNearby
作品–热单 WishDiscoverHot WishDiscoverHot
作品–关注 WishDiscoverFriend WishDiscoverFriend

2、二级页

2.1、作品相关

页面描述 页面类名 页面埋点名
作品–推荐–推荐用户
作品–同城–
作品–热单–获豆榜 RankBeanWidget RankBeanWidget
作品–热单–愿望榜 RankWishWidget RankWishWidget
作品–关注–关注/粉丝/互关
作品详情页

2.2、商品相关

页面描述 页面类名 页面埋点名
商品详情页 GoodsTaDetailPage GoodsTaDetailPage

2.3、发布相关

页面描述 页面类名 页面埋点名
添加商品页

2.4、消息相关

页面描述 页面类名 页面埋点名
消息–收到的打赏 MsgCostPage MsgCostPage
消息–实现的愿望 MsgWishPage MsgWishPage
消息–新增的关注 MsgFocusPage MsgFocusPage
消息–互动消息–收到的评论 MsgCommentPage MsgCommentPage
消息–互动消息–发表的评论 InteractiveMessageListPage InteractiveMessageListPage
消息–互动消息–赞过的评论 InteractiveMessageListPage InteractiveMessageListPage
消息–系统消息
消息–聊天页面

2.5、我的相关

页面描述 页面类名 页面埋点名
我的–关注 MyFriendsPage MyFriendsPage
我的–粉丝 MyRelationPage MyRelationPage
我的–愿望豆 StarHistoryPage StarHistoryPage
我的–我的农场
我的–我的订单 MyOrderMainPage MyOrderMainPage
我的–我的足迹 RecordPage RecordPage
我的–我的收藏 CollectPage CollectPage

3、其他

页面描述 页面类名 页面埋点名
意见反馈 FeedbackPage FeedbackPage
平台客服 APPIMChat APPIMChat

End