2023-02-16：最新打点文档

2021-12-24

[toc]

文件版本	修改人	修改内容	修改时间
V1	张丹峰	文档初步拟定	2020-04-15
V2	张丹峰	文档修改，仿ga	2020-04-23
		分为pageview, event, timing, item和transaciton
V3	张丹峰	增加4.1, 4.2, timing计时规范	2020-06-05
V3.1	张丹峰	增加货币编码附录, cu字段	2020-09-28
V3.2	张丹峰	修改歧义部分，msg需要穿string类型	2021-04-06

规范声明：

1，event事件ec, el, ea是用来区分数据的，均为产品约定好的数据，不可传用户自定义的内容，比如搜索内容，用户输入内容等。
2，如1中，长度需要限定，长度不可超过100个字符，
3，如果有类似用户输入内容，可以联系bool.zhang通过确定key值后写入打了msg业务字段
4，任何打点字段内的信息只能包含一个维度，不可把多个维度的数据通过拼接的方式存入到一个字段内，如：grid-1588_0，auto_image_shopmore-1516_0。如果确实需要，比如说想把所有大品类下的小品类用大品类表示，请用数据字典。
5，任何el都必须人为指定，且有上限。比如screen可以一直滚动， el不可直接定义为滚动的第n页面
6，不可打入无意义内容：如：

其他数据：参考excel

0, 注意声明

默认情况下，所以字段一律使用小写
不可使用带有空格的属性名和属性值，如果特殊需要，请使用“_”取代空格, 如“top_bar_notification”
所有数据中不可携带制表符换行符等，"\t", "\n", "\r", "\01", 如有特殊，请先沟通
url中不可携带emoji等表情符，字符一律使用utf-8
发送时异步发送，避免影响页面加载或者响应速度
同一批次最少传输一个具体事件，最多传输30个事件，不符合要求的会传输失败
字符串类型，请避免‘-1’直接作为属性值传入，-1将作为null的默认符号

注意⚠️：msg字段需要字符串类型数据，需要先把对象转为字符串！

1, 通用字段解释

如下字段为通用字段，任何事件均需要传递如下字段, 建议定义一个通用方法获取下面的属性进行赋值

字段	是否必填	类型	参数含义	备注	ga对应
pl	true	int	product_line,产品线	1代表azazie，2代表blushmark，3代表ppmianliao，4代表sisdress, 5 dolmi, 6, acrosposa	tid
p	true	int	platform,平台	1代表pc, 2代表mweb, 3代表ios， 4代表android	ds
c	false	string	国家标识	US，CA, CN，这里和cf保持一致，由数据搜集方直接从CF服务中获取,
fd	true	string	站点	具体见下面from_domain配置表, 如果有问题可以联系我更改，请勿随意填写

cid	true	string	client_id,设备唯一标识	每台设备必须唯一, app有的，网站需自行生成	cid
im	false	string	device_imei	移动端设备的device_imei
ia	false	string	idfa	移动端设备的idfa
uid	false	string	user_id,用户id	数据库中的用户id, 如果用户登陆则需要提交	uid
ip	false	string	ip,ip地址	真实的ip地址，该字段可不传，由数据搜集方从cf中获取	uip
sid	true	string	session_id	session定义: 不活动30分失效, 移动端需自行生成

cv	false	string	client_version,客户端版本号，代码的版本号	由客户端定义，规则需要统一，规则不可随意更改，如不传则后续无法分析版本

nw	true	string	⚠️：对于a站而言，这里改为语言， network,网络模式	⚠️：对于a站：是语言：en, es等 wifi, wwan
sr	false	string	screen_size,屏幕分辨率	800x600
md	false	string	model	model, 移动端填写手机模型iphone 6s
ov	false	string	operating system, 系统版本	手机填写手机系统版本，网站填写浏览器版本
ua	true	string	userAgent	移动端请模拟出对应信息(如不知道，可咨询海哥)	ua

