@fle.sdk/event-tracking-web

构建用户数据体系，让用户行为数据发挥深远的价值。

前言

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",
  "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-web";

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-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	描述	是否必填	默认值
userId	numberstring	用户ID	否	-

例子

import React, { useEffect } from "react";
import WebTracking from "@fle-sdk/event-tracking-web";
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-web";
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-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	描述	示例值
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