hzdataanalytic

v1.1.3

Published

25 days ago

埋点sdk

Downloads

0High
0Medium
0Low

vicki_wu

埋点sdk 埋点

Web JS SDK

集成文档（Web）

1. 集成埋点分析 SDK

Script 标签

如果你需要把引入代码和 SDK 文件整合在一个文件中，然后在页面头部通过 script src 的方式引入。你可以把引入代码改成如下方式，并放在下载下来的 sdk.min.js 文件前面。

<script charset='UTF-8' src="在 github 下载新版本的 /dist/sdk.min.js "></script>
<script>
  var sensors = window['hzdataanalytic'];
sensors.init({
  app_id: "app_limvtuenmd",
  aes_key:'0123456789abcdef',
  server_url: 'https://tapp3.jegotest.top/eventtracking/api',
  is_track_single_page:true, // 单页面配置，默认开启，若页面中有锚点设计，需要将该配置删除，否则触发锚点会多触发 $pageview 事件
  use_client_time:true, 
  heatmap: {
    //是否开启点击图，default 表示开启，自动采集 $WebClick 事件，可以设置 'not_collect' 表示关闭。
    clickmap:'default',
    //是否开启触达图，not_collect 表示关闭，不会自动采集 $WebStay 事件，可以设置 'default' 表示开启。
    scroll_notice_map:'not_collect'
  }   
});
  
</script>

CommonJS

从 npm 获取 sdk ， ***npm install hzdataanalytic ***

var sensors = require('hzdataanalytic'); 
sensors.init({
  app_id: "app_limvtuenmd",
  aes_key:'0123456789abcdef',
  server_url: 'https://tapp3.jegotest.top/eventtracking/api',
  is_track_single_page:true, // 单页面配置，默认开启，若页面中有锚点设计，需要将该配置删除，否则触发锚点会多触发 $pageview 事件
  use_client_time:true, 
  heatmap: {
    //是否开启点击图，default 表示开启，自动采集 $WebClick 事件，可以设置 'not_collect' 表示关闭。
    clickmap:'default',
    //是否开启触达图，not_collect 表示关闭，不会自动采集 $WebStay 事件，可以设置 'default' 表示开启。
    scroll_notice_map:'not_collect'
  }
});

AMD

引入sdk.amd.min.js ，假设该文件放到与 require.js 同一目录中

requirejs(["./dist/sdk.amd.js"], function(sensors) {
  sensors.init({
    app_id: "app_limvtuenmd",
    aes_key:'0123456789abcdef',
    server_url: 'https://tapp3.jegotest.top/eventtracking/api',
    is_track_single_page:true, // 单页面配置，默认开启，若页面中有锚点设计，需要将该配置删除，否则触发锚点会多触发 $pageview 事件
    use_client_time:true, 
    heatmap:{
      clickmap: 'default',
      scroll_notice_map: 'not_collect'
    }
  });
   
});

ES Module

import sensors from './dist/sdk.es6.js'
# import sensors from "hzdataanalytic";
sensors.init({
  app_id: "app_limvtuenmd",
  aes_key:'0123456789abcdef',
  server_url: 'https://tapp3.jegotest.top/eventtracking/api',
  is_track_single_page:true, // 单页面配置，默认开启，若页面中有锚点设计，需要将该配置删除，否则触发锚点会多触发 $pageview 事件
  use_client_time:true, 
  heatmap: {
    //是否开启点击图，default 表示开启，自动采集 $WebClick 事件，可以设置 'not_collect' 表示关闭。
    clickmap:'default',
    //是否开启触达图，not_collect 表示关闭，不会自动采集 $WebStay 事件，可以设置 'default' 表示开启。
    scroll_notice_map:'not_collect'
  }
});

2. SDK 基本配置

2.1. 配置项目https://tapp3.jegotest.top/eventtracking/api

