1. SDK 初始化参数

如果使用自动代码生成,一般情况下无需手工修改参数。

参数默认值含义备注
sdk_urlsensorsdata.min.js 文件的地址。请从 GitHub 获取并且放在你们自己网站目录下。
namesa

SDK 使用的一个默认的全局变量,如定义成 sensors 的话,后面可以使用 sensors.track() 用来跟踪信息。为了防止变量名重复,你可以修改成其他名称比如 sensorsdata 等 。


server_url数据接收地址。 
heatmap_url

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

请从 GitHub 获取并且放在你们自己网站目录下。

web_url

神策分析后台地址,神策分析中点击分析及触达分析功能会用到此地址,代码生成工具会自动生成。如果神策后台版本及 sensorsdata.min.js 均是 1.10 及以上版本,这个参数不需要配置;如果需要解决热力图引起的 XSS 漏洞问题,Web SDK 需要升级到 v1.21.13 版本,同时配置此参数。


heatmap

点击图配置。默认配置表示不自动采集元素点击事件和页面停留事件,配置成 {} 表示开启 $WebClick 采集 和 $WebStay 自动采集,默认 $WebClick 只采集 a,button,input ,textarea 四个 dom 元素的点击事件。


cross_subdomaintrue

设置成 true 后,表示在根域下设置 cookie 。也就是如果你有 zhidao.baidu.comtieba.baidu.com 两个域,且有一个用户在同一个浏览器都登录过这两个域的话,我们会认为这个用户是一个用户。如果设置成 false 的话,会认为是两个用户。


show_logtrue设置 true 后会在网页控制台打 logger,会显示发送的数据,设置 false 表示不显示。
use_client_timefalse客户端系统时间的不准确,会导致发生这个事件的时间有误,所以这里默认为 false ,表示不使用客户端时间,使用服务端时间,如果设置为 true 表示使用客户端系统时间。如果你在属性中加入 {$time: new Date()} ,注意这里必须是 Date 类型,那么这条数据就会使用你在属性中传入的这个时间。
source_channel默认获取的来源是根据 utm_source 等 ga 标准来的,如果使用百度统计的 hmsr 等参数,需在此字段中加入对应参数,参数必须是数组,例如:['hmsr']。使用网页通用渠道添加自定义属性时,需将对应的自定义属性名添加到此字段。
source_type
自定义搜索引擎流量,社交流量,搜索关键词。

详细配置参考

max_string_length500通用字符串最大长度,超过部分会被截取丢弃(由于超过 7000 的字符串会导致 url 超长发不出去,所以限制长度)。
send_typebeacon表示使用 beacon 请求方式发数据,可选使用 'image' 图片 get 请求方式发数据。( 神策系统 1.10 版本以后 ) 支持使用 'ajax' 和 'beacon' 方式发送数据,这两种默认都是 post 方式, beacon 方式兼容性较差。
callback_timeout200 ,单位毫秒表示回调函数超时时间,如果数据发送超过 callback_timeout 还未返回结果,会强制执行回调函数。

SDK 版本 1.11.6 以后支持

queue_timeout300 ,单位毫秒表示队列发送超时时间,如果数据发送时间超过 queue_timeout 还未返回结果,会强制发送下一条数据。

SDK 版本 1.11.6 以后支持

datasend_timeout3000 ,单位毫秒表示数据发送超时时间,如果数据发送超过 datasend_timeout 还未返回结果,会强制取消该请求。

SDK 版本 1.11.6 以后支持

preset_properties
是否开启 $latest 最近一次相关事件属性采集以及配置 $url 作为公共属性,默认值为一个对象。

SDK 版本 1.14.10 及以后支持
详细配置参考

is_track_single_pagefalse表示是否开启单页面自动采集 $pageview 功能,SDK 会在 url 改变之后自动采集web页面浏览事件 $pageview。

SDK 版本 1.12.18 以后支持

