visual-buried-point-platform-h5 1.3.4

package/.babelrc

@@ -0,0 +1,8 @@
+{
+  "presets": [
+    ["es2015", {
+      "modules": false
+    }],
+    "stage-2"
+  ]
+}

package/README.md

@@ -0,0 +1,434 @@
+# visual-buried-point-platform-h5
+# 可视化埋点JS SDK接入指南
+
+### SDK更新日志
+- 1.2.0 新增页面浏览时长统计功能、优化埋点精度、统计事件绑定用户标识等；
+- 1.2.7 新增可自定义事件埋点接口、增加元素名称、访问途径等采集；
+- 1.2.8 新增PV/UV统计、元数据配置，访问链路追踪等；
+- 1.3.2 新的数据结构和修改PV/UV流量上报方式；
+- 1.3.3 自定义埋点数据结构增加page对象和事件标识符eventCode；
+
+### 1.基本原理
+
+Web SDK 是用原生 JavaScript 语言编写。理论支持 IE6+ 的浏览器。
+
+Web SDK 的原理，主要是通过原生 JavaScript 代码，去监控页面的点击等操作，并自动获取屏幕宽高等属性，然后发送请求。因为 Web SDK 是面向传统的浏览器环境的，跟框架没有关系！也就是说必须也且只能是在 “ 浏览器上运行的网页中 ” 就可以使用 Web SDK。这里的几个特点：
+
+* 能支持 JavasScript 语言的环境
+* 能支持 Web 浏览器的环境
+
+能支持 JavasScript 语言的环境
+能支持 Web 浏览器的环境
+因为要满足上述的 Web + JavaScirpt 的环境，所以我们称 SDK 为 Web JS SDK，简称 Web SDK。
+
+<!-- ## 功能
+
+* 上报pv uv
+* 捕获error
+* 上报性能performance
+* 上报用户轨迹
+* 支持单页面
+* hack ajax fetch
+* 上报加载的资源
+* hack console
+* hack onpopstate
+* 暴露全局变量__bb
+* 埋点 sum avg msg
+* 无埋点方案 -->
+
+<!-- // TODO:lodash -->
+
+## 用法
+
+token在可视化埋点后台申请
+
+### 方法一  npm | yarn、并添加配置文件	buried-point.ts
+```javascript
+npm i visual-buried-point-platform-h5 -S --registry=http://verdaccio.gogdev.cn/
+
+yarn add visual-buried-point-platform-h5 --registry=http://verdaccio.gogdev.cn/
+```
+
+### 方法二 、导入	buried-point-h5.js	包，并添加配置文件	buried-point.ts【推荐】
+```js
+import * as BuriedPointH5 from 'visual-buried-point-platform-h5';
+ts declare module 'visual-buried-point-platform-h5';
+
+export const buriedPoint = new BuriedPointH5({
+  //配置
+  token: 'xxx',
+  environment: 'test',
+  reportUrl: ''
+  ...
+  ...
+})
+
+// uniapp兼容写法
+import * as BuriedPointH5 from 'visual-buried-point-platform-h5';
+const BP = BuriedPointH5.default || BuriedPointH5
+export const buriedPoint = new BP({
+  //配置
+  token: 'xxx',
+  environment: 'test',
+  reportUrl: ''
+  ...
+  ...
+})
+```
+
+## 添加buried-point.ts配置文件
+
+- 注：t_name、token、t_version 对应修改
+
+```js
+// import * as BuriedPointH5 from 'visual-buried-point-platform-h5';
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const BuriedPointH5 = require("./buried-point-h5.js");
+export const BuriedPoint = new BuriedPointH5({
+  /** 上报地址（可选） */
+  reportUrl: 'http://localhost:8000',
+  /** 上报参数。需填入管理端生成的token 与 ·enableJavaScriptBridge·字段互斥 */
+  token: '',
+  /** appkey （可选）*/
+  appkey: '';
+  /** 业务板块  （可选）*/
+  busSegment: '';
+  /** 业务模块 （可选）*/
+  module: '';
+  // app版本
+  appVersion: '1.0.0',
+  // 环境 取值 `dev` `test` `prod`。当开启环境配置参数后上报地址随环境变化 可以不配置上报地址
+  environment: 'dev',
+  // 脚本延迟上报时间
+  outtime: 3000,
+  // 开启单页面？
+  enableSPA: true,
+  // 是否自动上报pv
+  autoSendPv: true,
+  // 是否上报页面性能数据
+  isPage: true,
+  // 是否上报ajax性能数据
+  isAjax: true,
+  // 是否上报页面资源数据
+  isResource: true,
+  // 是否上报错误信息
+  isError: true,
+  // 是否录屏
+  isRecord: true,
+  // 是否上报行为
+  isBehavior: true,
+  // 是否开启了CSS HASH值，(默认开启) [针对商品列表情况埋点，建议false]
+  isOpenCSSHash: true,
+  // 业务线流量上报的应用 name 
+  t_name: '购物',
+  // 业务线流量上报的当前应用 version
+  t_version: 'v1.0.0',
+  ignore: {
+    ignoreErrors: [],
+    ignoreUrls: [],
+    ignoreApis: ['/api/v1/report/web', 'livereload.js?snipver=1', '/sockjs-node/info'],
+  },
+  behavior: {
+    console: ['log', 'error'], // 取值可以是"debug", "info", "warn", "log", "error"
+    click: true,
+  },
+  // 最长上报数据长度
+  maxLength: 1000,
+  // Web JS SDK 的 H5 页面，在嵌入到 App 后，H5 内的事件可以通过 App 进行发送 默认关闭
+  // 当开启次字段配置 token字段失效 打通APP上报数据依据所在环境判断  必须配置 androidToken与iosToken字段
+  enableJavaScriptBridge: false,
+  // 打通H5与APP通信后，上报数据ID
+  androidToken: null,
+  iosToken: null
+});
+```
+
+## 初始化
+
+```javascript
+// buried-point-h5.js和buried-point.ts放入utils文件夹中
+// 在main.js 或者 main.ts 入口
+import "./utils/buried-point";
+```
+
+##  3.设置绑定用户ID
+
+```js
+// 应用登录成功后，调用下面API设置用户ID，后续产生的统计事件将会与该用户关联起来
+buriedPoint.setUserInfo(xxxx)
+```
+
+## 4.自定义上报
+
+### 4.1 自定义埋点事件对接可视化埋点平台说明
+
+#### 4.1.1 事件名称规范：
+
+- 事件名称需按照事件类型_元素名称/页面名称_平台规则填写，例如“浏览_首页_ web”“点击_xxx商品_ web”
+
+- 事件名称需唯一
+
+#### 4.1.2 事件类型：
+
+- 事件类型仅能选择可视化埋点提供的事件类型，各个事件类型的触发、上报由各自定义埋点业务平台自行确认，事件类型包括以下四种：
+
+- **搜索事件【 search 】**
+
+- **动作事件【 action 】**
+
+- **点击事件【 click 】**
+
+- **浏览事件【 browse 】**
+
+#### 4.1.3自定义埋点事件包含事件内容说明：
+
+- 事件ID
+
+- 事件名称
+
+- 事件类型，仅包含搜索事件、动作事件、点击事件、浏览事件四种事件类型。
+
+- 事件触发时间，事件触发时间为用户触发埋点事件时间。
+
+- 扩展参数，参数内容为自定义埋点平台自行定义，该事件需要额外传到可视化平台上的事件内容，以json字符串方式上传；json字符串长度限制为500字符，大于500字符参数可正常上报，做截断展示。
+
+## 5.设置自定义上报
+
+```javascript
+// 调用自定义上报
+buriedPoint.setCustomEvent(data)
+// 注：
+data: json字符串
+{
+    $event_id: 对应创建的事件ID [ 必填字段 ]
+    $busSegment: 业务板块 【非必填字段，建议业务填上, 否则数据统计可能出现缺失】【表1】
+    $module: 业务模块 【非必填字段，建议根据业务填上， 否则数据统计可能出现缺失】【表1】
+    $extend_param: 扩展参数(JSON) [ 非必填字段(建议根据业务需求填上) ]
+    $event_code: 事件标识符 【必填字段，建议根据业务填上， 否则数据统计可能出现缺失】
+    $page: 当前页对象 【非必填字段，建议根据业务填上， 否则数据统计可能出现缺失】
+    $path: 埋点组件的路径 【必填字段，建议根据业务填上， 否则数据统计可能出现缺失】
+}
+// 参考例子：【搜素事件】
+import { BuriedPoint } from "@/utils/buried-point";
+const params = { 
+    $event_id: "3156566905601572864", 
+    $busSegment: 1,
+    $module: 1, 
+    $extend_param: { 
+        title: "自定义[搜索事件]上报-搜索_首页搜索框", 
+        searchContent: "猕猴桃"
+    },
+    $event_code: "",
+    $page: {
+      domain: "",
+      path: "",
+      title: "",
+    },
+    $path: "",
+}
+buriedPoint.setCustomEvent(params)
+```
+
+表1
+
+```js
+示例如下：
+业务板块        业务模块
+busSegment     module
+1.景区/门票  	1.门票
+2.民宿/酒店  	1.民宿 2.酒店
+```
+
+## 6、流量上报
+
+- sdk初始化后，可通过**onStartTrack(params)** 方法注册上报流量，并为上报添加属性值：
+
+**注册上报流量：onStartTrack(params)**
+
+**配置：**【以下配置参数建议上报】
+
+| 参数         | 必填 | 类型        | 描述             |
+| ------------ | ---- | ----------- | ---------------- |
+| domain       | 否   | string      | 域名             |
+| path         | 否   | string      | 路径             |
+| ctk          | 否   | string      | 渠道推广编码     |
+| busSegment   | 否   | string      | 业务板块 【表1】 |
+| module       | 否   | string      | 业务模块 【表1】 |
+| extend_param | 否   | JSON对象 {} | 扩展参数         |
+| title        | 否   | string      | 页面名称         |
+
+**示例：**
+
+```javascript
+// 注：
+data: JSON对象
+const params = {
+  domain: "xxxx",
+  busSegment: 1,
+  module: 1,
+  title: "店铺详情",
+  extend_param: {
+      goods_id: 123456, //商品id 【根据业务确定】
+      store_id: 1111, //店铺id   【...】
+      business_id: 222, //商户id 【...】
+  }
+};
+buriedPoint.onStartTrack(params)
+```
+
+**销毁上报流量：调用onDestroyTrack()进行销毁**
+
+**示例：**
+
+```javascript
+buriedPoint.onDestroyTrack()
+```
+
+## 6、批量创建事件ID
+
+## main.py
+
+用于批量创建和批量生成埋点数据的脚本，**如不存在批量创建事件，可直接通过埋点管理端创建即可**
+
+### 准备
+
+#### 1.安装环境
+
+需要在电脑上安装 python 环境
+
+#### 2.安装依赖
+
+```shell
+pip install requests
+```
+
+## example示例：
+
+#### 1、在 `utils/buryPoint` 中创建各业务模块文件夹，并在文件夹下创建 `parameter.py` 文件 及 `enum.js` 文件，内容参考 `route`【路线业务模块】 文件夹，并将 `enum.js` 在 `index.js` 中导出
+
+![](image\101.png).
+
+#### 2、按各自业务修改其中的变量名
+
+- 注：重要！重要！：注意先查看main.py中需要修改的：
+  - projectId为埋点管理端上创建项目时生成的 **token**，参考 初始化方式 的图1
+
+![](image\102.png).
+
+![](image\103.png)
+
+![](image\104.png)
+
+![](image\105.png).
+
+#### 3、按需修改 main.py 最底部调用方法
+
+- batchCreate: 批量创建【先执行第一步】
+- batchWrite: 批量生成【再执行第二步】
+
+先执行 `batchCreate` 方法将数据推到埋点后台管理系统中，再执行 `batchWrite` 方法，将后台管理中的数据写入到本地文件中
+
+#### 4、执行脚本
+
+##### 方式一（推荐）
+
+在命令后增加**业务模块文件夹**名称，自动执行该文件夹下的参数文件
+
+```python
+python main.py route
+```
+
+#### 5、按环境生成 `enum.xxx.js` 文件，并在 `utils/buryPoint/enum.js` 中导出
+
+```javascript
+注：这里默认会生成 `enum.commonm.js` 文件，如果后续生产或其他环境又是另外一份数据，到时候可以修改脚本，对不同环境进行适配
+```
+
+#### 6、代码使用
+
+查看**index.js**文件或者**index.tsx**相关文件
+
+```javascript
+// index.js
+import { setCustomEvent, onStartTrack, onDestroyTrack } from '@/utils/pointAction';
+
+class Favourite extends Component {
+
+	//注册
+    componentDidMount() {
+        this.genData();
+        onStartTrack('我的收藏', null);
+    }
+
+	//销毁
+    componentWillUnmount() {
+      onDestroyTrack();
+    }
+
+    // 点击取消收藏上报
+    cancel(e, obj) {
+        setCustomEvent('点击-我的-我的收藏-取消收藏');
+    }
+    render() {
+        return (
+            <div >
+                ...
+				...
+				...
+
+            </div>
+        )
+    }
+}
+
+export default Favourite;
+
+```
+
+```javascript
+// index.tsx
+import React, { useEffect, useState } from 'react'
+import { setCustomEvent, onStartTrack, onDestroyTrack } from '@/utils/pointAction';
+
+const PageComponent = (props: any) => {
+  // 进入编辑页面
+  const toEditAddressPage = (item: any) => {
+    setCustomEvent('点击-地址管理-编辑');
+  }
+
+  useEffect(() => {
+    onStartTrack('地址管理', null);
+    return () => {
+      onDestroyTrack();
+    };
+  }, []);
+
+  useEffect(() => {
+    getDataSource()
+  }, [])
+
+  return (
+    <div>
+      ...
+	  ...
+    </div>
+  );
+};
+
+export default connect(({trade}) => {
+  return {site: trade.site}
+})(PageComponent);
+```
+
+#### 7、埋点后台管理系统
+
+##### 云测管理端地址
+
+- chameleon.gcongo.com.cn
+
+#### 8、SDK 文档
+
+http://verdaccio.gogdev.cn/-/web/detail/visual-buried-point-platform-miniprogram
+
+
+