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 及以上版本,这个参数不需要配置。


heatmap

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


cross_subdomaintrue

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


show_logfalse设置 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 到 1.18.17 支持

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 以后支持


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. 埋点数据的加密功能

为了加强埋点数据的安全性,神策分析支持对埋点数据进行加密,并以密文的形式对数据进行存储和发送。

本功能需要服务端的配合,可以联系神策客户成功/项目经理协助开通服务端解密功能。

开启加密后,如果服务端不支持解密,数据无法入库,会丢失,埋点管理中不会有报错。

版本要求

  • Web JS SDK 1.19.9  及以上版本 
  • Edge v0.3.0 及以上版本
  • SDF 2.3 及以上版本

7.1. SDK 端开启加密

使用加密插件 aes-encryption.min.js ,必须先同步集成和初始化 Web JS SDK,代码示例如下:

// 神策埋点 SDK 初始化
<script charset='UTF-8' src="在 github 下载新版本的 sensorsdata.min.js"></script>
// 引入加密插件
<script src="在 GitHub 下载新版本的 aes-encryption.min.js"></script>
<script>
    var sensors = window['sensorsDataAnalytic201505'];
    sensors.init({
        server_url: "数据接收地址"  
    });
   // k、khash 数据类型为 String,kid 数据类型为 Number
   sensors.use('AesEncryption', {
      k:'加密密钥', 
      kid: '加密编号',
      khash: '密钥哈希值'
  });
  sensors.quick('autoTrack'); 
</script>
JS

7.2. 获取加密密钥

登录神策服务器,执行以下命令:

# 1、生成对称密钥命令
sh /sensorsdata/main/program/edge/edge/bin/generate_web_symmetric_key.sh -t AES
# 2、生成密钥后需要重启 Edge 模块才能生效
spadmin restart -p edge -m edge
POWERSHELL

8. 物品元数据上报

在神策推荐项目中,客户需要将物品元数据上报,以开展后续推荐业务的开发与维护。Web SDK 提供了设置与删除物品元数据的方法。

item_id(物品 ID ) item_type (物品所属类型)共同组成了一个物品的唯一标识。所有的 item 系列方法都必须同时指定物品 ID 及物品所属类型这两个参数,来完成对物品的操作。

版本要求

  • Web JS SDK 1.18.12  及以后版本

8.1. setItem(item_type,item_id,properties)

直接设置一个物品,如果已存在则覆盖。除物品 ID 与物品所属类型外,其他物品属性需在 properties 中定义。

物品属性中,属性名称与属性值的约束条件与事件属性相同,详细说明请参考 数据格式

item_type:string,必选。

item_id:string,必选。

properties:object,可选。

sensors.setItem("food","2",{name:"玉米",flavour:"甜"});
JS

8.2. deleteItem(item_type,item_id)

如果物品不可被推荐需要下线,删除该物品即可,如不存在则忽略。

除物品 ID 与 物品所属类型外,不解析其他物品属性。

item_type:string,必选。

item_id:string,必选。

sensors.deleteItem("food","2");
JS

9. 页面浏览时长

页面浏览时长是网站分析中很常见的一个指标,用于反映用户在某些页面上浏览时间的长短,体现了用户对网站的黏性。

目前该功能不支持单页面浏览时长的采集

版本要求

  • Web JS SDK 1.18.14  及以后版本
  • SCA v0.5.10375 及以上版本

9.1. 代码示例

// 神策埋点 SDK 初始化
<script charset='UTF-8' src="在 github 下载新版本的 sensorsdata.min.js"></script>
<script>
    var sensors = window['sensorsDataAnalytic201505'];
    sensors.init({
        server_url: "数据接收地址",
        is_track_single_page:true, // 单页面配置,默认开启,若页面中有锚点设计,需要将该配置删除,否则触发锚点会多触发 $pageview 事件
        use_client_time:true, 
        send_type:'beacon',
        heatmap: {
            //是否开启点击图,default 表示开启,自动采集 $WebClick 事件,可以设置 'not_collect' 表示关闭。
            clickmap:'default',
            //是否开启触达图,not_collect 表示关闭,不会自动采集 $WebStay 事件,可以设置 'default' 表示开启。
            scroll_notice_map:'default'
        }  
    });
    sensors.quick('autoTrack');
    sensors.use('PageLeave');
</script>
JS

9.2. API 说明

option: 页面浏览时长配置参数。类型: Object,可选。

  • custom_props:页面浏览时长自定义属性。   类型:Object,可选。
  • heartbeat_interval_time:心跳记录刷新时间。 类型:Number ,单位:秒 ,默认:5,范围:大于 0,可选。
sensors.use('PageLeave'[, option]);
JS

示例:

sensors.use('PageLeave', { heartbeat_interval_time: 5 }) // 设置页面浏览时长心跳记录刷新时间为 5 秒。
sensors.use('PageLeave', { custom_props: { page_title: '我的标题' }, heartbeat_interval_time: 5 }) // 设置页面浏览时长自定义属性 page_title 为 '我的标题',并设置页面浏览时长心跳记录刷新时间为 5 秒。
JS

10. 开启数据的批量发送

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


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

12. 关闭页面发送数据

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

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

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

12.1. 改为服务端发送事件

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

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

12.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

12.4. 使用 setTimeout:

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

12.5. beacon 的方式发送数据

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