自动生成导入代码时，会自动配置当前项目接收地址。其他方式引入 SDK 时，需要手动将 server_url 参数设置为相应项目的https://tapp3.jegotest.top/eventtracking/api。

集成：https://tapp3.jegotest.top/eventtracking/api stage：https://svapp3.jegotest.top/eventtracking/api 生产：https://app3.jegotrip.com.cn/eventtracking/api ----> app

2.2. 开启全埋点

初始化 SDK 时，heatmap 参数和 quick() 接口可以配置 SDK 全埋点。全埋点的更多配置，可参考全埋点 (Web) 。

2.3. 设置事件公共属性

对于所有事件都需要添加的属性，可在初始化 SDK 后，sensors.quick('autoTrack') 前，调用 registerPage() 将属性注册为公共属性

<script>
// 初始化 SDK

// 注册公共属性
sensors.registerPage({
	current_url: location.href,
	referrer: document.referrer
});
</script>

2.4. 代码埋点追踪事件

SDK 初始后，即可以通过 track() 方法追踪用户行为事件，并添加自定义属性：

sensors.track('BuyProduct', {
	ProductName: "MacBook Pro", 
	ProductPrice: 123.45, 
	IsAddedToFav: false,
});

3. 调试查看事件信息

3.1. 事件的触发日志

测试阶段在初始化代码中添加 show_log 设置为 true，页面上有事件触发时，浏览器开发者工具会打印采集的事件信息，如下图。上线时初始化代码中将 show_log 设置为 false 即可关闭日志输出功能，show_log 和 server_url 平级。

基础 API 介绍（Web）

1. SDK 初始化参数

| 参数 | 默认值 | 含义 | 备注 | | :------------------- | :-------------- | :----------------------------------------------------------- | :----------------------------------------------------------: | | sdk_url | 无 | sdk.min.js 文件的地址。 | 引入js放在你们自己目录下。 | | server_url | 无 | https://tapp3.jegotest.top/eventtracking/api。 | 集成：https://tapp3.jegotest.top/eventtracking/apistage：https://svapp3.jegotest.top/eventtracking/api生产：https://app3.jegotrip.com.cn/eventtracking/api | | app_id | 无 | appid | | | aes_key | 无 | key | | | show_log | false | 设置 true 后会在网页控制台打 logger，会显示发送的数据,设置 false 表示不显示。 | | | is_track_single_page | false | 表示是否开启单页面自动采集 $pageview 功能，SDK 会在 url 改变之后自动采集web页面浏览事件 $pageview。 | | |

2. 事件公共属性

2.1. 设置事件静态公共属性

对于所有事件都需要添加的属性，可在初始化 SDK 后，调用 registerPage() 将属性注册为公共属性：

<script>
// 注册公共属性
sensors.registerPage({
	current_url: location.href,
	referrer: document.referrer
});
</script>

全埋点

1. 开启全埋点

1.1. 代码示例

<script charset='UTF-8' src="在 github 下载新版本的 sdk.min.js "></script>
<script>
  var sensors = window['hzdataanalytic'];
sensors.init({
  app_id: "app_limvtuenmd",
  aes_key:'0123456789abcdef',
  server_url: 'https://tapp3.jegotest.top/eventtracking/api',
  is_track_single_page:true, // 单页面配置，默认开启，若页面中有锚点设计，需要将该配置删除，否则触发锚点会多触发 $pageview 事件
  use_client_time:true, 
  heatmap: {
    //是否开启点击图，default 表示开启，自动采集 $WebClick 事件，可以设置 'not_collect' 表示关闭。
    clickmap:'default',
    //是否开启触达图，not_collect 表示关闭，不会自动采集 $WebStay 事件，可以设置 'default' 表示开启。
    scroll_notice_map:'default'
  } 
});
</script>

Web JS SDK 全埋点包括三种事件：Web 页面浏览、Web 元素点击、Web 视区停留。如果需要针对全埋点类型进行单独配置，则参照下文中单个全埋点类型使用的帮助文档。

