神策分析 JavaScript SDK AutoTrack 使用说明

最后更新于:2019-09-05 16:56:15

1、全埋点代码生成

2、页面浏览事件采集

3、页面点击事件及视区停留事件的采集示例

4、预置属性含义解释

5、常见问题

1. 全埋点代码生成

首先从神策分析的主页中,进入数据接入向导页面:

然后在右上角点击 数据接入 显示如下界面,然后点击 生成导入代码,进入代码生成页面,按需选择合适的选项,然后点击生成代码,如下图:

这段代码是每个需要采集数据的页面都要引入的,所以建议放在页面的公共部分,比如页面头部或者尾部。

2. 页面浏览事件采集($pageview)

为了方便使用,神策分析的 SDK 也提供了一些默认事件的收集,例如如果需要采集页面浏览事件(即 PageView),可以通过增加如下代码:

  // 如果需要调用 login 来重新设置用户标识,必须在此之前调用
  sensors.quick('autoTrack')

设置之后,SDK 就会自动收集页面浏览事件,以及设置初始来源。 另外,如果想加额外的属性,可以如下方式(添加 platForm 属性为 h5)

  // 如果需要调用 login 来重新设置用户标识,必须在此之前调用
 sensors.quick('autoTrack', {
   platForm:'h5'
 })

而如果只想追踪事件,不想设置首次来源到 profile 里,可以使用sensors.quick('autoTrackWithoutProfile')来替代。

注意: 单页面中发送页面浏览事件($pageview)

第一种 自动模式
配置参数 is_track_single_page (推荐使用这种模式),默认值为 false ,表示是否开启自动采集 web 浏览事件 $pageview 的功能
其原理是修改 window 对象的 pushState 和 replaceState 原生方法,在页面的 url 改变后自动采集 $pageview 事件,若用户浏览器不支持这两种方法或者是使用 hash 的路由模式,我们也会监听 popstate 和 hashchange 事件来自动触发 $pageview 事件

//SDK版本1.12.18以上支持,默认值为false
is_track_single_page:true

//注意默认的: sa.quick('autoTrack') 是需要的

第二种 手动模式
在页面切换的时候,手动调用 sensors.quick('autoTrackSinglePage') 来采集 web 浏览事件 $pageview ,这个方法在页面 url 切换后调用

// 比如现在是在 react 中可以在全局的 onUpdate 里来调用
onUpdate: function(){
    sensors.quick('autoTrackSinglePage');
}

  //vue 项目在路由切换的时候调用
router.afterEach((to,from) => {
    Vue.nextTick(() => {
        sensors.quick("autoTrackSinglePage");
    });
});
//注意: vue下因为首页打开时候就会默认触发页面更细,所以需要去掉默认加的 sa.quick('autoTrack')

此方法也可添加自定义属性,

sensors.quick("autoTrackSinglePage",{platForm:"H5"});

3. 页面点击事件及视区停留事件的采集

必填参数:

  • web_url: 神策分析后台地址,神策分析中点击分析及触达分析功能会用到此地址,代码生成工具会自动生成。如果神策后台版本及 sensorsdata.min.js 均是 1.10 及以上版本,这个参数不需要配置。

  • heatmap_url: 神策分析中点击分析及触达分析功能代码,代码生成工具会自动生成。如果神策代码中 sensorsdata.min.js 版本是 1.13.1 及以前版本,这个参数须配置,高于此版本不需要配置。

  • heatmap: 必须配置这个参数才会发送数据,如果只想采集所有页面的仅交互按钮的数据,可以使用这种配置方式 heatmap:{} 。具体参数配置如下:

heatmap: {
    clickmap:'default',
    scroll_notice_map:'default',
    loadTimeout:  3000,
    collect_url: function(){
        //如果只采集首页
        if(location.href === 'xxx.com/index.html' || location.href === 'xxx.com/'){
            return true;
        }
    },
    collect_element: function(element_target){
        // 如果这个元素有属性sensors-disable=true时候,不采集
        if(element_target.getAttribute('sensors-disable') === 'true'){
            return false;
        }else{
            return true;
        }
    },
    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,
    scroll_delay_time: 4000
}

heatmap 相关参数说明:

参数名 参数值说明 备注
clickmap 是否开启点击图,默认 default 表示开启,可以设置 'not_collect' 表示关闭 需要 JSSDK 版本号大于 1.7
scroll_notice_map 是否开启触达注意力图,默认 default 表示开启,可以设置 'not_collect' 表示关闭 需要 JSSDK 版本号大于 1.9.1
loadTimeout 毫秒 设置多少毫秒后开始渲染点击图,因为刚打开页面时候页面有些元素还没加载
collect_url 返回真会采集当前页面的元素点击事件,返回假表示不采集当前页面,设置这个函数后,内容为空的话,是返回假的。不设置函数默认是采集所有页面
collect_element 用户点击页面元素时会触发这个函数,让你来判断是否要采集当前这个元素,返回真表示采集,返回假表示不采集。
custom_property 假如要在 $WebClick 事件增加自定义属性,可以通过标签的特征来判断是否要增加 注意:如果同时使用了 trackAllHeatMap 或者 trackHeatMap 方法设置了自定义属性,那么这两个方法中的自定义属性对象会覆盖 custom_property 返回值中的同名属性,它的优先级更高。
collect_input 考虑到用户隐私,这里可以设置 input 里的内容是否采集 如果返回真,表示采集 input 内容,返回假表示不采集 input 内容,默认不采集
element_selector SDK 默认优先以元素 ID 作为选择器采集点击事件,若不想以 ID 作为选择器,可以设置该参数为 'not_use_id' 1.12.1 以上版本支持
renderRefreshTime 毫秒 第二版点击图滚动滚动条,改变页面尺寸后延时多少毫秒重新渲染页面
scroll_delay_time 毫秒 设置触达图的有效停留时间,默认超过 4 秒以上算有效停留

