piwik custom variables

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;
        }
    }
}

参数解释：

1. index ：表示使用5个自定义变量的中的第几个
2. name：自定义变量名称
3. value：自定义变量值
4. scope：自定义变量的使用范围，包括：

• visit（访客级别）：同一个访客30分钟内在不同的页面都能操作该变量，可以做计算
• page（页面级别）：在当前页面只要页面没有重载就可以获得该变量，即通过别的js事件或是方法是可以获取到该变量的。
• event（事件级别）：在当前页面的只能在一个事件级别里获取该变量，下次事件操作将清空改变量，此时页面并无重载操作。

需要注意的是：如果同一个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来获取那个设置的变量。