1.2. Web 页面浏览($pageview)

// 设置之后，SDK 就会自动收集页面浏览事件，以及设置初始来源。
sensors.quick('autoTrack')

// 另外，如果想加额外的属性，可以如下方式（添加 platform 属性为 h5）
sensors.quick('autoTrack', {
	platform:'h5'
})

1.3. Web 元素点击($WebClick)

// SDK 初始化参数配置
heatmap: {
	// 是否开启点击图，default 表示开启，自动采集 $WebClick 事件，可以设置 'not_collect' 表示关闭。
    // 默认只有点击 a input button textarea 四种元素时，才会触发 $WebClick 元素点击事件
	clickmap:'default'
}

1.4. 视区停留事件($WebStay)

// SDK 初始化参数配置
heatmap: {
	//是否开启触达图，default 表示开启，自动采集 $WebStay 事件，可以设置 'not_collect' 表示关闭。
	scroll_notice_map:'default'
}

2. 其他元素类型的元素点击事件采集

2.1. 支持 div 类型元素的自动采集

在原来的全埋点（采集 a、button、input 、textarea 标签）基础上新增对 div 标签的采集，采集规则为：

div 为叶子结点（无子元素）时采集 div 的点击
div 中有且只有样式标签（['mark','strong','b','em','i','u','abbr','ins','del','s','sup']）时，点击 div 或者样式标签都采集 div 的点击

通过 collect_tags 配置是否开启 div 的全埋点采集，默认不采集。如需开启，配置 collect_tags 参数如下：

heatmap:{  
  collect_tags:{
    div : true
  }
}

2.2. 支持任意类型元素的自动采集

通过 collect_tags 配置是否开启其他任意元素的全埋点采集（默认不采集），其中 div 通过配置最多可以采集 3 层嵌套情况***。***

heatmap: {
  //是否开启点击图，默认 default 表示开启
  clickmap:'default',
    collect_tags: {
      div: {
        max_level: 1 // 默认是 1，即只支持叶子 div。可配置范围是 [1, 2, 3],非该范围配置值，会被当作 1 处理。
      },
        li: true,
          img: true
      // ... 其他标签
    }
}

2.3. 支持任意层级 div 元素的自动采集

开启方式：

该功能通过可视化圈选实现，在可视化模式下去圈选相应的 div 元素后，全埋点可自动采集该 div 元素。

SDK 需要配置参数 get_vtrack_config: true 开启该功能（默认 false 关闭）。参考如下：

heatmap: {
  //是否开启点击图，默认 default 表示开启
  clickmap:'default',
  get_vtrack_config: true
}

服务端需要开启相应的配置。通过命令开启（后端开启：spadmin config set server -p sdg -m web -n enable_unlimit_position_web_element -v true）。

2.4. 配置特殊属性来支持其他类型元素的自动采集

2.4.1. 配置特殊属性：data-sensors-click

开启全埋点时，给需要自动采集点击事件的元素增加属性：data-sensors-click。

代码示例如下：

<div name='test' data-hz-click>我是测试元素</div>
<li data-hz-click class='test-li'>我是测试元素</li>

2.4.2. 配置页面元素点击的自定义属性

开启全埋点时，支持配置带有指定属性的页面元素点击，自动采集点击事件。代码示例如下：

<script src="xxxx/xxx/sdk.js"></script>
<script>
  var sensors = sensorsDataAnalytic201505;
  sensors.init({
    app_id: "app_limvtuenmd",
    aes_key:'0123456789abcdef',
    server_url: 'https://tapp3.jegotest.top/eventtracking/api', 
    heatmap: {
      track_attr: ['hotrep', 'anotherprop', "data-prop2"],
      clickmap:'default',
      scroll_notice_map: 'not_collect'
    }
  });
</script>
...
<p hotrep id="test1">hotrep p tag</p>
<p><span anotherprop id="test2">another repo a.b.c</span></p>
<p><strong data-prop2 id="test3">strong with prop2 attribute</strong></p>

