1.1.2-alpha.0 • Published 2 months ago
@fle-sdk/event-tracking-web v1.1.2-alpha.0
构建用户数据体系,让用户行为数据发挥深远的价值。
前言
WEB数据埋点sdk,开始之前请确保了解埋点的架构和基础知识
埋点中比较重要的组成部分就是每个事件的 key,注意的是 key 至少由两部分组成。 完整的 key 由这几部分组成:appkey.pagekey.partkey 通过“.”来分割
- appkey:APP应用唯一标识
- pagekey:页面唯一标识,默认取当前路由
- partkey:控件/自定义事件唯一标识,可通过接口获取或自定义
一、下载
// npm
npm install @fle-sdk/event-tracking-web --save-dev
// yarn
yarn add @fle-sdk/event-tracking-web
二、全埋点
全埋点包括三种事件:Web 页面浏览、Web 元素点击、Web 页面留存时长,对应的配置如下:
// 初始化
WebTracking.init({
appKey: "218844",
showLog: true,
autoTrack: true, // 设置该属性之后,SDK 就会自动收集页面浏览事件
isTrackSinglePage: true,
contentType: "application/json",
serverUrl: "https://xxx/push",
});
2.1 元素点击
元素的点击事件上报 attr 属性中必须含有 data-part-key ,否则会被过滤。
// 对充值按钮的点击次数进行统计
<button data-part-key="recharge_btn" data-desc="显示充值弹窗">
充值
</button>
2.2 全埋点参数示例
全埋点三种类型的上报参数示例,建议都了解一下
{
"desc": "Web 浏览页面",
"event": "PageView",
"itemKey": "218844.app_other",
"requestTime": 1709524231171,
"deviceId": "1dd539cdea9332ebb9d5c087f9d4471f",
"privateParamMap": {
"currentUrl": "http://localhost:9999/app/other",
"targetUrl": null,
"pageWidth": 414,
"pageHeight": 672,
"screenWidth": 414,
"screenHeight": 672,
"sdkVersion": "1.1.0",
"systemsInfo": {
"language": "zh-CN",
"client": "iPhone, iOS 11.0, WeChat 8.0.5",
"platform": "h5",
"ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 11_0 like Mac OS X) AppleWebKit/604.1.38 (KHTML, like Gecko) Version/11.0 Mobile/15A372 Safari/604.1 wechatdevtools/1.06.2310080 MicroMessenger/8.0.5 Language/zh_CN webview/17095233761068527 webdebugger port/25477 token/e60c2e75ed74647fb2c0d949c0a31774"
},
"urlParams": {},
"userInfo": {
"userId": 20211232232123,
"userName": "asheng"
},
"business": {
"appId": "1000010"
}
}
}
{
"desc": "Web 元素点击",
"event": "WebClick",
"itemKey": "218844.main.h1",
"requestTime": 1709524472904,
"deviceId": "1dd539cdea9332ebb9d5c087f9d4471f",
"privateParamMap": {
"targetEle": {
"id": "",
"nodeName": "H1",
"className": "",
"position": [
66,
108
]
},
"pointerType": "",
"currentUrl": "http://localhost:9999/main?a=1",
"elementSelector": "#root > div:nth-of-type(1) > div:nth-of-type(1) > h1:nth-of-type(1)",
"pageWidth": 414,
"pageHeight": 672,
"screenWidth": 414,
"screenHeight": 672,
"sdkVersion": "1.1.0",
"systemsInfo": {
"language": "zh-CN",
"client": "iPhone, iOS 11.0, WeChat 8.0.5",
"platform": "h5",
"ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 11_0 like Mac OS X) AppleWebKit/604.1.38 (KHTML, like Gecko) Version/11.0 Mobile/15A372 Safari/604.1 wechatdevtools/1.06.2310080 MicroMessenger/8.0.5 Language/zh_CN webview/17095233761068527 webdebugger port/25477 token/e60c2e75ed74647fb2c0d949c0a31774"
},
"urlParams": {
"a": "1"
},
"userInfo": {
"userId": 20211232232123,
"userName": "asheng"
},
"business": {
"appId": "1000010"
}
}
}
{
"desc": "Web 页面浏览时长",
"event": "PageRetained",
"itemKey": "218844.main",
"requestTime": 1709524334413,
"deviceId": "1dd539cdea9332ebb9d5c087f9d4471f",
"privateParamMap": {
"pageWidth": 414,
"pageHeight": 672,
"screenWidth": 414,
"screenHeight": 672,
"sdkVersion": "1.1.0",
"systemsInfo": {
"language": "zh-CN",
"client": "iPhone, iOS 11.0, WeChat 8.0.5",
"platform": "h5",
"ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 11_0 like Mac OS X) AppleWebKit/604.1.38 (KHTML, like Gecko) Version/11.0 Mobile/15A372 Safari/604.1 wechatdevtools/1.06.2310080 MicroMessenger/8.0.5 Language/zh_CN webview/17095233761068527 webdebugger port/25477 token/e60c2e75ed74647fb2c0d949c0a31774"
},
"urlParams": {
"a": "1"
},
"userInfo": {
"userId": 20211232232123,
"userName": "asheng"
},
"currentUrl": "http://localhost:9999/main?a=1",
"business": {
"appId": "1000010"
},
"retainedDuration": 103243
}
}
三、API
WebTracking
- init() ---初始化
- preset() ---配置全局参数(注意:如果配置的全局属性初始化已配置,将覆盖。)
- login() ---用户登录
- track() ---自定义代码埋点上报
- getDeviceId() ---获取设备唯一标识
Init
参数
参数名 | type | 描述 | 是否必填 | 默认值 |
---|---|---|---|---|
appKey | string | 应用唯一标识(由接口生成) | 是 | - |
serverUrl | string | 数据接收地址 | 是 | - |
autoTrack | boolean | 是否开启全埋点(指的是:页面浏览、元素点击事件自动上报) | 否 | false |
showLog | boolean | 是否在网页控制台打印发送的数据 | 否 | false |
sendTimeout | number | 接口发送超时时长,超过该时长未发送成功将强制取消 | 否 | 3000 |
isTrackSinglePage | boolean | 是否采集单页面应用的路由变化 | 否 | false |
contentType | string | application/json | ||
application/x-www-form-urlencoded | 否 | application/x-www-form-urlencoded | ||
business | {key: string: any} | 全局自定义业务参数(如果后续手动上报了业务字段,会进行合并) | 否 | - |
platform | string | 手动指定应用平台类型 | 否 | - |
例子
初始化 sdk 例子,建议在 src/App.js 中初始化,且需在useLayoutEffect中初始化。
import React, { useLayoutEffect } from "react";
import WebTracking from "@fle-sdk/event-tracking-web";
const App = () => {
useLayoutEffect(() => {
// 初始化埋点
WebTracking.init({
appKey: "218844",
showLog: true,
autoTrack: true,
platform: 'h5',
isTrackSinglePage: true,
serverUrl: "https://qa-gateway.fxqifu.net/pangu/buriedpoint/record/push",
business: {
appId: "1000010",
}
});
}, []);
return <div className="App"></div>;
};
export default App;
Preset
除了不可配置appKey、serverUrl,本质上和init差不多,这么做是为了更好的区分使用场景,不产生歧义。
参数
参数名 | type | 描述 | 是否必填 | 默认值 |
---|---|---|---|---|
autoTrack | boolean | 是否开启全埋点(指的是:页面浏览、元素点击事件自动上报) | 否 | false |
showLog | boolean | 是否在网页控制台打印发送的数据 | 否 | false |
sendTimeout | number | 接口发送超时时长,超过该时长未发送成功将强制取消 | 否 | 3000 |
isTrackSinglePage | boolean | 是否采集单页面应用的路由变化 | 否 | false |
contentType | string | application/json | ||
application/x-www-form-urlencoded | 否 | application/x-www-form-urlencoded | ||
business | {key: string: any} | 手动埋点参数 | 否 | {} |
platform | string | 手动指定应用平台类型 | 否 | - |
例子
import React, { useLayoutEffect } from "react";
import WebTracking from "@fle-sdk/event-tracking-web";
const App = () => {
useLayoutEffect(() => {
// init tracking
WebTracking.init({
appKey: "xxxxxx", // 由接口生成,应用唯一标识
serverUrl: "https://www.serverHost.com/serverApi/push",
});
// 配置全局参数,初始化后预置属性用该方法。
// 注意:如果配置的全局属性初始化已配置,将覆盖
WebTracking.preset({
autoTrack: true,
showLog: true,
isTrackSinglePage: true,
sendTimeout: 10000
})
}, []);
const pageHandle = () => {
WebTracking.preset({
autoTrack: false, // 关闭全埋点
})
}
return <div className="App" onClick={pageHandle}></div>;
};
export default App;
Login
参数
参数名 | type | 描述 | 是否必填 | 默认值 |
---|---|---|---|---|
params | {key: string: any} | 用户信息 | 是 | - |
例子
import React, { useEffect } from "react";
import WebTracking from "@fle-sdk/event-tracking-web";
import { LoginStore } from "store";
const Test = () => {
const getUserInfo = () => {
const userInfo = await LoginStore.getUserInfo();
WebTracking.Login(userInfo);
}
useEffect(() => {
getUserInfo()
}, []);
return <div className="Test"></div>;
};
export default Test;
GetDistinctId
例子
获取设备唯一标识,当用户没有登录时即用户唯一标识
import React, { useEffect } from "react";
import WebTracking from "@fle-sdk/event-tracking-web";
import { LoginStore } from "store";
const Test = () => {
useEffect(() => {
WebTracking.getDistinctId();
}, []);
return <div className="Test"></div>;
};
export default Test;
Track
手动代码埋点上报
上报参数
参数名 | type | 描述 | 是否必填 | 默认值 |
---|---|---|---|---|
partkey | numberstring | 上报事件 Key(由前后端协商定义或由后端接口生成,该应用下需唯一且具有一定意义,例:goods_detail_pv) | 是 | - |
desc | string | 上报事件描述 | 否 | 自定义上报事件 |
business | {key: string: any} | 上报的业务参数 | 否 | - |
例子
import React, { useEffect } from "react";
import WebTracking from "@fle-sdk/event-tracking-web";
const Index = () => {
const history = useHistory();
const tracking = () => {
WebTracking.track({ desc: "我是描述", partkey: "xxx" })
.then((res) => console.log(res || "上报成功!"))
.catch((err) => console.log(err || "上报失败!"));
}
// 手动上报商品详情浏览量示例
useEffect(() => {
WebTracking.track({
desc: "商品详情PV埋点",
partkey: "goods_detail_pv",
business: {
goodsId: "123",
goodsName: "测试商品",
},
});
}, []);
return (
<div className="index-wrap">
<button onClick={tracking}>点我,自动上报</button>
</div>
);
};
export default Index;
四、完整参数明细
4.1 request参数明细
参数名 | type | 描述 | 示例值 |
---|---|---|---|
event | string | 有四种类型的值: | |
PageViewPageRetainedCustomTrackWebClick | - | ||
desc | string | 埋点事件描述 | - |
itemKey | string | 当前埋点事件Key | appkey.pagekey.partkey |
requestTime | number | 发送请求事件 | - |
privateParamMap | object | 私有参数 | 查看详情 |
deviceId | string | 设备ID | 9ce0159574b00867c7d2c5b200bd2f60 |
4.2.1 privateParamMap参数明细
参数名 | type | 描述 | 示例值 |
---|---|---|---|
currentUrl | string | 当前URL | http://localhost:9999/main |
targetUrl | string | 目标URL | http://localhost:9999/app/other |
business | {key: string: any} | 手动埋点参数 | - |
targetEle | TargetEleProps | 触发元素属性 | 查看详情 |
pageWidth | number | 页面可视区宽度 | 1440 |
pageHeight | number | 页面可视区高度 | 860 |
screenWidth | number | 显示屏宽度 | 1440 |
screenHeight | number | 显示屏高度 | 860 |
pointerType | string | 手动触发的指针类型 | mouse、touch、pen |
elementSelector | string | 触发元素链路 | #root > div:nth-of-type(1) > div:nth-of-type(1) > h1:nth-of-type(1) |
userInfo | {key: string: any} | 用户信息 | {userName: "啊盛", userId: 1001} |
urlParams | string | 路由参数 | - |
systemsInfo | SystemsInfoTypes | 系统信息 | 查看详情 |
sdkVersion | string | 埋点SDk版本 | 1.0.0 |
retainedDuration | number | 页面停留时长(毫秒) | 2000 |
4.2.2 TargetEleProps参数明细
参数名 | type | 描述 | 示例值 |
---|---|---|---|
nodeName | string | dom节点名称 | BUTTON |
id | string | id类名 | main_btn |
className | string | class类名 | fx-primary-btn |
position | number, number | 元素触发位置:x, y | 100, 200 |
4.2.3 SystemsInfoTypes参数明细
参数名 | type | 描述 | 示例值 |
---|---|---|---|
language | string | 系统语言 | zh-CN |
network | string | 网络类型 | - |
ua | string | userAgent | Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.64 Safari/537.36 |
client | string | 客户端(Mac/Android/iPhone/iPad/iPod/WeChat) | Mac, MacOS 10.15.7 |
platform | string | 应用平台类型,如不传会自动获取 | |
枚举:h5iPadpcother | h5 |
1.2.0-beta.1
2 months ago
1.2.0-beta.0
2 months ago
1.1.2-alpha.0
2 years ago
1.1.1
2 years ago
1.1.0
2 years ago
1.0.8
3 years ago
1.0.7
3 years ago
1.0.6
3 years ago
1.0.5
3 years ago