开发者文档-云眼AB测试

云眼 JavaScript API 参考

以下是JavaScript API的完整参考,包括数据对象API函数

数据对象

对象 window['eyeofcloud'].data 包含了有所有关于当前用户和正在运行的优化方案的信息。

自定义标签

window['eyeofcloud'].data.customTags

给出一个对象,其中包含发送给云眼使用自定义标签功能的所有键值对。

优化方案

优化方案对象

window['eyeofcloud'].data.experiments

该对象包含了所有优化方案的信息。该对象的键是优化方案的ID,这个ID可以在编辑器的诊断分析中查看。

优化方案代码

window['eyeofcloud'].data.experiments[experimentId].code

给出优化方案的全局js代码,这个代码在该优化方案的所有优化版本上都会执行。

优化方案激活模式

window['eyeofcloud'].data.experiments[experimentId].manual

给出一个布尔值,表示优化方案是否是手动激活的优化方案。

优化方案名称

window['eyeofcloud'].data.experiments[experimentId].name

给出优化方案的名称。

优化方案section ID

window['eyeofcloud'].data.experiments[experimentId].section_ids

如果是多变量优化方案,则包含优化方案的section ID。

优化方案优化版本号

window['eyeofcloud'].data.experiments[experimentId].variation_ids

给出一个数组,包含了该优化方案的所有优化版本号。

section

section 对象

window['eyeofcloud'].data.sections

此对象包含有关所有项目文件section的信息,按section ID进行索引。section ID可以在诊断报告中找到。只有多变量优化方案包含section。

section 名称

window['eyeofcloud'].data.sections[variationId].name

这包含该section的名称。

section 变化ID

window['eyeofcloud'].data.sections[variationId].variation_ids

这是一个包含此section的变体ID的数组。

状态

状态对象

window['eyeofcloud'].data.state

给出云眼系统的当前状态,包括已激活的优化版本号、用户抽签情况等等。

启动的优化方案

window['eyeofcloud'].data.state.activeExperiments

给出一个数组,包含所有已经启动的优化方案ID。

重定向优化方案

window['eyeofcloud'].data.state.redirectExperiment

如果在之前的页面中包含了一个具有重定向的优化版本,那么这个对象就会被定义。如果没有重定向发生,这个对象是 undefined。当重定向确实发生时,对象包含:

优化版本映射表

window['eyeofcloud'].data.state.variationMap

给出一个哈希表,键是已经激活了的优化方案ID(包括所有之前激活过的优化方案),其值是这些优化方案选中的优化版本的数组序号。

优化版本号映射表

window['eyeofcloud'].data.state.variationIdsMap

给出一个哈希表,键是已经激活了的优化方案ID(包括所有之前激活过的优化方案),其值是这些优化方案选中的优化版本号形成的数组。

优化版本名称映射表

window['eyeofcloud'].data.state.variationNamesMap

给出一个哈希表,键是已经激活了的优化方案ID(包括所有之前激活过的优化方案),其值是这些优化方案选中的优化版本的名称。

优化版本

优化版本对象

window['eyeofcloud'].data.variations

给出一个对象,包含了所有优化版本的信息,并按其优化版本号进行索引。优化版本号可以在诊断报告中查到。

优化版本名称

window['eyeofcloud'].data.variations[variationId].name

给出优化版本的名称。

优化版本代码

window['eyeofcloud'].data.variations[variationId].code

给出优化版本的JavaScript代码。

访客

访客对象

window['eyeofcloud'].data.visitor

给出访客的所有信息。

访客受众

window['eyeofcloud'].data.visitor.audiences

给出一个以受众ID为键的对象,值是一个布尔值,如果访客符合受众条件,则为true。不会列出所有受众群体。

访客浏览器

window['eyeofcloud'].data.visitor.browser

给出访客正在使用的浏览器类型。选项包括“Firefox”,“Google Chrome”,“Internet Explorer”,“Opera”和“Safari”。如果云眼不识别浏览器,将给出一个空字符串。

访客维度值

window['eyeofcloud'].data.visitor.dimensions

一个以dimensionId为关键字的对象,以及一个维度值(如果有的话)作为值的字符串。如果访问者没有维度的值,则不会在此对象中显示。

访客地理位置

window['eyeofcloud'].data.visitor.location
window['eyeofcloud'].data.visitor.location.city
window['eyeofcloud'].data.visitor.location.region
window['eyeofcloud'].data.visitor.location.country

给出一个对象,包含访客所处的地理位置信息。包含访问者的城市,区域和国家/地区的名称。

访客来源

window['eyeofcloud'].data.visitor.referrer

给出访客的来源(如果有)。这在功能上等同于document.referer。

访客的操作系统

window['eyeofcloud'].data.visitor.os

给出访客的操作系统。如果操作系统未知,则此字符串为空。

访客第三方数据

window['eyeofcloud'].data.thirdParty

