1. 属性插件化

  • SDK 版本需 1.25.5 及以上
  • 属性插件化是神策 Web SDK 提供用于修改埋点事件属性的高级功能,用户可通过属性插件化功能实现对指定事件(或所有事件)的属性进行新增、修改和删除。

1.1. 接口介绍

SDK 提供了 registerPropertyPlugin 方法,通过该方法传入自定义的属性插件对象给指定的事件添加、修改或删除属性。

自定义属性插件对象介绍:

方法名描述示例
properties(data)

用于对属性进行修改,data 为发送前的完整数据。

data 包括 SDK 采集的所有数据类型:

item_set 、

item_delete、

profile_set、

profile_set_once、

profile_append、

profile_increment、

profile_delete、

profile_unset、track、

track_signup。


可配置该方法中对待发送数据 data 进行属性的添加、删除、修改操作。

{
	properties:function(data){
	  // 添加
	  // data.properties.hello = 'world'
	  
	  // 修改
	  // data.properties.$title = 'new title'
	  
	  // 删除
	  // delete data.properties.$screen_width		
	}
}
JS
isMatchedWithFilter(data)

用于对数据进行筛选,data 为发送前的完整数据。

同上面 data 包括所有数据类型。


如果配置了该方法,仅当该方法返回 true 时,配置的 properties 方法才会得到执行。


如果不配置该方法,则配置的 properties 方法始终执行。

{
	isMatchedWithFilter:function(data){
		// 筛选事件名为 $SignUp 的事件
		if(data.event === '$SignUp'){
			return true;
		}

		// 筛选在页面标题为 home 的事件
		if(data.properties.$title === 'home'){
			return true;
		}
		
		// 其他事件不会执行 properties 方法
		return false;
	}
}
JS

1.2. 使用示例

  • 常用方法:修改事件名为 $pageview 下的 $url 属性

    sensors.registerPropertyPlugin({
      isMatchedWithFilter:function(data){
    	return data.event === "$pageview";
      }
    
      properties:function(data){
    	data.properties['$url'] = 'http://xxx';
      }
    });
    JS
  • 常用方法:删除所有事件中的 platform 属性

    sensors.registerPropertyPlugin({
      isMatchedWithFilter:function(data){
    	return data.type === 'track';
      }
    
      properties:function(data){
    	delete data.properties['platform'];
      }
    });
    JS
  • 注意:需要先做事件筛选,再做属性修改。因为 profile、item 等类型的数据也是可以被修改的。

    sensors.registerPropertyPlugin({
      isMatchedWithFilter:function(data){
    	return data.type.slice(0, 4) === 'item' ||  data.type.slice(0, 7) === 'profile';
      }
      properties:function(data){
    	delete data.properties['aaa'] = 'bbb';
      }
    });
    JS
  • 对所有类型数据,修改属性值。注意:这种用法一般情况下是错误的,会导致所有数据(包括 profile、item 等)都被修改,引发意想不到的情况

    sensors.registerPropertyPlugin({
        properties:function(data){
        	data.properties['aaa'] = 'bbb';
      }
    });
    JS
  • 直接在 properties 里进行筛选和属性修改也是可以的

    sensors.registerPropertyPlugin({
      properties:function(data){
    	if(data.event === '$pageview'){
     		data.properties['$url'] = 'http://xxxx';
    	}
      }
    });
    JS

2. 开启数据的批量发送

SDK 版本需 1.14.7 及以上

// 默认不开启批量发送
batch_send:false,

// 开启批量发送
batch_send:true,

//或者
batch_send:{
	datasend_timeout: 6000, //一次请求超过多少毫秒的话自动取消,防止请求无响应。
	send_interval: 6000, //间隔多少毫秒发一次数据。
   	storage_length: 200 // 存储 localStorage 条数最大值,默认:200 。如 localStorage 条数超过该值,则使用 image 方式立即发送数据。v1.24.8 以上支持。
 },
JS


写入策略:

触发事件就写入 localStorage,localStorage 的兼容性请 [参考文档],如果浏览器不支持 localStorage,还是使用实时发送数据的方式。

发送策略:

定时触发发送,或者,遇到 $pageview(或者使用 quick('autoTrack'); 方法)和 $SignUp 也会立即存储并且发送。

重复策略:

必须请求 success 后,才会删除数据,不然会一直请求,直到数据满一定数量。


注意事项:

  • 批量发送功能和回调函数功能不可同时使用,比如 track 加了 callback ,使用批量发送后 callback 不会执行
  • 批量发送默认使用跨域 ajax 的方式发送数据。用客户端系统时间标识数据,如浏览器不支持跨域 ajax 发送数据,还是默认使用 img 且实时发送数据的方式。 
  • 如果 localStorage 里已经存了超过 200 条数据,会导致批量发送功能失效,localStorage 中只保存这 200 条数据,新产生的数据使用 img 且实时发送数据的方式。当进入同域名的新页面时,会自动检查缓存中是否有数据,如果有会继续发送缓存的数据。
  • app_js_bridge 和 batch_send 只能选择一个,开启了打通就不能再用批量发送。