am	false	string	app_market,下载的市场, 网站无需填写	比如appStore
dws	false	string	source,下载source	pc端可不填写，移动端选填，如果有的话请务必传
dwc	false	string	channel, 下载channel	pc端可不填写，移动端选填，如果有的话请务必传
dwm	false	string	medium,下载medium	pc端可不填写，移动端选填，如果有的话请务必传
opc	true	string	channel, 打开channel	打开渠道，必填
ops	true	string	source,打开source	打开source，必填
opm	true	string	medium,打开medium	打开medium，必填
acp	false	string	广告的ad_campaign	广告的大类
agp	false	string	广告的ad_group	广告的小类
ait	false	string	广告的ad_item	具体的广告
ant	false	string	广告的ad_content	广告的自定义字段


dh	true	string	host部分, 例如：foo.com，注意这里不写http://www	移动端填本字段同from_domain保持一致
dp	true	string	网页网址的路径部分, 例如：/home	如果是网站，可以是完整的路径部分
dt	true	string	文档标题	该url需要和20200430-final-页面及其对应的标识.xlsx 中的url保持一直方便后续进行映射

ct	true	long	clint-time,客户端发送数据的时间	1506047606608, 时间戳即可
st	false	long	server_time, 这个由数据接受方添加	1506047606608, 时间戳即可


pageviews	false	json数组	网页跟踪事件	当批量传递pageview事件时候必传
events	false	json数组	事件跟踪事件	当批量传递events事件时候必传
timings	false	json数组	用户计时跟踪事件	当批量传递timings事件时候必传
transactions	false	json数组	交易匹配事件	当批量传递transactions事件时候必传
items	false	json数组	商品匹配事件	当批量传递items事件时候必传


sign	true	string	签名	具体参考附录签名规则

2, 网页跟踪: pageview事件

字段	类型	是否必填	参数含义	备注	ga
msg	string	false	业务数据(注意类型为字符串)	请勿过度依赖这个字段，该字段只做补充参考，后续分析可能有限	如需传，提前沟通
lgt	long	true	time,日志事件	1506047606608, 时间戳即可

param1	string	false	拓展字段1	完整url	填写完整的url
param2	string	false	拓展字段2	a/b(a代表是a测试， b代表是b测试。暂不接受其他数据，如需更改请沟通)	AB测试字段
param3	string	false	拓展字段3	上一个页面(渠道统计的时候统计前一个页面)
param4	string	false	拓展字段4	语言
param5	string	false	拓展字段5	货币
param6	string	false	拓展字段6	b站：siteid(站点id) ｜ a站：extended_wgd_landed	yes, 拓展落地页
param7	string	false	拓展字段7	WGDLanded	yes, 落地页
param8	string	false	拓展字段8	WGDSource	wgdcpc/wgdfb
					wgdcpc,wgdfb

3, 事件跟踪: event事件

# 新增打点事件需要先联系开发者确认，确定无误后更新到文档中之后可以写入

字段	类型	是否必填	参数含义	备注	ga
ec	string	true	ec=top_bar_notification，这里指组件的唯一名称	不同打点的ec后续会补充在附录中
ea	string	true	ea=click，指定事件操作, 目前值有：click, view
el	string	false	el=‘’“，指定事件标签，暂时无
ev	int	false	ev=1，指定事件价，暂时无

msg	string	false	业务数据(注意类型为字符串)	请勿过度依赖这个字段，该字段只做补充参考，后续分析可能有限	如需传，提前沟通
lgt	true	long	1506047606608, 时间戳即可


param1	string	false	拓展字段1	完整url	填写完整的url
param2	string	false	拓展字段2	a/b(a代表是a测试， b代表是b测试。暂不接受其他数据，如需更改请沟通)	AB测试字段AB测试字段
param3	string	false	拓展字段3	上一个页面(渠道统计的时候统计前一个页面)
param4	string	false	拓展字段4	语言
param5	string	false	拓展字段5	货币
param6	string	false	拓展字段6	b站：siteid(站点id) ｜ a站：extended_wgd_landed	yes, 拓展落地页
param7	string	false	拓展字段7	WGDLanded
param8	string	false	拓展字段8	WGDSource

4, 用户计时跟踪: timing事件

# 新增打点事件需要先联系开发者确认，确定无误后更新到文档中之后可以写入

