visual-buried-point-platform-h5

可视化埋点JS SDK接入指南

SDK更新日志

• v1.2.0 新增页面浏览时长统计功能、优化埋点精度、统计事件绑定用户标识等;
• v1.2.7 新增可自定义事件埋点接口、增加元素名称、访问途径等采集;
• v1.2.8 新增PV/UV统计、元数据配置，访问链路追踪等;
• v1.3.2 新的数据结构和修改PV/UV流量上报方式;
• v1.3.3 自定义埋点数据结构增加page对象和事件标识符eventCode;
• v1.3.4 调整SDK上报接口入参、删除appkey参数配置;
• v1.3.5 上报数据结构增加url;
• v1.3.6 调整上报数据结构circulation和duration计算规则;
• v2.0.0 调整SDK内部PVUV采集模式，分原有start方法采集及自动采集，支持获取埋点sdk内的跟踪ID；【详见1，3，4，7，10】
• v2.0.1 解决pv采集在不同端上问题，增加utm渠道采集；
• v2.0.2 优化startTrack采集duration取值规则；
• v2.0.3 解决path过长取值规则和优化utm取值；
• v2.0.4 增加buriedConfigData配置优化加载埋点配置表数据；

1.基本原理

Web SDK 是用原生 JavaScript 语言编写。理论支持 IE6+ 的浏览器。

Web SDK 的原理，主要是通过原生 JavaScript 代码，去监控页面的点击等操作，并自动获取屏幕宽高等属性，然后发送请求。因为 Web SDK 是面向传统的浏览器环境的，跟框架没有关系！也就是说必须也且只能是在 “ 浏览器上运行的网页中 ” 就可以使用 Web SDK。这里的几个特点：

• 能支持 JavasScript 语言的环境
• 能支持 Web 浏览器的环境

能支持 JavasScript 语言的环境 能支持 Web 浏览器的环境 因为要满足上述的 Web + JavaScirpt 的环境，所以我们称 SDK 为 Web JS SDK，简称 Web SDK。

1.用法

一、 npm | yarn、并添加配置文件 buried-point.ts ，或者直接导入 buried-point-h5.js 包

yarn add visual-buried-point-platform-h5 --registry=http://verdaccio.gogdev.cn/

npm i visual-buried-point-platform-h5 -S --registry=http://verdaccio.gogdev.cn/

二 、添加buried-point.ts配置文件

• 注：t_name、token、t_version 对应修改

// eslint-disable-next-line
// const BuriedPointH5 = require("./buried-point-h5.js");
import BuriedPointH5 from "visual-buried-point-platform-h5";
export const buriedPoint = new BuriedPointH5({
  /** 上报参数。需填入管理端生成的token 与 ·enableJavaScriptBridge·字段互斥 */
  token: '',
  // 页面载体环境
  ecology: "",
  /** domain */
  domain: "",
  /** 业务板块  （可选）*/
  busSegment: '';
  /** 业务模块 （可选）*/
  module: '';
  // 环境 取值 `test` `prod`。当开启环境配置参数后上报地址随环境变化 可以不配置上报地址
  environment: 'test',
  // 开启单页面？
  enableSPA: true,
  // 是否开启了CSS HASH值，(默认开启) [针对有商品列表多的情况，建议false]
  isOpenCSSHash: true,
  // 业务线流量上报的应用 name 
  t_name: '购物',
  // 业务线流量上报的当前应用 version
  t_version: 'v1.0.0',
  // Web JS SDK 的 H5 页面，在嵌入到 App 后，H5 内的事件可以通过 App 进行发送 默认关闭
  // 当开启次字段配置 token字段失效 打通APP上报数据依据所在环境判断  必须配置 androidToken与iosToken字段
  enableJavaScriptBridge: false,
  // 打通H5与APP通信后，上报数据ID
  androidToken: null,
  iosToken: null,
  // 是否兼容已埋点方案，true兼容（业务方需调用start方法采集PV流量），false不兼容（SDK内部自动采集，但前提业务方需要预置参数）
  isCompatible: true
  // 需要单独采集的页面path，设置isCompatible为false使用 例如：["/home", "/personal-auth"]
  signTrackPathArray: [],
  // 是否需要埋点配置表数据 默认false
  buriedConfigAPI: false,
});

2.初始化【可省略】

// buried-point-h5.js和buried-point.ts放入utils文件夹中
// 在main.js 或者 main.ts 入口
import "./utils/buried-point";

3.设置当前页面自动采集PVUV数据

//在任意页面
import { buriedPoint } from '@/utils/buried-point';
//vue
onMounted(async () => {
  buriedPoint.setPageExtraObj(
    {
      properties: {test: '123'}, //扩展参数
      busSegment: '8', //业务板块
      module: '4', //业务模块
    }
  )
})
//react
useEffect(() => {
    buriedPoint.setPageExtraObj({
      properties: {test: '123'}, //扩展参数
      busSegment: '8', //业务板块
      module: '4', //业务模块
    })
}, [])

4.获取埋点SDK内跟踪ID

import { buriedPoint } from '@/utils/buried-point';
buriedPoint.getTrackId()

5.设置绑定用户ID

import { buriedPoint } from '@/utils/buried-point';
// 应用登录成功后，调用下面API设置用户ID，后续产生的统计事件将会与该用户关联起来
buriedPoint.setUserInfo(xxxx)