此对象包含来自第三方集成的访问者的信息。其内容取决于在“云眼”中启用了哪些集成。例如,如果启用了Demandbase集成,可以访问Demandbase的访问者属性,如下所示:

window['eyeofcloud'].data.thirdParty.demandbase.company_name
window['eyeofcloud'].data.thirdParty.demandbase.industry
window['eyeofcloud'].data.thirdParty.demandbase.sub_industry
...

通常来说,要从集成访问第三方 attributeID 属性 integrationID, 请使用以下格式。

window['eyeofcloud'].data.thirdParty.integrationID.attributeID

由于第三方数据不能保证在每个页面视图中都存在,因此请确保代码正确处理引用错误。例如, industry 要从Demandbase集成访问该字段,建议以下代码:

var demandbase = window['eyeofcloud'].data.thirdParty.demandbase || {};
var industry = demandbase.industry || '';
if (industry) {
  // do something
}

有关如何启用第三方集成和访问权限的更多信息,请参阅: 优化集成简介

API函数

在调用云眼的API之前,必须保证下方的代码已经被执行过。这行代码的作用是为了应对云眼的代码还没有完全加载的情况,如果没有加载,所有API都会被缓存到这个数组中,等到代码加载完毕之后,这些API就会被执行。以下是应该使用的代码:

window['eyeofcloud'] = window['eyeofcloud'] || [];

云眼的API不仅能够通过JavaScript来执行,还能够通过get参数来实现,eyeofcloud_function_name=value。通过JavaScript调用的方式通常是用在整个应用的实现里。而get参数的方式最常用于测试和调试。一个常见的例子是通过使用get参数eyeofcloud_opt_out=true来防止用于测试的访问被记录,从而影响结果。网址可能如下所示:

http://www.example.com/page.html?eyeofcloud_opt_out=true

激活

激活所有需要手动激活的优化方案。当调用“activate”时,如果访客符合受众的条件,则会激活这些优化方案。

window['eyeofcloud'] = window['eyeofcloud'] || [];
window['eyeofcloud'].push(["activate"]);

可以激活指定的优化方案。但是访客依旧需要符合受众的条件。

window['eyeofcloud'] = window['eyeofcloud'] || [];
window['eyeofcloud'].push(["activate", experimentId]);

受众

手动将访客分配到指定的受众中去,这种行为会覆盖掉系统内置的判断逻辑。具有较高的优先级。

要把访客添加到受众,请使用:

window['eyeofcloud'] = window['eyeofcloud'] || [];
window['eyeofcloud'].push(['addToAudience', audienceId]);

要把访客从受众中删除,请使用:

window['eyeofcloud'].push(['removeFromAudience', audienceId]);

要把访客从所有受众中删除,请使用:

window['eyeofcloud'].push(['removeFromAllAudiences']);

版本抽签

如果要把访客分配到指定的版本,必须在云眼SDK运行之前调用"bucketVisitor"。同样需要注意的是,通过API分配版本的时候,是不会去检测受众是否匹配的。experimentIdvariationId可在优化方案的诊断报告中查看。

window['eyeofcloud'] = window['eyeofcloud'] || [];
window['eyeofcloud'].push(["bucketVisitor", experimentId, variationId]);

如果要防止pageview事件被触发,请将第三个参数设置为true。

var doNotSendPageviewTracking = true;
window['eyeofcloud'] = window['eyeofcloud'] || [];
window['eyeofcloud'].push(["bucketVisitor", experimentId, variationId, doNotSendPageviewTracking]);

调用此API的其他方式:

// Multivariate experiments should bucket for each section:
window['eyeofcloud'].push(["bucketVisitor", experimentId, variationIdOfSection1]);
window['eyeofcloud'].push(["bucketVisitor", experimentId, variationIdOfSection2]);

// You can also use the variation index:
window['eyeofcloud'].push(["bucketVisitor", experimentId, variationIndex]);

variationIndex 是编辑器中个版本的索引号,索引号是以0为基础的(0为原始版本,1为第一个优化版本,依此类推)。

自定义标签

可以根据有关访问者的信息使用自定义标签进行定位。必须在加载云眼代码段之前调用“customTag”。

window['eyeofcloud'] = window['eyeofcloud'] || [];
window['eyeofcloud'].push(["customTag", tagKey, tagValue]);

还可以同时设置多个标签:

window['eyeofcloud'].push(["customTag", {
  firstKey: firstValue,
  secondKey: secondValue
}]);

如果为相同的标签键设置了多个值,则将使用在云眼代码段加载之前设置的最后一个值。可以通过在云眼代码段加载后检查数据对象上的自定义标签字段来检查实际设置的值。

请注意,为了定位目的,值都将作为字符串进行比较。

延迟事件跟踪

延迟发送跟踪事件,时间有参数指定,单位是毫秒。

window['eyeofcloud'] = window['eyeofcloud'] || [];
window['eyeofcloud'].push(["delayPageviewTracking", 1000]);