2.5. 代码埋点触发元素点击事件

如果你想要对非 a input button textarea 的其他元素采集点击事件的话，请在元素发生点击的时候，调用我们的这个方法。

// 下面演示一个 div 标签被点击时触发预置的元素点击事件
<div id="submit_order">提交订单</div>

<script type="text/javascript">
$('#submit_order').on('click', function() {
	sensors.quick('trackHeatMap', this, {
		customProp1: 'test1', //如果需要添加自定义属性需要将 SDK 升级到 1.0.4 及以上版本。
		customProp2: 'test2'
	});
});
</script>

// 注意: 在原生 js 中调用我们绑定的 click 事件时 this 指向的是元素节点，在其他框架采集点击事件时 this 指针也应该指向相应的元素节点，例如在 vue 中可以参考下面示例。

<div v-on:click="track">点击</div>

<script>
export default {
	methods: {
		track: function(event) {
			sensors.quick('trackHeatMap', event.target, {
				customProp1: 'test1', //如果需要添加自定义属性需要将 SDK 升级到 1.0.4 及以上版本。
				customProp2: 'test2'
			});
		}
	}
}
</script>

新方法 trackAllHeatMap ，当调用这个方法时，此方法的第二个参数可以传入包括 a, input, button, textarea 标签和 div，img 等的所有标签。而 trackHeatMap 只采集除 a, input, button,textarea 之外的标签。同时，这两个方法均可以设置自定义属性，且支持回调函数（这两个方法的第四个参数都可以传入一个方法）。

// 下面演示一个 button 按钮被点击时触发预置的元素点击事件
<button id="testp">测试按钮</button>

<script type="text/javascript">
  $('#testp').on('click', function() {
    sensors.quick('trackAllHeatMap', this, {
      customProp1: 'test1', //如果需要添加自定义属性需要将 SDK 升级到 1.0.4 及以上版本。
      customProp2: 'test2'
    });
  });
</script>

3. 全埋点相关参数配置

3.1. Web 元素点击

3.1.1. heatmap 相关参数，提供了对于 $WebClick 事件的自定义设置和处理。

heatmap 相关参数说明：

heatmap 相关参数代码示例：

heatmap: {
  clickmap:'default',
    scroll_notice_map:'default',
      loadTimeout: 3000,
        collect_url: function(){
          //如果只采集首页
          if(location.href === 'example.com/index.html' || location.href === 'example.com/'){
            return true;
          }
        },
          //此参数针对预置 $WebClick 事件（包括 quick('trackHeatMap') quick('trackAllHeatMap') 触发的）生效。
          collect_element: function(element_target){
            // 如果这个元素有属性sensors-disable=true时候，不采集。
            if(element_target.getAttribute('sensors-disable') === 'true'){
              return false;
            }else{
              return true;
            }
          },
            //此参数针对预置 $WebClick 事件（包括 quick('trackHeatMap') quick('trackAllHeatMap') 触发的）生效。
            custom_property:function( element_target ){
              //比如您需要给有 data=test 属性的标签的点击事件增加自定义属性 name:'aa' ，则代码如下：
              if(element_target.getAttribute('data') === 'test'){
                return {
                  name:'aa'
                }
              }
            },
              collect_input:function(element_target){
                //例如如果元素的 id 是a，就采集这个元素里的内容。
                if(element_target.id === 'a'){
                  return true;
                }
              },
                element_selector:'not_use_id',
                  renderRefreshTime:1000
}

3.2. Web 视区停留

3.2.1. 相关参数说明：

scrollmap 相关参数说明：

| 参数名 | 参数值说明 | | :---------- | :----------------------------------------------------------- | | collect_url | 返回真会采集当前页面的数据，返回假表示不采集当前页面,设置这个函数后，内容为空的话，是返回假的。不设置函数默认是采集所有页面。 |