6.自定义上报

6.1 自定义埋点事件对接可视化埋点平台说明

6.1.1 事件名称规范：

• 事件名称需按照事件类型_元素名称/页面名称_平台规则填写，例如“浏览_首页_ web”“点击_xxx商品_ web”

• 事件名称需唯一

6.1.2 事件类型：

• 事件类型仅能选择可视化埋点提供的事件类型，各个事件类型的触发、上报由各自定义埋点业务平台自行确认，事件类型包括以下四种：

• 搜索事件【 search 】

• 动作事件【 action 】

• 点击事件【 click 】

• 浏览事件【 browse 】

6.1.3自定义埋点事件包含事件内容说明：

• 事件ID

• 事件名称

• 事件类型，仅包含搜索事件、动作事件、点击事件、浏览事件四种事件类型。

• 事件触发时间，事件触发时间为用户触发埋点事件时间。

• 扩展参数，参数内容为自定义埋点平台自行定义，该事件需要额外传到可视化平台上的事件内容，以json字符串方式上传；json字符串长度限制为500字符，大于500字符参数可正常上报，做截断展示。

7.设置自定义上报

// 调用自定义上报
buriedPoint.setCustomEvent(data)
// 注：
data: json字符串
{
    $event_id: 对应创建的事件ID [ 必填字段 ]
    $busSegment: 业务板块 【非必填字段，建议业务填上, 否则数据统计可能出现缺失】【表1】
    $module: 业务模块 【非必填字段，建议根据业务填上， 否则数据统计可能出现缺失】【表1】
    $extend_param: 扩展参数(JSON) [ 非必填字段(建议根据业务需求填上) ]
    $event_code: 事件标识符 【必填字段，建议根据业务填上， 否则数据统计可能出现缺失】
    $page: 当前页对象 【非必填字段，建议根据业务填上， 否则数据统计可能出现缺失】
}
// 参考例子：【搜素事件】
import { BuriedPoint } from "@/utils/buried-point";
const params = { 
    $event_id: "3156566905601572864", 
    $event_code: "",
    $busSegment: 1,
    $module: 1, 
    $extend_param: { 
        title: "自定义[搜索事件]上报-搜索_首页搜索框", 
        searchContent: "猕猴桃"
    },
    $page: {
      domain: "",
      path: "",
      title: "",
    },
}
buriedPoint.setCustomEvent(params)

表1

示例如下：
业务板块        业务模块
busSegment     module
1.景区/门票  	1.门票
2.民宿/酒店  	1.民宿 2.酒店

8、流量上报

• sdk初始化后，可通过onStartTrack(params) 方法注册上报流量，并为上报添加属性值：

注册上报流量：onStartTrack(params)

配置：【以下配置参数建议上报】

| 参数 | 必填 | 类型 | 描述 | | ------------ | ---- | ----------- | ---------------- | | domain | 否 | string | 域名 | | path | 否 | string | 路径 | | ctk | 否 | string | 渠道推广编码 | | busSegment | 否 | string | 业务板块 【表1】 | | module | 否 | string | 业务模块 【表1】 | | extend_param | 否 | JSON对象 {} | 扩展参数 | | title | 否 | string | 页面名称 |

示例：

// 注：
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()进行销毁

示例：

buriedPoint.onDestroyTrack()

9、批量创建事件ID

main.py

用于批量创建和批量生成埋点数据的脚本，如不存在批量创建事件，可直接通过埋点管理端创建即可

准备

1.安装环境

需要在电脑上安装 python 环境

2.安装依赖

pip install requests

example示例：

1、在 utils/buryPoint 中创建各业务模块文件夹，并在文件夹下创建 parameter.py 文件 及 enum.js 文件，内容参考 route【路线业务模块】 文件夹，并将 enum.js 在 index.js 中导出

.

2、按各自业务修改其中的变量名

• 注：重要！重要！：注意先查看main.py中需要修改的：
  • projectId为埋点管理端上创建项目时生成的 token，参考 初始化方式 的图1

.

.

3、按需修改 main.py 最底部调用方法

• batchCreate: 批量创建【先执行第一步】
• batchWrite: 批量生成【再执行第二步】

先执行 batchCreate 方法将数据推到埋点后台管理系统中，再执行 batchWrite 方法，将后台管理中的数据写入到本地文件中

4、执行脚本

方式一（推荐）

在命令后增加业务模块文件夹名称，自动执行该文件夹下的参数文件

python main.py route

5、按环境生成 enum.xxx.js 文件，并在 utils/buryPoint/enum.js 中导出

注：这里默认会生成 `enum.commonm.js` 文件，如果后续生产或其他环境又是另外一份数据，到时候可以修改脚本，对不同环境进行适配

6、代码使用

查看index.js文件或者index.tsx相关文件

// 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;

// 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、埋点后台管理系统

云测管理端地址

• https://chameleon.gcongo.com.cn

8、SDK 文档

http://verdaccio.gogdev.cn/-/web/detail/visual-buried-point-platform-miniprogram

10 问题记录

1、在buried-point.ts配置文件中，提示无法找到模块“visual-buried-point-platform-h5”的声明文件。

在src下创建文件shims-vue.d.ts或者typings.d.ts，写入如下：

declare module '@/utils/buried-point-h5.js'; declare module 'visual-buried-point-platform-h5';