3. 部分预置属性是否采集( preset_properties )相关参数

神策 SDK 采集的最近一次相关的属性会存储在浏览器的 Cookie 中,如果对 Cookie 存储大小有要求,可有选择的采集下列属性,
可配置是否将 $url 和 $title 作为公共属性。
( 1.12.18 版本以上,1.14.10 版本以下的相似功能的 SDK 使用的配置 is_track_latest 已做兼容处理 )

下面配置需要放在初始化配置中,与 server_url 平级,需要 Web JS SDK 版本是 1.14.10 及以上版本

//子配置项 true 表示采集,false 表示不采集,未设置的参数取默认值。
preset_properties: {
	//是否采集 $latest_utm 最近一次广告系列相关参数,默认值 true。
	latest_utm:true,
	//是否采集 $latest_traffic_source_type 最近一次流量来源类型,默认值 true。
	latest_traffic_source_type:true,
	//是否采集 $latest_search_keyword 最近一次搜索引擎关键字,默认值 true。
	latest_search_keyword:true,
	//是否采集 $latest_referrer 最近一次前向地址,默认值 true。
	latest_referrer:true,
	//是否采集 $latest_referrer_host 最近一次前向地址,1.14.8 以下版本默认是true,1.14.8 及以上版本默认是 false,需要手动设置为 true 开启。
	latest_referrer_host:false,
	//是否采集 $latest_landing_page 最近一次落地页地址,默认值 false。
	latest_landing_page:false,
	//是否采集 $url 页面地址作为公共属性,1.16.5 以下版本默认是 false,1.16.5 及以上版本默认是 true。
	url: true,
	//是否采集 $title 页面标题作为公共属性,1.16.5 以下版本默认是 false,1.16.5 及以上版本默认是 true。
	title: true,
}
JS

4. 关闭页面发送数据

一些浏览器比如 iOS 系统的 Safari,如果在页面关闭时上报事件信息,该上报请求可能会失败。比如点击按钮时触发了页面跳转,则跳转前页面上的信息存在上报失败的可能。

正常情况下,Web JS SDK 丢数据概率不超过 5%,但是在关闭页面的情况下,丢失率会增加。

针对此问题,可以选择下面几种解决方式:

4.1. 改为服务端发送事件

如果是关键的点击,需要准确的采集,比如支付等事件是在关闭页面时发送,建议在服务端中埋点采集。

4.2. 采集跳转后页面的 $pageview 事件

用户点击 href 属性为 www.xxx.com 的 a 标签,触发 $WebClick 事件或者用户自定义的 track 事件,这时页面会进行跳转。可能数据未发送成功,页面已经跳转到 www.xxx.com ,会造成数据的的丢失。

方案:给 a 标签的 href 属性添加某个参数,例如 www.xxx.com?urlfrom=123 ,当页面跳转到 www.xxx.com?urlfrom=123 后,采集这个页面的 $pageview 事件,在神策后台中查看 Web 浏览事件,根据 url 是否包含 urlfrom 这个参数来筛选结果。

4.3. 使用 setTimeout:

// 点击链接
function targetLinkIcon( url ){
	//延迟跳转页面,给 SDK 发送数据提供时间
	setTimeout(function(){
		window.location.href = url; 
	},500);
	//神策自定义事件的方法
	sensors.track('demo',{});
}
JS

4.4. beacon 的方式发送数据

// 要求 sdk 版本在 v1.15.26 及以上版本
// 开启 beacon 方案的需要在 SDK 初始化代码中增加配置(配置位置与 server_url 平级)如下:
send_type:'beacon',
use_client_time:true,
...
server_url: 'xxx'
JS
  • 如果检测到浏览器不支持 beacon 时,会自动降级为使用 img 发送数据

5. 单页面中事件的自动采集

单页面中事件的自动采集,可参考 Demo

5.1. Web 页面浏览事件采集

5.1.1. 自动模式

配置参数 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
//注意:如果进首页不会自动 redirect 时,sa.quick('autoTrack') 是需要的,否则不需要。
JS


SDK 版本大于等于 1.14.1 的 is_track_single_page 参数增加 function(){} 的配置,必须 return 一个值。

  • 配置一:return true 表示当前页面会发送数据。
  • 配置二:return false 表示不会发数据。
  • 配置三:return {} 对象,表示会把对象的属性新增到当前 $pageview 里。

使用方法示例:

is_track_single_page : function (){
	return true 时候,使用默认发送的 $pageview
	return false 时候,不执行默认的 $pageview
	return {} 时候,把对象中的属性,覆盖默认 $pageview 里的属性。
}
//注意:如果进首页不会自动 redirect 时,sa.quick('autoTrack') 是需要的,否则不需要。
JS

必须保证切换页面前神策 Web JS SDK 的已经执行,否则的话可能第一次切换页面不会触发 $pageview。

5.1.2. 手动模式

在页面切换的时候,手动调用 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')。
JS


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

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