❤
npm
Sign UpSign In

@fle-sdk/event-tracking-weapp
TypeScript icon, indicating that this package has built-in type declarations

1.0.2 • Public • Published

@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

Readme

Keywords

Package Sidebar

Install

npm i @fle-sdk/event-tracking-weapp

Weekly Downloads

1

Version

1.0.2

License

ISC

Unpacked Size

54.6 kB

Total Files

7

Last publish

Collaborators

  • libin_pro
  • chenfangsheng
Try on RunKit
Report malware