1. Web JS SDK 使用说明

在使用前,请先阅读 数据格式 的介绍。
如想查看 SDK 历史版本,请参考 SDK 更新日志

1.1. 获取和引入神策分析 SDK

详细参考:Web 快速使用

目前 Web JS SDK 压缩文件 sensorsdata.min.js 大小约为 20kb。

当神策服务器异常时,Web JS SDK 发送的图片数据请求无法及时响应,会导致 window.onload 无法生效,所以建议不要将页面渲染的代码放在 window.onload 中。如果一定要使用 window.onload 的话,建议将 send_type 参数设置为 'ajax',使用 ajax 发送数据。

1.1.1. 参数配置

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

1.1.1.1. 普通参数

普通参数对代码埋点有效,下面是必填参数:

  • sdk_url: sensorsdata.min.js 文件的地址,请从 GitHub 获取并且放在你们自己网站目录下。
  • name: SDK 使用的一个默认的全局变量,如定义成 sensors 的话,后面可以使用 sensors.track() 用来跟踪信息。为了防止变量名重复,你可以修改成其他名称比如 sensorsdata 等 。
  • server_url: 数据接收地址。 
  • heatmap_url: heatmap.min.js 文件的地址,请从 GitHub 获取并且放在你们自己网站目录下。神策分析中点击分析及触达分析功能代码,代码生成工具会自动生成。如果神策代码中 sensorsdata.min.js 版本是 1.13.1 及以前版本,这个参数须配置,高于此版本不需要配置。
  • web_url: 神策分析后台地址,神策分析中点击分析及触达分析功能会用到此地址,代码生成工具会自动生成。如果神策后台版本及 sensorsdata.min.js 均是 1.10 及以上版本,这个参数不需要配置。如果有需要,也可以修改可选参数。   
  • heatmap:点击图配置。配置成 {} 表示开启 $WebClick 和 $WebStay 的自动采集,默认 $WebClick 只采集 a,button,input 三个 dom 元素的点击事件。 详细配置参考:Web 全埋点
  • cross_subdomain: 设置成 true 后,表示在根域下设置 cookie 。也就是如果你有 zhidao.baidu.comtieba.baidu.com 两个域,且有一个用户在同一个浏览器都登录过这两个域的话,我们会认为这个用户是一个用户。如果设置成 false 的话,会认为是两个用户。默认 true。
  • show_log: 设置 true 后会在网页控制台打 logger,会显示发送的数据,设置 false 表示不显示。默认 true。
  • use_client_time: 因为客户端系统时间的不准确,会导致发生这个事件的时间有误,所以这里默认为 false ,表示不使用客户端时间,使用服务端时间,如果设置为 true 表示使用客户端系统时间。如果你在属性中加入 {$time: new Date()} ,注意这里必须是 Date 类型,那么这条数据就会使用你在属性中传入的这个时间。
  • source_channel: 默认获取的来源是根据 utm_source 等 ga 标准来的,如果使用百度统计的 hmsr 等参数,需在此字段中加入对应参数,参数必须是数组,例如:['hmsr']。使用网页通用渠道添加自定义属性时,需将对应的自定义属性名添加到此字段。
  • source_type: 自定义搜索引擎流量,社交流量,搜索关键词。[详细配置参考] Web 渠道参数
  • max_string_length: 通用字符串最大长度,超过部分会被截取丢弃(由于超过 7000 的字符串会导致 url 超长发不出去,所以限制长度),默认值:500。
  • send_type: 默认值 'image' 表示使用图片 get 请求方式发数据,( 神策系统 1.10 版本以后 ) 可选使用 'ajax' 和 'beacon' 方式发送数据,这两种默认都是 post 方式, beacon 方式兼容性较差。
  • callback_timeout: 默认值 200 ,单位毫秒,表示回调函数超时时间,如果数据发送超过 callback_timeout 还未返回结果,会强制执行回调函数。(SDK 版本 1.11.6 以后支持)
  • queue_timeout: 默认值 300 ,单位毫秒,表示队列发送超时时间,如果数据发送时间超过 queue_timeout 还未返回结果,会强制发送下一条数据。(SDK 版本 1.11.6 以后支持)
  • datasend_timeout: 默认值 3000 ,单位毫秒,表示数据发送超时时间,如果数据发送超过 datasend_timeout 还未返回结果,会强制取消该请求。(SDK 版本 1.11.6 以后支持)
  • preset_properties: 是否开启 $latest 最近一次相关事件属性采集以及配置 $url 作为公共属性,默认值为一个对象。(SDK 版本 1.14.10 及以后支持) 详细配置参考:Web 渠道参数
  • is_track_single_page: 默认值 false,表示是否开启单页面自动采集 $pageview 功能,SDK 会在 url 改变之后自动采集web页面浏览事件 $pageview。(SDK 版本 1.12.18 以后支持)
  • batch_send: 默认值 false,表示不开启批量发送,设置为 true 表示开启批量采集,并且使用以下默认值 { datasend_timeout: 6000, 一次请求超过多少秒的话自动取消,防止请求无响应。send_interval: 6000, 间隔几秒发一次数据。one_send_max_length: 6 一次请求最大发送几条数据,防止数据太大 },也可以直接以 {} 的方式自定义这几个参数的值,详细参考:批量发送

