1. 概述

如果某个事件的属性,在所有事件中都会出现,可以将该属性设置为事件公共属性。设置公共属性后,之后触发的所有事件,都会自动加上设置的公共属性。

2. Android 公共属性

2.1. Android 设置事件公共属性

可以通过 registerSuperProperties() 设置事件公共属性。
例如将平台类型设置为事件的公共属性,设置方法如下:

// 将'平台类型'作为事件公共属性,后续所有触发事件都会添加上 "PlatformType" 属性,且属性值为 "Android"
try {
	JSONObject properties = new JSONObject();
	properties.put("PlatformType", "Android");
	SensorsDataAPI.sharedInstance().registerSuperProperties(properties);
} catch (JSONException e) {
	e.printStackTrace();
}
JAVA


重复调用 registerSuperProperties 会覆盖之前已设置的公共属性,公共属性会保存在 App 本地存储中。可以通过 unregisterSuperProperty() 删除一个公共属性,使用 clearSuperProperties() 会删除所有已设置的事件公共属性。

当公共属性和事件属性的 Key 冲突时,事件属性优先级最高,它会覆盖公共属性。

注意:请在初始化 SDK 后调用 registerSuperProperties 方法,确保每个事件都会添加已设置的公共属性。

2.2. Android 设置动态公共属性

2.0.1 及以后的版本可以通过 registerDynamicSuperProperties 方法设置动态公共属性,设置之后 SDK 会自动获取 getDynamicSuperProperties 中的属性添加到触发的事件中。

// 初始化 SDK 后,设置动态公共属性
SensorsDataAPI.sharedInstance().registerDynamicSuperProperties(new SensorsDataDynamicSuperProperties() {
	@Override
	public JSONObject getDynamicSuperProperties() {
		try {
			// 比如 isLogin() 是用于获取用户当前的登录状态,SDK 会自动获取 getDynamicSuperProperties 中的属性添加到触发的事件中。
			boolean bool = isLogin();
			return new JSONObject().put("isLogin",bool);
		} catch (Exception e) {
			e.printStackTrace();
		}
	return null;
	}
});
JAVA

3. iOS 公共属性

3.1. iOS 设置事件公共属性

可以通过 registerSuperProperties: 方法设置事件公共属性。
例如将平台类型设置为事件的公共属性,设置方法如下:

// 将'平台类型'作为事件公共属性,后续所有触发事件都会添加上 "PlatformType" 属性,且属性值为 "iOS"
[[SensorsAnalyticsSDK sharedInstance] registerSuperProperties:@{@"PlatformType" : @"iOS"}];
OBJECTIVE-C


重复调用 registerSuperProperties: 会覆盖之前已设置的公共属性,公共属性会保存在 App 本地存储中。可以通过 unregisterSuperProperty: 删除一个公共属性,使用 clearSuperProperties: 会删除所有已设置的事件公共属性。

当公共属性和事件属性的 Key 冲突时,事件属性优先级最高,它会覆盖公共属性。

注意:请在初始化 SDK 后调用 registerSuperProperties 方法,确保每个事件都会添加已设置的公共属性。

3.2.  iOS 设置动态公共属性

1.10.8 及以后版本可以通过 registerDynamicSuperProperties: 方法设置动态公共属性,设置之后 SDK 会自动将设置的动态属性添加到触发的事件中。

[[SensorsAnalyticsSDK sharedInstance] registerDynamicSuperProperties:^NSDictionary<NSString *,id> * _Nonnull{
	//比如 LoginManager 的 isLogin 方法是用于获取 App 当前的登录状态
	BOOL isLogin = [LoginManager isLogin];
	return @{@"isLogin":@(isLogin)};
}];
OBJECTIVE-C


4. JavaScript 公共属性

4.1. JavaScript 设置静态公共属性

如果某个事件的属性,在所有事件中都会出现,可以通过 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','clearAllRegister','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;
	y.parentNode.insertBefore(x, y);
	w[n].para = para;
	}
})({
	sdk_url: '在 github 下载新版本的 sensorsdata.min.js',
	name: 'sensors',
	server_url:'数据接收地址',
	//heatmap_url神策分析中点击分析及触达分析功能代码,代码生成工具会自动生成。如果神策代码中 sensorsdata.min.js 版本是 1.9.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.track('button_A_click'); // 这时候,这个 button_A_click 事件,就会带有current_url和referrer这些属性。且仅对当前页面有效。
</script>
JS


当公共属性和事件属性的 Key 冲突时,事件属性优先级最高,它会覆盖公共属性。

4.2. JavaScript 设置动态公共属性

当设置动态公共属性的时候,注意使用函数类型作为属性值,函数的返回值应当是神策支持的类型,请参考数据格式,否则会被过滤掉。
另外您如果使用了 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"] // 返回元素是字符串的数组
  }
})
JS


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

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


5. 微信小程序公共属性

可以在 app.js 文件引入 sensorsdata.min.js 文件之后, init() 方法调用之前使用 registerApp() 方法设置公共属性。
例如将平台类型设置为事件的公共属性,设置方法如下:

let sensors = require('./utils/sensorsdata.min.js');
// 将'平台类型'作为事件公共属性,后续所有触发事件都会添加上 PlatformType 属性,且属性值为 'miniprogram'
sensors.registerApp({
	PlatformType:'miniprogram'
});
sensors.init();
APP.JS


当公共属性和事件属性的 Key 冲突时,事件属性优先级最高,它会覆盖公共属性。

6. 服务端公共属性

以 Java 端为例。可以通过 registerSuperProperties() 设置公共属性。例如将服务器的应用版本及机房地址设置为事件的公共属性,设置方法如下:

Map<String, Object> properties = new HashMap<String, Object>();
// 服务器应用版本
properties.put("ServerVersion", "1.2");
// 服务器机房地址
properties.put("Location", "BeiJing");
// 设置事件公共属性
sa.registerSuperProperties(properties);
JAVA


设置公共属性后,再通过 track() 追踪事件时,公共属性会被添加到每个事件中,使用 clearSuperProperties() 会删除所有已设置的事件公共属性。

当公共属性和事件属性的 Key 冲突时,事件属性优先级最高,它会覆盖公共属性。