batch_sendfalse表示不开启批量发送,设置为 true 表示开启批量采集。SDK 版本 1.14.7 以后支持
详细配置参考


2. 获取预置属性

版本要求

Web JS SDK 1.9.13  及以后版本

此方法可获取,页面地址,页面标题,前向地址,SDK 类型及版本,屏幕宽高,最近一次的相关属性,如果服务端需要使用这些属性需要客户自己传输,且这些属性不包括需要后端解析的 ip 及 UA 等属性。

sensors.quick('isReady',function(){
	sensors.getPresetProperties();
});
JS

3. 获取匿名 ID

3.1. 前端方式获取匿名 ID

增加了获取匿名ID的方法 sensors.quick('getAnonymousID'); 返回匿名 id (SDK 版本 1.13.4 及以上支持),调用这个方法时,可能 Web JS SDK 还未初始化成功,建议将此方法放在下面代码中。

sensors.quick('isReady',function(){
	sensors.quick('getAnonymousID');
});
JS

3.2. 后端方式获取匿名 ID

可以在 Cookie 里面找到 key 为 sensorsdata2015jssdkcross 的 value 值然后进行 decodeURIComponent 解码,最后通过 JSON.parse 方法得到一个对象,对象里面的 Distinct ID 即为用户所需要的 (注意,如果前端已经调用过 login 方法,那么此时 Distinct ID 为真实 id,所以需要获取 first_id 字段)。

4. 修改匿名 ID

默认情况下,是把 cookie_id 作为 Distinct ID 的。如果你能取到其他匿名 id(比如设备 id,或者你们自己生成的 cookie_id),可以用 sensors.identify(id, true) 来改变当前的 Distinct ID :

sensors.identify(id, true): 会把这个 id 保存在浏览器的 cookie 中,该域名下的页面都会默认使用这个 id。
JS

5. 设置事件公共属性

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

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

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

5.2. 设置事件动态公共属性

版本要求

Web JS SDK 1.14.15 及以后版本

当设置动态公共属性的时候,注意使用函数类型作为属性值,函数的返回值应当是神策支持的类型,请参考数据格式,否则会被过滤掉。
另外您如果使用了 ES6 语法如箭头函数等,则需要使用编译工具编译后运行。

var i=0
sensors.registerPage({
  index: function() {
    return ++i; // 返回数字
  },
  istrue: function() {
    return i<10 ? true : false; // 返回bool
  },
  isEmptyString: function() {
    return ""; // 返回字符串
  },
  isDate: function() {
    return new Date('December 17, 1995 03:24:00'); // 返回日期类型
  },
  isArrayOfStr: function() {
    return ["1","2","3"] // 返回元素是字符串的数组
  }
})


另外如果函数在异步回调中返回值,这种情况也是会被过滤掉。

sensors.registerPage({
    num:function(){
        setTimeout(()=>{
            return 100
        },500)
    }
})


6. 设置用户属性

6.1. setProfile(properties[, callback])

直接设置用户的属性,如果存在则覆盖。

properties:object,必选。
callback:function,可选。

sensors.setProfile({email:'xxx@xx'});
JS

6.2. setOnceProfile(properties[, callback])

如果不存在则设置,存在就不设置。

properties:object,必选。
callback:function,可选。

sensors.setOnceProfile({email:'xxx@xx'});
JS

6.3. appendProfile(properties[, callback])

给数组属性添加值。通过setProfile只能改变属性的值。如果这个属性是数组类型的,你不想完全改变这个值,只想做添加操作可以使用此方法。

properties:object,必选。
callback:function,可选。

//给 category 增加两个值
sensors.appendProfile({catrgory: ['玉米','白菜']});
//给 category 增加一个值
sensors.appendProfile({catrgory: '玉米'});
JS

6.4. incrementProfile(properties[, callback])

对当前用户的属性做递增或者递减。

properties:object 或者 string,必选。
callback:function,可选。

