Web SDK 集成文档
JS SDK初始化
在您的页面head部分,直接引入SDK:
请务必将sdk集成在head 较头部的位置 , 请不要将sdk加在任何判断中(如if判断)。
<head>
<script src="https://sdk.appadhoc.com/ab.plus.js"></script>
<script>
adhoc('init', {
appKey: "your appkey", //创建应用时获得的appkey
defaultFlags: {your_flag_name: 0}, //编程模式必填:设置试验变量默认值,通常为0
clientIdDomain:"your_website_domain"//试验页面主域名,例如appadhoc.com
})
</script>
</head>
因sdk加载后需要进行页面渲染,请务必在页面head部分进行初始化,否则可能影响页面展示和数据上报。AppAdhoc SDK 经过长期优化和验证,加载过程不会被感知。
注意:如果没有初始化,其他 API 调用可能会出错,建议在 ab.plus.js 加载之后尽快进行初始化。
“appkey” 是在登录 AppAdhoc 后台创建“应用”之后获得的该“应用”的授权标识。
可在AppAdhoc控制台应用列表找到,如下图红线部分:
请勿在SDK基础上进行自行封装,以免影响到试验逻辑,造成试验无法正常运行。如果确有自行封装的需求,请与客户经理联系,获取注意事项。
编程模式:根据“试验变量”展示相应内容
在编程模式中“试验变量”的值决定了展示的内容或程序的逻辑,请务必保证填写的试验变量和集成的代码保持一致。多链接试验和可视化试验不需要此步骤。
注意:试验变量值应由相关A/B Testing需求制定人员在后台提前录入完毕,如下图“版本管理”红线部分:
通过试验变量控制展示版本内容需要如下两步:
1.获取AppAdoc 后台试验变量
通过在您的 Web 页面上调用 adhoc('getFlags', callback) 来完成的:(以一个按钮为例)
<button href="" onclick="adhoc('getFlags', applyFlags)">测试获得试验变量</button>
<!-- getflags:获取实验变量的方法;applyFlags:callback函数名称 -->
2.定义 callback 函数,在函数中根据此页面所使用的试验变量值,显示不同的页面内容。
applyFlags是一个 callback 函数,需要在页面代码中定义该函数,在此函数中完成不同版本所需的操作,我们的sdk会把flags的值通过回调函数参数传入。
请务必保证代码中的变量名称与此处填写完全一致(包括字母大小写等)。
<script>
function applyFlags(flags) {
//applyFlags:callback函数名称
if (flags.get('isNewHomePage') === 1) {
//isNewHomePage:试验变量名称,和试验平台填写的名称保持一致;
var text = "请填写试验版本要展示的文案!";
} else {
var text = "请填写原始版本要展示的文案!";
}
}
</script>
其中,'isNewHomePage' 即是“试验变量“,应与上图中红线标识保持一致,上面的示例代码在判断试验变量值以后,决定使用哪个版本的文案。
请注意在用户访问到试验页面时,需要触发试验内包含的所有变量才算作进入试验,否则将不会上报试验数据。
在此示例中,“flags.get('isNewHomePage')”算作触发变量“isNewHomePage”。请勿在非试验页面或公用head模板中调用。
注意:如果网络速度较慢,在此 callback 中处理页面的展示可能会造成页面的闪烁。对于涉及到的界面变动部分,建议使用adhoc('hide')和adhoc('show')方法控制元素的隐藏和展示时机。
_上报指标
指标用于量化试验结果的好坏,AppAdhoc 后台中的试验图表根据此数据生成。在可视化试验和多链接合并试验中,您也可以通过此方法定义上报指标。注意:指标值应由PM或相关AB Test需求制定人员在后台提前录入完毕,如下图“优化指标”红线部分:
请务必保证代码中的变量名称与此处填写完全一致(包括字母大小写等)。
比如在进入某一逻辑分支后,可以统计点击次数。将上图中的指标“clickTimes”传入函数实现上报指标, 每次累加1:
<button href="" onclick="adhoc('track', 'clickTimes', 1)">统计点击次数</button>
<!-- track:表示这次函数调用的作用是上报数据; -->
<!-- clickTimes:这是上报指标名称,必须和平台填写的优化指标名称保持一致; -->
<!-- 1:统计点击次数+1 -->
JS中的指标上报
<script type = 'text/javascript' > $(function() {
$('button').click(function() {
//function:回调函数;
adhoc('track', 'clickTimes', 1)
//track:表示这次函数调用的作用是上报数据;
//clickTimes:这是上报指标名称,必须和平台填写的优化指标名称保持一致;
//1:统计点击次数+1
});
}) </script>
跳转链接的指标统计
针对跳转链接的事件跟踪,为保证事件成功上报,请使用以下方法。此回调方法将返回指标上报是否成功的结果,您可根据返回的结果进一步处理。
<!-- a标签 -->
<a href="http://example.com/link" onclick="adhoc('track', 'clickTimes', 1, function(){ location.href = 'url' }); return false;"> 跳转链接 </a >
<!-- track:表示这次函数调用的作用是上报数据; -->
<!-- clickTimes:这是上报指标名称,必须和平台填写的优化指标名称保持一致; -->
<!-- 1:统计点击次数+1;-->
<!-- location.href = 'url':跳转链接地址 -->
<!-- 非a标签 -->
<div onclick="adhoc('track', 'clickTimes', 1, function(){ location.href = 'url' });" ></div>
高级功能 受众定向(需要联系管理员开启)
AppAdhoc Web SDK 支持预定义受众定向和自定义受众定向两种方式。
预定义受众定向功能中,开发者只需要在Appadhoc平台中选择预设的受众标签,SDK会自动采集相关信息并判定当前用户是否进入试验(例如浏览器名称、版本、语言等用户标签),无需在代码中定义。
投放渠道
在web试验中,支持通过链接参数中的渠道标签进行定向试验。举例如下:
http://www.appadhoc.com?source=xxxxx
其中参数名source表示投放渠道,参数值为不同渠道的名称。假设本次试验只针对投放于百度的流量生效,则目标参数为source=baidu。您需要进行如下配置:
1、在sdk初始化中指定投放渠道的参数key:
调用此方法,sdk将会自动抓取参数key对应的值,作为用户的渠道属性上传。
<!-- 初始化 -->
adhoc('init',{
appKey:"your appkey",//平台获得的Appkey必要
sourceKey:"source"//渠道参数key
})
2、在AppAdhoc网站端设置定向受众组:
3、在试验的运行控制模块中选择受众组即可(试验开始后不可更改)。
自定义定向条件
开发者可以根据需要选择自定义受众标签,此方式需要在Appadhoc平台中填写好标签的key和value,之后再代码中为当前用户设置标签,进而实现将不符合条件的用户排除在此次试验之外。比如只想要女性用户,或30岁以下的用户参与试验等。最好在init前调用。
关于受众定向详细请参考受众定向。
注意:自定义受众定向条件应由PM或相关AB Test需求制定人员在后台提前录入完毕。
在运行控制/右侧定向试验:
选择分组,点击编辑用户群:
即得到受众条件的key,在下图例子中,“sex”是key:
前端代码中通过“custom”添加自定义标签名及标签值,这里需要动态获取标签值上传给后台,以便后台决定该用户是否满足受众定向条件(如有疑问请联系客户经理协助)。
<!-- 初始化 -->
adhoc('init',{
appKey:"your appkey",//平台获得的Appkey必要
custom:{sex: 'male', age: user_age_tag}//sex、age:自定义标签key;
})
“appKey” 是在登录 AppAdhoc 后台创建“应用”之后获得的该“应用”的授权标识。
可在AppAdhoc控制台应用列表找到,如下图红线部分:
API 参考
集成调试
恭喜,您完成了AppAdhoc AB Testing Web SDK的埋点集成工作,后续可通过AppAdhoc平台集成调试功能验证试验流程。
注意:确保app_key, 试验变量字符串,指标字符串与后台截图处一一对应,否则可能出现异常或无试验数据情况。