@fle-sdk/event-tracking-weapp
v1.0.2
Published
event tracking in weapp
Downloads
8
Readme
@fle.sdk/event-tracking-weapp
构建用户数据体系，让用户行为数据发挥深远的价值。
前言
WEB 数据埋点 sdk，开始之前请确保了解埋点的架构和基础知识
埋点中比较重要的组成部分就是每个事件的 key，注意的是 key 至少由两部分组成。 完整的 key 由这几部分组成：appkey.pagekey.partkey 通过“.”来分割
- appkey：APP 应用唯一标识
- pagekey：页面唯一标识，默认取当前路由
- partkey：控件/自定义事件唯一标识，可通过接口获取或自定义
一、下载
// npm
npm install @fle-sdk/event-tracking-weapp --save-dev
// yarn
yarn add @fle-sdk/event-tracking-weapp二、全埋点
全埋点包括三种事件：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",
"appKey": "218844",
"siteId": "",
"itemKey": "218844.app_other",
"requestTime": 1638456820316,
"deviceId": "f9e3f35a6371f369a2c9f21c48dcabe8",
"privateParamMap": {
"currentUrl": "http://localhost:9999/app/other",
"targetUrl": null,
"sdkVersion": "1.1.0",
"pageWidth": 742,
"pageHeight": 867,
"screenWidth": 1680,
"screenHeight": 1050,
"systemsInfo": {
"language": "zh-CN",
"platform": "pc",
"client": "Mac, MacOS 10.15.7",
"ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/96.0.4664.55 Safari/537.36",
"navigationStart": 1638456820099,
"navigation": "1ms",
"dns": "0ms",
"tcp": "0ms",
"request": "2ms",
"response": "1ms"
},
"urlParams": {},
"userInfo": {
"userId": 20211232232123
}
}
}
{
"desc": "Web 元素点击",
"event": "WebClick",
"appKey": "218844",
"siteId": "",
"itemKey": "218844.main.8ydgk",
"requestTime": 1638460476808,
"deviceId": "f9e3f35a6371f369a2c9f21c48dcabe8",
"privateParamMap": {
"position": [
126,
87
],
"targetEle": {
"id": "",
"nodeName": "H1",
"className": ""
},
"pointerType": "mouse",
"currentUrl": "http://localhost:9999/main?a=1",
"elementSelector": "#root > div:nth-of-type(1) > div:nth-of-type(1) > h1:nth-of-type(1)",
"sdkVersion": "1.1.0",
"pageWidth": 742,
"pageHeight": 867,
"screenWidth": 1680,
"screenHeight": 1050,
"systemsInfo": {
"language": "zh-CN",
"platform": "pc",
"client": "Mac, MacOS 10.15.7",
"ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/96.0.4664.55 Safari/537.36",
"navigationStart": 1638456820099,
"navigation": "1ms",
"dns": "0ms",
"tcp": "0ms",
"request": "2ms",
"response": "1ms",
"domComplete (domLoaded)": "201ms (186ms)",
"loadEvent": "1ms",
"total (DOM)": "218ms (217ms)"
},
"urlParams": {
"a": "1"
},
"userInfo": {
"userId": 20211232232123
}
}
}
{
"desc": "Web 页面浏览时长",
"event": "PageRetained",
"appKey": "218844",
"siteId": "",
"itemKey": "218844.app_other",
"requestTime": 1638460554657,
"deviceId": "f9e3f35a6371f369a2c9f21c48dcabe8",
"privateParamMap": {
"sdkVersion": "1.1.0",
"pageWidth": 742,
"pageHeight": 867,
"screenWidth": 1680,
"screenHeight": 1050,
"currentUrl": "http://localhost:9999/app/other",
"systemsInfo": {
"language": "zh-CN",
"platform": "pc",
"client": "Mac, MacOS 10.15.7",
"ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/96.0.4664.55 Safari/537.36",
"navigationStart": 1638456820099,
"navigation": "1ms",
"dns": "0ms",
"tcp": "0ms",
"request": "2ms",
"response": "1ms",
"domComplete (domLoaded)": "201ms (186ms)",
"loadEvent": "1ms",
"total (DOM)": "218ms (217ms)"
},
"urlParams": {},
"userInfo": {
"userId": 20211232232123
}
},
"retainedStartTime": 1638460451953
}三、API
WebTracking
- init() ---初始化
- preset() ---配置全局参数（注意：如果配置的全局属性初始化已配置，将覆盖。）
- login() ---用户登录
- track() ---自定义代码埋点上报
- getDeviceId() ---获取设备唯一标识
Init
参数
| 参数名 | type | 描述 | 是否必填 | 默认值 | | --------------------------------- | ------------ | -------------------------------------------------------- | ------------ | ---------- | | appKey | string | 应用唯一标识（由接口生成） | 是 | - | | serverUrl | string | 数据接收地址 | 是 | - | | autoTrack | boolean | 是否开启全埋点（指的是：页面浏览、元素点击事件自动上报） | 否 | false | | showLog | boolean | 是否在网页控制台打印发送的数据 | 否 | false | | useClientTime | boolean | 是否使用客户端系统时间 | 否 | true | | sendTimeout | number | 接口发送超时时长，超过该时长未发送成功将强制取消 | 否 | 3000 | | isTrackSinglePage | boolean | 是否采集单页面应用的路由变化 | 否 | false | | siteId | numberstring | 站点 Id | 否 | - | | contentType | string | application/json | | application/x-www-form-urlencoded | 否 | application/x-www-form-urlencoded |
例子
初始化 sdk 例子，建议在 src/App.js 中初始化，且需在useLayoutEffect中初始化。
import React, { useLayoutEffect } from "react";
import WebTracking from "@fle-sdk/event-tracking-weapp";
const App = () => {
useLayoutEffect(() => {
// init tracking
WebTracking.init({
appKey: "xxxxxx", // 由接口生成，应用唯一标识
serverUrl: "https://www.serverHost.com/serverApi/push",
autoTrack: true,
showLog: true,
isTrackSinglePage: true
});
}, []);
return <div className="App"></div>;
};
export default App;Preset
除了不可配置 appKey、serverUrl，本质上和 init 差不多，这么做是为了更好的区分使用场景，不产生歧义。
参数
| 参数名 | type | 描述 | 是否必填 | 默认值 | | ----------------- | ------------ | -------------------------------------------------------- | ------------ | ---------- | | autoTrack | boolean | 是否开启全埋点（指的是：页面浏览、元素点击事件自动上报） | 否 | false | | showLog | boolean | 是否在网页控制台打印发送的数据 | 否 | false | | useClientTime | boolean | 是否使用客户端系统时间 | 否 | true | | sendTimeout | number | 接口发送超时时长，超过该时长未发送成功将强制取消 | 否 | 3000 | | isTrackSinglePage | boolean | 是否采集单页面应用的路由变化 | 否 | false | | siteId | numberstring | 站点 Id | 否 | - |
例子
import React, { useLayoutEffect } from "react";
import WebTracking from "@fle-sdk/event-tracking-weapp";
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 | 描述 | 是否必填 | 默认值 | | ------ | ------------ | ------- | -------- | ------ | | userId | numberstring | 用户 ID | 否 | - |
例子
import React, { useEffect } from "react";
import WebTracking from "@fle-sdk/event-tracking-weapp";
import { LoginStore } from "store";
const Test = () => {
const getUserInfo = () => {
const { userId } = await LoginStore.getUserInfo();
WebTracking.Login("用户ID");
}
useEffect(() => {
getUserInfo()
}, []);
return <div className="Test"></div>;
};
export default Test;GetDeviceId
例子
获取设备唯一标识，单用户没有登录时即用户唯一标识
import React, { useEffect } from "react";
import WebTracking from "@fle-sdk/event-tracking-weapp";
import { LoginStore } from "store";
const Test = () => {
useEffect(() => {
WebTracking.getDeviceId();
}, []);
return <div className="Test"></div>;
};
export default Test;Track
手动代码埋点上报
上报参数
| 参数名 | type | 描述 | 是否必填 | 默认值 | | ---------- | ------------ | --------------------------------------------------------------------------------------------------- | ------------ | -------------- | | partkey | numberstring | 上报事件 Key（由前后端协商定义或由后端接口生成，该应用下需唯一且具有一定意义，例：goods_detail_pv） | 是 | - | | desc | string | 上报事件描述 | 否 | 自定义上报事件 | | business | object | 上报的业务参数 | 否 | - |
例子
import React, { useEffect } from "react";
import WebTracking from "@fle-sdk/event-tracking-weapp";
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 | 描述 | 示例值 | | --------------------------------------- | ------------ | ---------------------------------------------------------------------------- | ---------------------- | | appKey | string | 应用唯一标识（由接口生成） | - | | event | string | 有四种类型的值： | | PageViewPageRetainedCustomTrackWebClick | - | | itemKey | string | 当前埋点事件 Key | appkey.pagekey.partkey | | serverUrl | string | 数据接收地址 | - | | siteId | numberstring | 站点 ID | - | | showLog | boolean | 是否在网页控制台打印发送的数据 | false | | platform | string | 应用平台类型，如不传会自动获取 | | 可选值：h5pc | - | | autoTrack | boolean | 是否开启全埋点 指的是：页面浏览、元素点击事件自动上报 | true | | useClientTime | boolean | （是否使用客户端系统时间）注意：客户端系统时间可能会不准确，导致该字段不准确 | true | | requestTime | number | 发送请求事件 | - | | sendTimeout | number | 接口发送超时时长，超过该时长未发送成功将强制取消，单位：毫秒 | 3000 | | isTrackSinglePage | boolean | 是否采集单页面应用的路由变化 | false | | contentType | string | 可选值： |
application/json application/x-www-form-urlencoded | application/x-www-form-urlencoded | | privateParamMap | object | 私有参数 | 查看详情 |
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 |