字段	类型	是否必填	参数含义	备注	ga
utc	string	true	user timing category, api/home_open/	具体见4.1, 4.2打点规范，需先添加在文档中
utv	string	true	user timing variable， url	具体见4.1, 4.2打点规范，需先添加在文档中
utl	string	false	user timing label	具体见4.1, 4.2打点规范，需先添加在文档中
utt	int	true	user timing time, 毫秒，具体时间	具体见4.1, 4.2打点规范，需先添加在文档中

msg	string	false	业务数据(注意类型为字符串)	请勿过度依赖这个字段，该字段只做补充参考，后续分析可能有限	如需传，提前沟通
lgt	true	long	日志时间	1506047606608, 时间戳即可

				* msg lp_type => cocktail_dresses
				url: http:// goods/
				/list?
param1	string	false	拓展字段1	完整url	填写完整的url
param2	string	false	拓展字段2	a/b(a代表是a测试， b代表是b测试。暂不接受其他数据，如需更改请沟通)	AB测试字段
param3	string	false	拓展字段3	上一个页面(渠道统计的时候统计前一个页面)
param4	string	false	拓展字段4	语言
param5	string	false	拓展字段5	货币
param6	string	false	拓展字段6	b站：siteid(站点id) ｜ a站：extended_wgd_landed	yes, 拓展落地页
param7	string	false	拓展字段7	WGDLanded
param8	string	false	拓展字段8	WGDSource

4.1,用户计时详细分类

utc	utv	utl	utt	msg	场景
api	url(api的具体url)	无	时长，单位毫秒	具体见下4.2表格	每次调用接口会记录下接口的响应时间
page	home_open	无	时长，单位毫秒	具体见下4.2表格	移动端首页无缓存下渲染时间
page	goods_list_open	无	时长，单位毫秒	具体见下4.2表格	列表页无缓存下渲染时间
page	goods_detail_open	无	时长，单位毫秒	具体见下4.2表格	详情页渲染时间(每次打开新的实例)
page	cart_open	无	时长，单位毫秒	具体见下4.2表格	购物车页面无缓存下渲染时间
page	checkout_open
img_load	image_path(暂定完整url)

4.2, msg对照表

# url
{}

# home_open
{}

# goods_list_open
{}

# goods_detail_open
{}

# cart_open
{}

5, 电子商务跟踪

电子商务跟踪包括交易匹配和商品匹配，一笔交易必须要同时提交一个交易匹配及多个商品匹配

5.1, 交易匹配: transaction事件

字段	类型	是否必填	参数含义	备注	ga
ti	long	true	id, 交易的唯一标识符, 可以填写order_id
tg	decimal	true	gmv，是成交总额, 订单实付金额(含运费)	order_info(order_amount)
tr	decimal	true	revenue, 交易相关联的总收入, 不包含所有运费或税费或者红包	order_info(goods_amount + bonus)
trs	decimal	true	rush加急费用
tb	decimal	true	bonus红包费用
tp	decimal	true	points费用
ts	decimal	true	shipping_fee, 交易的总运费
tt	decimal	true	tax, 交易的总税费
cu	string	true	currency, 交易币种	参考下面附录：`05, 货币编码(cu)`

msg	string	false	业务数据(注意：这里直接传字符串)	请勿过度依赖这个字段，该字段只做补充参考，后续分析可能有限	如需传，提前沟通
lgt	true	long	日志时间	1506047606608, 时间戳即可


param1	string	false	拓展字段1	完整url	填写完整的url
param2	string	false	拓展字段2	a/b(a代表是a测试， b代表是b测试。暂不接受其他数据，如需更改请沟通)	AB测试字段
param3	string	false	拓展字段3	上一个页面(渠道统计的时候统计前一个页面)
param4	string	false	拓展字段4	语言
param5	string	false	拓展字段5	货币
param6	string	false	拓展字段6	b站：siteid(站点id) ｜ a站：extended_wgd_landed	yes, 拓展落地页
param7	string	false	拓展字段7	WGDLanded
param8	string	false	拓展字段8	WGDSource

5.2, 商品匹配: item事件