3.1 点击图默认只采集这些交互元素( a input button )

开启全埋点,SDK 就会自动追踪页面上的按钮( a button input )这种 html 标签类型 的点击情况,一旦页面某一个按钮发生了点击行为,我们就会去采集此按钮的一些信息,例如: 这个按钮的标签类型( a button input ),这个按钮的文本内容,这个按钮的 name ,这个按钮的 id 、 class 名,还有一些按钮特有的属性如 href 等。

3.2 如何采集自定义元素的 $WebClick 事件,比如 img 和 div

请注意,在使用该方法采集 div 元素的点击事件时,请根据自身需求采集某些专门的 class 或者 ID 的 div 元素,避免全局采集所有 div 元素,否则会导致 $WebClick 事件量激增,并且点击图会显示页面上所有 div 元素的色块,导致点击图整体过于混乱无法查看。

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

SDK 更新日志

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

<script type="text/javascript">

  $('#submit_order').on('click', function() {
      sensors.quick('trackHeatMap', this, {
        customProp1: 'test1',   //如果需要添加自定义属性需要将 SDK 升级到 1.13.7 及以上版本。
        customProp2: 'test2'
      }, function() {
        console.log('callback');
      });
  });

</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.13.7 及以上版本。
        customProp2: 'test2'
      }, function() {
        console.log('callback');
      });
    }
  }
}
</script>

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

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

<script type="text/javascript">

  $('#testp').on('click', function() {
      sensors.quick('trackAllHeatMap', this, {
        customProp1: 'test1',   //如果需要添加自定义属性需要将 SDK 升级到 1.13.7 及以上版本。
        customProp2: 'test2'
      }, function() {
        console.log('callback');
      });
  });

</script>

3.3 视区停留事件($WebStay)

有效停留:关注网页区域不滚动,期间鼠标可以移动,可以点击等操作。 有效停留时间:停留时间超过规定的时间,javascript sdk 中默认为 4 秒, 这个参数可以设置。

如果发生页面滚动时候,之前的页面停留是有效停留,也就是超过默认的 4 秒或者自定义的时间,javascript sdk 就会发送一次 页面停留事件。

$WebStay 的触发条件: 神策 $WebStay 事件的采集是基于在 window 上绑定的 scroll 事件,如果页面滚动是绑定在 div 上,则无法采集。

4. 预置属性含义解释

参考文档 预置属性

5. 常见问题

5.1 没有点击事件,控制台也看不到打印的数据

神策的点击事件是监听在 'document' 上的,如果阻止了事件的冒泡,就采集不到元素点击事件了。
例如:下面的情况,点击 id 为 one 的标签,就无法触发神策预置的元素点击事件。

$("#one").click(function(event) {
    event.stopPropagation();
});
//或者
$("#one").click(function(event) {
    return false;
});

检测是否阻止了冒泡的方法,在Chrome 浏览器开发者工具控制台上对 document 对象绑定一个点击事件,点击这个按钮看能不能触发,如果不能触发,则阻止了冒泡

document.addEventListener('click',function(){
    console.log(123);
});

5.2 $WebClick 事件,预置属性说明

需要客户设置才能采集到的预置属性。 如果客户的神策 SDK 默认采集的标签下列属性都有,那么神策可以默认采集,如果客户的标签缺少其中的某个属性,那么这一条数据的这几个预置属性会为 未知

<a href="https://www.sensorsdata.cn" class="mnav" name="sensorsnews" id="news">神策新闻</a>

元素 ID:news
元素内容:神策新闻
元素名字:sensorsnews
元素样式名:mnav
元素类型:a
元素链接地址:https://www.sensorsdata.cn

5.3 如何给 $WebClick 增加自定义属性

// 下面演示多个标签(class 名不同)被点击时触发预置的元素点击事件

<div class="aa">提交订单</div>
<img src="https://www.sensorsdata.cn" class="bb">图片

方案一,参考本章第 3 节,heatmap 参数的 custom_property 属性。
//使用 heatmap.custom_property 设置筛选规则后自动增加自定义属性,给标签添加同一属性,例:data="test"

<div class="aa" data="test" >提交订单</div>
<img src="https://www.sensorsdata.cn" class="bb" data="test" >图片

heatmap: {
  custom_property: function(element_target) {
    //比如您需要给有 data=test 属性的标签的点击事件增加自定义属性 
    if(element_target.getAttribute('data') === 'test'){
      return {
        customProp1: 'test1',
        customProp2: 'test2'
      };
    }
  }
}

方案二,参考本章第 3.1 节,trackHeatMap 及 trackAllHeatMap 方法的使用。

针对非默认标签(非 a, input, button, textarea 标签)的自定义属性,手动触发 trackHeatMap 方法时增加自定义属性

SDK 更新日志

$('.aa,.bb').on('click', function() {
  sensors.quick('trackHeatMap', this, {
    customProp1: 'test1',   //如果需要添加自定义属性需要将 SDK 升级到 1.13.7 及以上版本。
    customProp2: 'test2'
  }, function() {
    console.log('callback');
  });
});

所有元素的自定义属性,手动触发 trackAllHeatMap 方法时增加自定义属性

$('.aa,.bb').on('click', function() {
  sensors.quick('trackAllHeatMap', this, {
    customProp1: 'test1',   //如果需要添加自定义属性需要将 SDK 升级到 1.13.7 及以上版本。
    customProp2: 'test2'
  }, function() {
    console.log('callback');
  });
});

5.4 点击会跳转页面的按钮,预置采集的 $WebClick 可能会丢失

详细介绍请参考文档: 关闭页面发数据