// 表示 navClick 递减
sensors.incrementProfile({'navClick': -1});
// 表示 navClick 递增2
sensors.incrementProfile({'navClick': 2});
// 直接传入一个属性名,表示递增1
sensors.incrementProfile('navClick');
JS

6.5. deleteProfile([callback])

删除当前用户及他的所有属性。

callback: function。{可选}

//删除当前这个用户及他的所有属性
sensors.deleteProfile();
JS

6.6. unsetProfile(property[, callback])

删除当前用户的一些属性

properties:array 或者 string,必选。
callback:function,可选。

//删除 email 和 location 属性
sensors.unsetProfile(['email','location']);
//删除 email 属性
sensors.unsetProfile('email');
JS

7. 开启数据的批量发送

SDK 版本需 1.14.7 及以上

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

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

//或者
batch_send:{
	datasend_timeout: 6000, //一次请求超过多少毫秒的话自动取消,防止请求无响应。
	send_interval: 6000, //间隔多少毫秒发一次数据。
	one_send_max_length: 6 //一次请求最大发送几条数据,防止数据太大
},
JS


原理:

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

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

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

注意:

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


8. 部分预置属性是否采集(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

9. 关闭页面发送数据

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

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

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

9.1. 改为服务端发送事件

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

9.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 这个参数来筛选结果。

9.3.  callback 回调中跳转页面

神策自定义事件的 track 方法的第三个参数,回调函数,受 callback_timeout 参数影响(callback_timeout: 默认值 200 ,单位毫秒,表示回调函数超时时间,如果数据发送超过 callback_timeout 还未返回结果,会强制执行回调函数)。

正常情况下数据请求返回后,就会执行 callback 方法,但是考虑到网络卡或者死机的情况,设置 callback_timeout 的超时来强制执行 callback。其中有两种不太常见特殊场景需要注意:
1. 不能把时间设置的太长,比如 3s,因为不能保证网络请求一定能返回,这时候就会使用这个 callback_timeout,所以设置这个时间最好在 500ms 左右,可接受的范围内。
2. 不能把时间设置的太短,比如 100ms,因为可能请求还没发成功,就执行 callback 了,正常情况下没问题,但是如果 callback 里是页面跳转的操作,那这个数据可能会丢失。

// 点击链接
$('a').on('click',function(e,url){
	e.preventDefault(); // 阻止默认跳转
	sensors.track('a_click', {}, function(){
		location.href = url;
	}); //把跳转操作加在callback里
});
JS

9.4. 使用 setTimeout:

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

9.5. beacon 的方式发送数据

// 要求 sdk 版本在 v1.15.26 及以上版本
// 开启 beacon 方案的需要在 SDK 初始化代码中增加配置(配置位置与 server_url 平级)如下:
send_type:'beacon',
use_client_time:true,
...
server_url: 'xxx'
JS

这三种方式,第一种从根本上解决问题,将事件进行转换。推荐使用。
第二种需要阻止默认事件,对浏览器兼容性好。可以尝试。
第三种方式,在网页关闭情况下发送数据效果很好,不过需要较新的浏览器才可以支持。

  • 如果检测到浏览器不支持 beacon 时,会自动降级为使用 img 发送数据


9.6. batch_send 批量发送缓存数据

batch_send: 默认值 false,表示不开启批量发送,设置为 true 表示开启批量采集,并且使用以下默认值 { datasend_timeout: 6000, 一次请求超过多少毫秒的话自动取消,防止请求无响应。send_interval: 6000, 间隔 6 秒发一次数据。one_send_max_length: 6 一次请求最大发送几条数据,防止数据太大 },也可以直接以 {} 的方式自定义这几个参数的值。

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

// 开启批量发送
batch_send:true,
//或者
batch_send:{
	datasend_timeout: 6000, //一次请求超过多少毫秒的话自动取消,防止请求无响应。
	send_interval: 6000, //间隔多少毫秒发一次数据。
},
JS

原理:

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

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

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

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