piwik custom variables 是一个功能非常强大的自定义变量跟踪方案，多用于基于访客或是页面级别的变量跟踪。piwik默认最多可以添加5个自定义变量。
使用方式是在客户端脚本里添加如下片断
_paq.push(['setCustomVariable',
// Index, the number from 1 to 5 where this custom variable name is stored
1,
// Name, the name of the variable, for example: Gender, VisitorType
"Gender",
// Value, for example: "Male", "Female" or "new", "engaged", "customer"
"Male",
// Scope of the custom variable, "visit" means the custom variable applies to the current visit
"visit"
]);
查看setCustomVariable源码如下
/**
* Set custom variable within this visit
*
* @param int index
* @param string name
* @param string value
* @param string scope Scope of Custom Variable:
* - "visit" will store the name/value in the visit and will persist it in the cookie for the duration of the visit,
* - "page" will store the name/value in the next page view tracked.
* - "event" will store the name/value in the next event tracked.
*/
setCustomVariable: function (index, name, value, scope) {
var toRecord; if (!isDefined(scope)) {
scope = 'visit';
}
if (!isDefined(name)) {
return;
}
if (!isDefined(value)) {
value = "";
}
if (index > 0) {
name = !isString(name) ? String(name) : name;
value = !isString(value) ? String(value) : value;
toRecord = [name.slice(0, customVariableMaximumLength), value.slice(0, customVariableMaximumLength)];
// numeric scope is there for GA compatibility
if (scope === 'visit' || scope === 2) {
loadCustomVariables();
customVariables[index] = toRecord;
} else if (scope === 'page' || scope === 3) {
customVariablesPage[index] = toRecord;
} else if (scope === 'event') { /* GA does not have 'event' scope but we do */
customVariablesEvent[index] = toRecord;
}
}
}
参数解释：
- index ：表示使用5个自定义变量的中的第几个
- name：自定义变量名称
- value：自定义变量值
- scope：自定义变量的使用范围，包括：
需要注意的是：如果同一个scope的情况下，相同的index值如果先后被设置了不同的name，value，那么后设置的将会覆盖前面的。但是如果scope范围不同的话则无影响。
如果三个scope同时都设置了值也是可以的，因为piwik在发送请求时visit级别才用到的是_cvar参数，page是用的是cvar，而event才用的是e_cvar，例如下面的例子
_paq.push(['setCustomVariable',1,"GenderX","MaleX","visit"]);
_paq.push(['setCustomVariable',1,"GenderY","MaleY","page"]);
_paq.push(['setCustomVariable',1,"GenderZ","MaleZ","event"]);
/*cvar={"1":["GenderXXX","MaleXXX"]}&_cvar={"1":["Gender","Male"]}*/
_paq.push(['trackPageView']);
请求发送的参数是
cvar={"1":["GenderY","MaleY"]}&e_cvar={"1":["GenderZ","MaleZ"]}&_cvar={"1":["GenderX","MaleX"]}
当然index是可以改变的，范围1-5，这里只是为了演示piwik针对相同index不同级别的scope是如何处理的而已。
删除一个自定义变量请使用下面的方法
_paq.push(['deleteCustomVariable', 1, "visit"]);
获取自定义变量
var customVariable = this.getCustomVariable( 1, "visit" );
如果自定义变量不存在会返回false
另外在使用visit级别的时候，如果要在跨页面或是页面刷新后能获取之前设置的变量，需要在
_paq.push(['trackPageView']);
前添加下面的代码
_paq.push(['storeCustomVariablesInCookie']);
这是因为visit跨页面访问自定义变量是通过存储cookie来是实现的，只有把变量存储到了cookie，在其他的页面或是刷新后才能通过getCustomVariable来获取那个设置的变量。