字段	类型	是否必填	参数含义	备注	ga
ti	long	true	交易的唯一标识符, 可以填写order_id
in	string	true	name, 商品名称
ipr	decimal	true	price, 商品的单价
iq	long	true	quantity, 商品数量
isu	string	true	sku, 指定 SKU
igi	long	true	goods_id, 商品
ic	int	true	Category, cat_id
isi	int	false	style_id
cu	string	true	currency, 交易币种

msg	string	false	业务数据(注意类型为字符串)	请勿过度依赖这个字段，该字段只做补充参考，后续分析可能有限	如需传，提前沟通
lgt	true	long	日志时间	1506047606608, 时间戳即可

param1	string	false	拓展字段1
param2	string	false	拓展字段2	a/b(a代表是a测试， b代表是b测试。暂不接受其他数据，如需更改请沟通)	AB测试字段
param3	string	false	拓展字段3	上一个页面(渠道统计的时候统计前一个页面)
param4	string	false	拓展字段4	语言
param5	string	false	拓展字段5	货币
param6	string	false	拓展字段6	b站：siteid(站点id) ｜ a站：extended_wgd_landed	yes, 拓展落地页
param7	string	false	拓展字段7	WGDLanded
param8	string	false	拓展字段8	WGDSource

6, 请求方式

swagger接口定义：https://collect-test.azazie.cn/swagger-ui.html

# 生产(slave04, slave05)
https://collect.azazie.cn


https://collect.azazie.cn/api/v1/events


# 测试(1个实例)
https://collect-test.azazie.cn

请求密钥请联系数据搜集方获取

7, 签名方式

/**
 * 签名生成方法, 方法如下：
 
 * 1，把通用字段参数按照字典升序顺序排列(注意：不包含sign和具体事件参数的任何数据)
 
 * 2，然后拼接参数为name=Ivanl001&age=10&hobby=game形式，
 
 * 3，将所有大写转小写,然后拼接密钥:act=1&am=appstore&c=us&cv=v1.0.1&di=dfakfdafdaslfasdfasfdasfasdfdsa&entry=1&ip=10.0.0.1&ldt=1.22&lgt=1506047606608&nw=wifi&p=1&pl=1&sr=1080*960&secretkey=me02kunyfqcejqbdwlaf0ghs3j2r8wuu
 
 * 4，把待编码字符串进行base64编码:YWN0PTEmYW09YXBwc3RvcmUmYz11cyZjdj12MS4wLjEmZGk9ZGZha2ZkYWZkYXNsZmFzZGZhc2ZkYXNmYXNkZmRzYSZlbnRyeT0xJmlwPTEwLjAuMC4xJmxkdD0xLjIyJmxndD0xNTA2MDQ3NjA2NjA4Jm53PXdpZmkmcD0xJnBsPTEmc3I9MTA4MCo5NjAmc2VjcmV0a2V5PW1lMDJrdW55ZnFjZWpxYmR3bGFmMGdoczNqMnI4d3V1
 
 * 5，将base64编码后的字符串进行md5加密:c34b30f0f77b63ef80f1cc3b841b3a89
 */

