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