1.2. 如何标识用户

在进行任何埋点之前,都应当先确定如何标识用户。Distinct ID 是用来标识用户的,是一段唯一的字符串,默认情况下 Web JS SDK 会自动生成一个 Distinct ID 并永久保存在浏览器中的 Cookie 中(我们暂时称这个为 cookie_id),如果你已知了真实的用户 id ,你可以通过 sensors.login("你们服务端分配给用户具体的登录 ID",function(){//回调函数}) 来发送关联 cookie_id 的事件,同时这个方法还会用"你们服务端分配给用户具体的登录 ID"替换浏览器缓存中的 cookie_id

获取 Cookie 中的 Distinct ID :sensors.store.getDistinctId();

由于调用 login 接口之后,Distinct ID 会由匿名 id 变成真实 id,所以我们又提供了一个获取 Cookie 中的 匿名 id 的方法:
前端方式:
增加了获取匿名ID的方法 sensors.quick('getAnonymousID'); 返回匿名 id (SDK 版本 1.13.4 及以上支持),调用这个方法时,可能 Web JS SDK 还未初始化成功,建议将此方法放在下面代码中。

sensors.quick('isReady',function(){

	sensors.quick('getAnonymousID');

});
JS


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

1.2.1. 在登录和注册成功后,调用sensors.login("你们服务端分配给用户具体的登录 ID",function(){//回调函数}) 来标识真实用户

注意:login 方法的回调函数需要 SDK 版本大于等于 1.14.8 才能使用,回调函数和批量发送功能不可同时使用。


通过 sensors.login("你们服务端分配给用户具体的登录 ID",function(){//回调函数}) 来把 SDK 自动生成的 cookie_id 关联成现在传入的 "你们服务端分配给用户具体的登录 ID"。且以后会一直使用这个 "你们服务端分配给用户具体的登录 ID"

1.2.1.1. 我们的 Web JS SDK 从 1.6.9 版本开始支持 sensors.login() 方法。

sensors.login('user1312312123',function(){
	//回调函数的使用需要 SDK 版本大于等于 1.14.8
});
JS


问题1:这行代码放在哪里?
建议放在所有事件前面。也就是在 sdk 载入代码后面,先使用 sensors.login ("如果此时有这个你们服务端分配给用户具体的登录 ID 的话",function(){//回调函数}),然后再用 sensors.quick('autoTrack') 等,这样后续的事件才会使用这个更改后的 真实 id。
问题2:在什么时候调用?
页面登录的时候,只要获取到用户是登录状态,就需要调用。或者 注册流程成功的时候。
问题3:sensors.login 和 sensors.identify 有什么区别?
login 用来关联数据库的 id,identify 用来改变匿名 id,可以认为匿名 id 是跟浏览器绑定的。

1.2.2. 使用 sensors.identify 来修改匿名 id

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

这个方法有三种使用方式:

sensors.identify(id): 这个 id 仅对当前页面有效。
sensors.identify(id, true): 会把这个 id 保存在浏览器的 cookie 中,该域名下的页面都会默认使用这个 id。该方法应用较多。
sensors.identify(): 重新生成一个新的 cookie_id,该方法一般情况不使用。


1.2.3. 使用 sensors.logout 切换到之前的匿名 id

通过 sensors.logout() 来永久改变当前的 Distinct ID 为 cookie_id 。

sensors.logout(); // 取消当前 login 的 id,改成最初自动生成的 cookie_id
sensors.logout(true); // 取消当前 login 的 id,重新生成一个新的 cookie_id
JS


问题1,这个在什么时候使用?
在你用过 sensors.login 后,在一个浏览器有多个用户登录的时候,你想在用户退出后改变当前的 Distinct ID

1.3. 事件追踪

1.3.1. 事件公共属性

1.3.1.1. 静态公共属性

sensors.registerPage(object)
JS

如果某个事件的属性,在所有事件中都会出现,可以通过 registerPage 方法将该属性设置为事件公共属性。例如电商产品中的用户等级,常作为事件的公共属性。sensors.registerPage({gender:"male"}) 。这样的话,下次你在使用 sensors.track("index_visit") 时等同于 sensors.track("index_visit", {gender:"male"})

再比如想在当前页面的后续事件中都注入当前页面地址及前向地址属性,只针对当前页面有效的方法如下:

<script>
(function(para) {
	var p = para.sdk_url, n = para.name, w = window, d = document, s = 'script',x = null,y = null;
	w['sensorsDataAnalytic201505'] = n;
	w[n] = w[n] || function(a) {return function() {(w[n]._q = w[n]._q || []).push([a, arguments]);}};
	var ifs = ['track','quick','register','registerPage','registerOnce','trackSignup', 'trackAbtest', 'setProfile','setOnceProfile','appendProfile', 	'incrementProfile', 'deleteProfile', 'unsetProfile', 'identify','login','logout','trackLink','clearAllRegister'];
	for (var i = 0; i < ifs.length; i++) {
		w[n][ifs[i]] = w[n].call(null, ifs[i]);
	}
	if (!w[n]._t) {
		x = d.createElement(s), y = d.getElementsByTagName(s)[0];
		x.async = 1;
		x.src = p;
		w[n].para = para;
		y.parentNode.insertBefore(x, y);
	}
})({
	sdk_url: '在 GitHub 下载新版本的 sensorsdata.min.js',
	name: 'sensors',
	server_url:'数据接收地址',
	//heatmap_url神策分析中点击分析及触达分析功能代码,代码生成工具会自动生成。如果神策代码中 `sensorsdata.min.js` 版本是 1.13.1 及以前版本,这个参数须配置,高于此版本不需要配置。
	heatmap_url: "在 GitHub 下载新版本的 heatmap.min.js",
	//web_url 神策分析中点击分析及触达分析功能会用到此地址,代码生成工具会自动生成。如果神策后台版本及 `sensorsdata.min.js` 均是 1.10 及以上版本,这个参数不需要配置。
	web_url:"神策分析后台地址",
	heatmap: {}
});
//以异步加载 SDK 为例,神策 SDK 初始化完成,此时调用设置公共属性的方法,来保证之后的事件都有这两个属性。
sensors.registerPage({
	current_url: location.href,
	referrer: document.referrer
});
sensors.quick('autoTrack'); //这时候,这个 Web 页面浏览事件,就会带有 current_url 和 referrer 这些属性。且仅对当前页面有效。
sensors.track('button_A_click'); // 这时候,这个 button_A_click 事件,就会带有 current_url 和 referrer 这些属性。且仅对当前页面有效。
</script>
JS

1.3.1.2. 动态公共属性(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)
    }
})

1.3.2. 全埋点事件追踪

Web 全埋点

1.3.3. 自定义事件追踪

第一次接入神策分析时,建议先追踪 3~5 个关键的事件,只需要几行代码,便能体验神策分析的分析功能。例如:

图片社交产品,可以追踪用户浏览图片和评论事件。
电商产品,可以追踪用户注册、浏览商品和下订单等事件。


神策分析 SDK 初始化成功后,即可以通过 sensors.track(event_name[, properties][, callback]) 记录事件:

event_name: string,必选。表示要追踪的事件名。
properties: object,可选。表示这个事件的属性。
callback: function,可选。表示已经发送完数据之后的回调。


// 追踪浏览商品事件。
sensors.track('ViewProduct', {
	//String 类型
	ProductName: "MacBook Pro", 
	//Number 类型,-9E15 到 9E15 小数点后最多保留 3 位
	ProductPrice: 123.45, 
	//BOOL 类型,true 或 false
	IsAddedToFav: false,
	//List 类型,字符串元素的数组,最大元素个数为 500,其中每个元素使用 UTF-8 编码后最大长度 255 字节
	ProductList:["apple","orange"], 
	//DATETIME 类型,可以直接传 new Date() 或者 传 yyyy-MM-dd HH:mm:ss.SSS / yyyy-MM-dd HH:mm:ss 格式的字符串。
	ViewTime:new Date()
});
JS

1.4. 设置用户属性

为了更准确地提供针对人群的分析服务,可以使用神策分析 SDK 的 setProfile() 等方法设置用户属性,如年龄、性别等。用户可以在留存分析、分布分析等功能中,使用用户属性作为过滤条件,精确分析特定人群的指标。

1.4.1. sensors.setProfile(properties[, callback])

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

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

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


1.4.2. sensors.setOnceProfile(properties[, callback])

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

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

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


1.4.3. sensors.appendProfile(properties[, callback])

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

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

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


1.4.4. sensors.incrementProfile(properties[, callback])

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

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

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


1.4.5. sensors.deleteProfile([callback])

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

callback: function。{可选}

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


1.4.6. sensors.unsetProfile(property[, callback])

删除当前用户的一些属性

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

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


1.5. 高级参数详解

1.5.1. 批量发送

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、use_app_track 和 batch_send 只能选择一个,开启了打通就不能再用批量发送。