//服务端加密源码参考：com.lebbay.common.utils.IMSignUtils

		//java代码参考

    //移除本身的sign字段
    String theSign = (String) map.remove("sign");

    //移除事件数据，这些不需要签名
    if (map.containsKey("pageviews")) {
      map.remove(COLLECT_PAGEVIEWS);
    } else if (map.containsKey(COLLECT_EVENT)) {
      map.remove(COLLECT_EVENT);
    } else if (map.containsKey(COLLECT_TIMINGS)) {
      map.remove(COLLECT_TIMINGS);
    } else if (map.containsKey(COLLECT_TRANSACTIONS)) {
      map.remove(COLLECT_TRANSACTIONS);
    } else if (map.containsKey(COLLECT_ITEMS)) {
      map.remove(COLLECT_ITEMS);
    }


    /**
     * 签名生成方法, 方法如下：
     * 1，先把参数按照字典升序顺序排列,
     * 2，然后拼接参数为name=Ivanl001&age=10&hobby=game形式，
     * 3，将所有大写转小写,然后拼接密钥:name=Ivanl001&age=10&hobby=game&secretkey=abcdefghijklmn
     * 4，把待编码字符串进行base64编码
     * 5，将base64编码后的字符串进行md5加密
     */
    public static String createSign(Map<String, Object> params, String secretkey){

        StringBuilder sb = new StringBuilder();

        /*
         * 1, 先把参数按照字典升序顺序排列
         */
        Map<String, Object> sortParams = new TreeMap<>(params);

        /*
         * 2, 遍历排序的字典,并拼接"key=value"格式
         */
        for (Map.Entry<String, Object> entry : sortParams.entrySet()) {
            String key = entry.getKey();
            String value =  entry.getValue().toString().trim();
            if (!StringUtils.isEmpty(value)) {
                sb.append("&").append(key).append("=").append(value);
            }
        }

        /*
         * 3, 将所有大写转小写
         */
        String stringToSign = sb.append("&secretkey=").append(secretkey).toString().replaceFirst("&","").toLowerCase();
        log.info("-----组装后转小写结果是:-----" + stringToSign);

        /*
         * 4, base64编码
         */
        String basedStringToSign = new String(Base64.getEncoder().encode(stringToSign.getBytes()));
        log.info("-----base64转码后结果:-----" + basedStringToSign);

        /*
         * 5, 将base64编码后的字符串进行md5加密
         */
        String sign = DigestUtils.md5Hex(basedStringToSign);
        log.info("-----md5加密后结果是:-----" + sign);

        /*
         * 返回结果
         */
        return sign;
    }

8, 附录

01, 国家编码

按照标准的编码规则，这里一律使用大写。
我这里列出最常用的三项，其他的简称见参考

取出字段从cloudflare中获取，具体可参考：

https://support.cloudflare.com/hc/zh-cn/articles/217074967#3WKsVX082tB32pFVMhVODw

“两字母国家/地区代码”

国家	简称
美国	US
加拿大	CA
中国	CN

02, from_domain

如新增了其他站点请及时联系文档提供者进行更新本文档

平台	站点	from_domain值
pc	美国的az的pc站	azazie.com
pc	加拿大的az的pc站	azazie.ca

mweb	美国az的m站	m.azazie.com
mweb	加拿大az的m站	m.azazie.ca

移动端	a站的android设备	az-andriod
移动端	a站的ios设备	az-ios

	b站的ios设备	bm-ios
	b站的android设备	bm-android

03, dh,dp,dt对应规则

全部内容参考：20200430-final-页面及其对应的标识.xlsx

完整数据请参考excel中，本表格只是一个大致的展示
https://docs.google.com/spreadsheets/d/1IOBrqz6eqqOPUkp_vSCygJfdHu2iVyiiGRSkBGC1MmY/edit#gid=1563099201

页面	dt值
首页	home
列表页	goods
详情页	detail
加车页	cart

付款页	checkout
付款成功页	checkout_success

订单列表页	order
订单详情页	order_detail

个人中心	account
登录注册页	login

其他页面参考：20200430-final-页面及其对应的标识.xlsx

04, channel, source, medium

注意⚠️：自定义渠道的时候，请务必把渠道长度限定在15个英文字符之内，请不要使用任何中文字符

具体内容参考：20200430-final-A站和B站渠道来源.xlsx

05, 货币编码(cu)

目前使用(如有其他货币，请联系)

中文名称	English_name	currency_code
美元	US Dollar	USD
加拿大元	Canada Dollar	CAD

end

zhangbool/01-埋点系统标准文档.md

2021-12-24

0, 注意声明

1, 通用字段解释

2, 网页跟踪: pageview事件

3, 事件跟踪: event事件

4, 用户计时跟踪: timing事件

4.1,用户计时详细分类

4.2, msg对照表

5, 电子商务跟踪

5.1, 交易匹配: transaction事件

5.2, 商品匹配: item事件

6, 请求方式

7, 签名方式

8, 附录

01, 国家编码

02, from_domain

03, dh,dp,dt对应规则

04, channel, source, medium

05, 货币编码(cu)

目前使用(如有其他货币，请联系)