维度

可以通过此API为访问者分配维度值,这些值可用于结果页面上的细分或者与受众群体的定位。

为访问者设置维度值:

window['eyeofcloud'].push(['setDimensionValue', dimensionId, 'value']);

'value'要求是一个字符串,最长20个字符(编码)。

要删除现有值,请删除值参数或设值为 null。把访客从分段中移除后,云眼将不再把访客的转化统计到分段的结果中。但如果在移除之前,访客触发了pageview事件的话,该访客的转化仍会被统计到分段的结果中。

禁用

完全禁用优化方案。必须在加载云眼代码段之前调用“disable”。

window['eyeofcloud'] = window['eyeofcloud'] || [];
window['eyeofcloud'].push(["disable"]);

也可以只是停用云眼的事件跟踪:

window['eyeofcloud'].push(["disable", "tracking"]);

日志

告诉云眼将其日志输出到浏览器的控制台。

window['eyeofcloud'] = window['eyeofcloud'] || [];
window['eyeofcloud'].push(["log"]);

还可以使用get参数eyeofcloud_log=true来执行此操作。

设置访客的Cookie的有效期。必须在加载云眼SDK之前调用“setCookieExpiration”。可设置的最小天数为90(约3个月)。

注意:每次访客访问网站时,都会重新设置一些Cookie,这意味着每次设置Cookie时将使用此API调用设置的有效期。

window['eyeofcloud'] = window['eyeofcloud'] || [];
window['eyeofcloud'].push(["setCookieExpiration", 365]);

在上面的示例中,访客的Cookie将在1年后到期。

指示云眼将其Cookie设置在特定子域而不是默认主域。必须先调用“setCookieDomain”才能加载云眼SDK。默认情况下,云眼在主域上设置其Cookie,以便跨子域进行操作。

window['eyeofcloud'] = window['eyeofcloud'] || [];
window['eyeofcloud'].push(["setCookieDomain", "www.example.com"]);

在此示例中,云眼设置的Cookie将只会在(“www.example.com”及其所有子域名)上可用,而不是“.example.com”这个主域上

跳过浏览跟踪

跳过浏览量跟踪。

window['eyeofcloud'] = window['eyeofcloud'] || [];
window.eyeofcloud.push(["skipPageTracking"]);

停用优化的第三方Cookie。必须先调用“optOutThirdPartyCookies”才能加载云眼代码段。这将阻止跨域访问者的bucketing和测量。

window['eyeofcloud'] = window['eyeofcloud'] || [];
window['eyeofcloud'].push(["optOutThirdPartyCookies"]);

点击事件

在所有符合选择器“selector”的元素上追踪click事件“eventName”。可以在云眼SDK之前或之后调用bindTrackElement:

window['eyeofcloud'] = window['eyeofcloud'] || [];
window['eyeofcloud'].push(["bindTrackElement", "selector",
   "eventName"]);

或者在各版本或全局的JavaScript代码中调用:

eyeofcloud.push(["bindTrackElement", "selector", "eventName"]);

事件跟踪

自定义事件跟踪

在云眼中跟踪自定义事件。事件“eventName”将被跟踪并与当前访客相关联。

window['eyeofcloud'] = window['eyeofcloud'] || [];
window['eyeofcloud'].push(["trackEvent", "eventName"]);

收入追踪

跟踪创收事件。事件“eventName”将被跟踪并与其收入相关联 value

window['eyeofcloud'] = window['eyeofcloud'] || [];
window['eyeofcloud'].push(["trackEvent", "eventName", {"revenue": value}]);

value 应该表示为选择的货币值的100倍。例如,如果想跟踪某个价值为¥23.5的商品的购买事件,可以参照以下代码:

window['eyeofcloud'].push(["trackEvent", "purchase", {"revenue": 2350}]);

排除访客

从云眼的数据收集中对象中排除一些访客。例如,希望通过自己的一些偏好来追踪指定的访客。

window['eyeofcloud'] = window['eyeofcloud'] || [];
window['eyeofcloud'].push(["optOut"]);

还可以使用query参数来执行此操作 eyeofcloud_opt_out=true.

访客分段

通过API对访客进行分段的做法已被弃用,建议使用 维度 。当然,已使用了API进行访客分段的优化方案也是可以正常工作的。

将访客添加到分段中:

window['eyeofcloud'] = window['eyeofcloud'] || [];
window['eyeofcloud'].push(['addToSegment', 'apiIdentifier', 'optionalSegmentValue']);

将访客从分段中移除:

window['eyeofcloud'].push(['removeFromSegment', 'apiIdentifier']);

把访客从分段中移除后,云眼将不再把访客的转化统计到分段的结果中。但如果在移除之前,访客触发了pageview事件的话,该访客的转化仍会被统计到分段的结果中。

将访客从所有分段中移除:

window['eyeofcloud'].push(['removeFromAllSegments']);