		@@ -1,240 +0,205 @@
		# A/B测试Web SDK
		## 项目运行
		1. 克隆代码
		```
		git clone http://prj.testin.cn:8200/abtest-sdk/javascript-sdk.git
		```
		或
		```
		git clone git@192.168.1.93:abtest-sdk/javascript-sdk.git
		```
		# Web/H5 SDK集成文档

		2. 安装依赖的模块
		### API参考

		[Web/H5 SDK API文档](https://ab.testin.cn/docs/api/web.html)

		## 兼容性

		支持市面上所有的主流浏览器，包括IE8及其以上版本。

		## Demo演示

		此Demo是对登录按钮的文字进行A/B测试，有两个版本: 版本一"立即登录"和版本二“点击登录”。

		Demo地址：[https://ab.testin.cn/demo/login.html](https://ab.testin.cn/demo/login.html)

		> 注意：访问Demo地址，如果看到的是版本一，那么再次访问时，看到的依旧是版本一。即同一个用户，一旦分配到某个版本，再次访问时，看到的仍旧会是同一个版本。如果想看到版本二，那么要换个设备, 再访问Demo地址。

		## 下载Web/H5 SDK

		### 独立版本

		直接下载并用 <script> 标签引入：

		[testin-ab-v4.0.8.js](http://ab.testin.cn/sdk/web/testin-ab-v4.0.8.js)（请点击“右键另存为”）

		最后更新：2017/09/13

		## 使用SDK

		### 加载SDK

		```js
		<html>
		<head>
		</head>
		<body>
		<!-- 假设开发者将下载后的SDK放到libs目录下 -->
		<script src="libs/testin-ab.js"></script>
		</body>
		</html>
		```
		npm install
		```

		3. 运行
		SDK库文件加载之后，本页面会得到一个全局对象`testinAB`。所有的API都是由`testinAB`对象提供的。

		### 初始化SDK

		调用`init`方法来完成初始化。

		```js
		var appKey = 'TESTIN_xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx';
		testinAB.init(appKey);
		```
		node app.js
		```
		在浏览器地址栏里访问http://127.0.0.1:8080/, 如果出现以下界面，那么恭喜你，项目已经成功运行起来了😃
		![Aaron Swartz](http://res.cloudinary.com/dcemaqxcp/image/upload/c_scale,w_644/v1472549277/index_skhfkd.jpg)

		其中`appKey` 是在登录 Testin后台创建应用之后获得的该“应用”的授权标识，可在网站应用列表页面找到，如下图所示：

		## 目录结构说明
		net
		request.js            当api接口服务器不支持跨域时，从代理服务器发请求
		public
		html                     用来存放demo页面
		demo.html       提供给第三方开发者使用的demo页面
		news.html        PC端的演示页面
		news_h5.html  移动端的演示页面
		javascripts
		absdk.js           sdk的代码
		env.js               环境模块
		package.js       创建包，即命名空间
		storage.js        本地存储
		utils.js              工具模块
		styles                   样式文件放这里
		views                   后端模板
		app.js                      后台程序入口
		gulpfile.js                 gulp构建脚本
		![](http://ab.testin.cn/docs/assets/import.png)

		## 功能模块化分
		![Aaron Swartz](http://res.cloudinary.com/dcemaqxcp/image/upload/v1472120857/module_licjvt.png)
		`init`方法除appKey之外还有一个可选参数`clientId`, `clientId`是一个唯一的ID，用来代表一个独立访客，可根据需要定义，例如使用内部会员ID或者随机生成等方法。

		工具模块: 提供了两个函数md5，uuid。md5是上报指标时用来对apKey和stime的
		连接字符串做md5后取前6位作为sign。uuid用来为SDK自动生成clientId.
		> 如果没有指定clientId, SDK将自动生成一个随机的 clientId，并存储在cookie中，之后该浏览器中的调用都将使用该 clientId。

		本地存储: 主要用来存储client信息，数据结构见下方。如果支持HTML5的localStorage，
		就优先用localStorage，否则用cookie。
		```javascript
		[
		{
		id: '5d69703a-d600-4afe-adb7-7712f143e72e',//clientId
		auto: 1, //是否是SDK自动生成的clientId(1: 是，否则不是)
		apps: [
		{
		appKey: '29bf3ae84-753e-41e4-b983-b31269d1b6ss',
		upTime: 1472643092357 //用户信息上传时间
		}
		]
		}
		]
		```
		### 根据“实验变量”展示对应实验版本

		环境模块: 得到操作系统，浏览器，语言，分辨率等。
		在编程模式中“实验变量”的值控制展示的内容或程序的逻辑。一般情况下，不同实验版本应有不同的变量值。实验变量值应由相关人员在后台提前录入，如下图“版本管理”部分：

		SDK核心API: 注意，并不是所有的接口都对外公开，私有接口存在闭包中，对外公开的接口在
		ABTest的prototype上。
		![](http://ab.testin.cn/docs/assets/websdk1.png)

		## A/B测试流程
		![Aaron Swartz](http://res.cloudinary.com/dcemaqxcp/image/upload/c_scale,w_837/v1472550325/abtest_flow_sawcxh.png)
		上图显示了当前实验有两个版本：原始版本和版本一。有一个变量`loginTxt`，在原始版本中，变量`loginTxt`的值为"立即登录"，在版本一中，变量`loginTxt`的值为"点击登录"。

		* 引入SDK
		SDK加载之后，需要先实例化ABTest，然后通过该实例提供的接口进行A/B测试

		```javascript
		var ABTest = cn.testin.abtest.ABTest;
		var abTest = new ABTest();
		```
		根据变量值来显示相应的内容分两步：

		* 初始化SDK
		使用API之前必须进行初始化，调用abTest.init(appKey, clientId) 来完成。
		1. 获得变量值, 是通过调用`getVars`方法来完成的；

		```javascript
		abTestSDK.init(appKey, clientId)
		```
		2. 提供`callback`函数，在回调函数中根据变量值，显示不同的页面内容：

		appKey是App授权标识。是登录 Testin A/B测试后台创建 "应用" 之后获得的该 "应用" 的
		授权标识。
		clientId是一个唯一的 ID，用来代表一个独立访客，可以是用户ID，也可以不传，不传的话，
		SDK会自动生成UUID作为用户标识。

		* 获取实验变量
		调用abTest.getExp(callback) 来得到实验变量。注意，回调函数 callback 是被异步调用的。
		```js
		var appKey = 'TESTIN_xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx';
		testinAB.init(appKey);
		testinAB.setDefVars({
		loginTxt: '立即登录' //设置变量loginTxt的默认值为'立即登录'
		});
		testinAB.getVars(function(vars) {
		//假设页面中有个按钮的id是btn，且用到了jquery，通过A/B测试来设置按钮的文字
		$('#btn').html(vars.get('loginTxt'));//通过变量loginTxt的值来设置按钮的文字
		});
		```

		* 根据试验变量的值显示不同的页面内容
		回调函数callback被调用时，会被传入实验变量，此时，可根据试验变量的值，
		来完成相关的操作，如下所示
		其中，`loginTxt` 即是“变量“，应与上图中红框处的变量名保持一致，上面的示例代码在获取变量后，给按钮设置了文字。

		```javascript
		abTest.getExp(function(vars) {
		if (vars.btnColor) {
		//根据实验变量的值，得到按钮的颜色
		$('#btn').css('color', vars.btnColor);
		} else {
		//默认颜色
		$('#btn').css('color', '#00f');
		}
		> 注意：getVars方法内部会向后台服务器发请求，所以一定要在回调函数中去拿变量值。另外，要给变量设置个默认值，这样在网络异常或获取变量失败时将使用默认值，默认值生效时用户会看到默认的原始版本。

		### 上报指标

		指标用于衡量不同版本实验结果的好坏，Testin A/B测试后台中的实验图表基于上报的指标数据生成。指标应由相关人员在后台提前录入，如下图所示：

		![](http://ab.testin.cn/docs/assets/androidsdk2.png)

		假设要统计按钮的点击次数。将上图中的指标`settingClick`传入函数`track`实现上报指标, 每次累加1：

		```js
		var appKey = 'TESTIN_xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx';
		testinAB.init(appKey);
		testinAB.setDefVars({
		loginTxt: '立即登录' //设置变量loginTxt的默认值为'立即登录'
		});
		```
		testinAB.getVars(function(vars) {
		//假设页面中有个按钮的id是btn，且用到了jquery，通过A/B测试来设置按钮的文字
		$('#btn').html(vars.get('loginTxt'));//通过变量loginTxt的值来设置按钮的文字
		});
		$('#btn').click(function() {
		testinAB.track('settingClick', 1); //上报指标settingClick, 每次累加1
		});
		```

		* 上报指标
		指标用于量化试验结果的好坏, 将指标传入函数track实现上报指标, 如
		注意：如果点击按钮的同时，页面会进行跳转，那么应该提供回调函数，在回调函数中进行跳转，否则，后台将收不到上报的指标。

		```javascript
		```js
		var appKey = 'TESTIN_xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx';
		testinAB.init(appKey);
		testinAB.setDefVars({
		loginTxt: '立即登录' //设置变量loginTxt的默认值为'立即登录'
		});
		testinAB.getVars(function(vars) {
		//假设页面中有个按钮的id是btn，且用到了jquery，通过A/B测试来设置按钮的文字
		$('#btn').html(vars.get('loginTxt'));//通过变量loginTxt的值来设置按钮的文字
		});
		$('#btn').click(function() {
		abTest.track('btnClick');
		//上报指标settingClick, 每次累加1
		testinAB.track('settingClick', 1, function() {
		location.href = 'http://www.abc.com'; //在回调函数中进行跳转，否则，后台将收不到上报的指标
		});
		});
		```
		```

		##
		### 集成调试

		## SDK核心API
		SDK核心API，分为私有API和公开API，私有API只有SDK内部能调用，公开API是为第三方开发者
		提供的接口。
		### 私有API
		#### ajax(url, method, data, callback)
		发送网络请求
		##### Parameters:
		* url <String> 请求地址
		* method <String> 请求方法，get, post等
		* data <Object> 传给后台的数据
		* callback <Function> 请求完成后的回调

		#### getQueryParam(name)
		获取浏览器地址栏中的查询参数
		##### Parameters:
		* name 查询参数的名称
		在开始运行实验前，Testin A/B 测试平台支持用户通过后台的”集成调试“，强制进入指定的实验版本，用来检测代码集成和实时验证数据是否正确（详见[集成调试](/debug.md)）。如果确认已正确集成SDK，就可以安排应用上线，并通过“运行控制”功能来开始实验，实验开始后就可以实时查看实验结果。注意：测试数据并不会计入实验结果。

		##### Returns:
		* <String> 查询参数的值
		在网址输入框中输入需要预览的页面地址，点击保存，然后点击进入调试，就跳转到需要进行调试的实验版本。为了更好的说明，如下图所示，如果实验有两个版本：原始版本、版本一。点击“进入调试“按钮后，会打开新窗口展示原始版本页面。接下来，可以在新窗口打开的页面中进行操作。如果测试数据实时发生对应变化，就说明Web/H5 SDK已成功集成。

		#### getAllClient
		得到本地存储的所有client
		##### Returns:
		* <Array> 返回client数组
		注：请确保appKey，实验变量字符串，指标字符串与后台截图处一一对应，否则可能出现异常或无实验数据情况。

		#### getClient(clientId)
		得到本地存储的一个client。如果不传clientId，那返回clientId是SDK自动生成的那个client。
		##### Parameters:
		* clientId <String> 用户唯一标识
		![](http://ab.testin.cn/docs/assets/webdebug.png)

		##### Returns:
		* <Object> client对象
		### 开始实验

		#### saveClient(clientId, auto)
		新增client，存储到localStorage或cookie中
		##### Parameters:
		* clientId <String> 用户唯一标识
		* auto <Boolean> clientId是否是由SDK自动生成的
		恭喜您完成了Testin A/B测试Web/H5 SDK的集成工作，请通知产品或相关AB测试人员，点下“开始实验”按钮吧！

		#### getAutoClientId()
		得到SDK之前自动生成并存储在本地的clientId，如果没有，就返回空字符串
		##### Returns:
		* <String> 存储在本地的clientId或空字符串
		### 基于受众分组的定向实验

		#### isClientUpload(clientId, appKey)
		根据指定的clientId, appKey来判断是否上传过用户信息
		##### Parameters:
		* clientId <String> 用户唯一标识
		* appKey <String> 应用唯一标识
		默认情况下，A/B测试会基于全部用户进行A/B测试实验。如果需要从所有用户中选出特定的用户参与A/B测试，比如只想要男性用户，或30岁以下的用户参与实验等，需要调用相关SDK的API。Testin A/B Web/H5 SDK 会自动把浏览器类型、语言等用户标签自动上传，您也可以根据需要给当前用户打上自定义标签，进而将不符合受众分组条件的用户排除在此次实验之外。

		#### setClientUpload(clientId, appKey)
		已上传过用户信息的应用，将appKey和上传时间存在本地
		##### Parameters:
		* clientId <String> 用户唯一标识
		* appKey <String> 应用唯一标识
		注：受众分组条件应在后台提前录入完毕，如下图"运行控制"中的“定向用户”部分所示：

		#### sendClient(sdk)
		将用户信息上传到服务器
		##### Parameters:
		* sdk <ABTest> ABTest的实例
		![](http://ab.testin.cn/docs/assets/userGroup1.png)

		#### reqExp(sdk, callback)
		请求实验数据
		##### Parameters:
		* sdk <ABTest> ABTest的实例
		* callback <Function> 得到实验数据后的回调
		点击“添加”即可新建用户分组：

		#### reqTrack(sdk, name, callback)
		上报指标数据
		##### Parameters:
		* sdk <ABTest> ABTest的实例
		* name <String>要上报的指标
		* callback <Function> 上传指标后的回调
		![](http://ab.testin.cn/docs/assets/userGroup2.png)

		### 公共API
		#### ABTest()
		ABTest构造器
		在“新建受众”中，点击“自定义条件”以添加新的受众分组，例如下图“userClass”是key，它的value等于“gold”的用户就属于这个分组，会参加到A/B测试中，所有不符合该受众分组条件的用户都不会参与该实验。

		#### ABTest#init(appKey, clientId)
		初始化SDK
		##### Parameters:
		* appKey <String> 应用唯一标识
		* clientId <String> 用户唯一标识

		#### ABTest#getExp(callback)
		获取实验
		##### Parameters:
		* callback <Function> SDK获取实验后的回调，异步调用
		![](http://ab.testin.cn/docs/assets/userGroup3.png)

		#### ABTest#track(name, [callback])
		上报指标数据
		##### Parameters:
		* name <String>要上报的指标
		* [callback] <Function>上报后的回调，可选


		## 查询参数
		参数名 \| 含义
		------------- \| -------------
		testinVisualEnabled \| 是否正在进行可视化编辑操作
		注：请一定要在getVars方法之前调用setTags方法，否则定向实验不会生效。

		```js
		var appKey = 'TESTIN_xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx';
		testinAB.init(appKey);
		testinAB.setDefVars({
		loginTxt: '立即登录' //设置变量loginTxt的默认值为'立即登录'
		});

		## SDK发布
		在项目目录下运行 gulp，输出如下
		![Aaron Swartz](http://res.cloudinary.com/dcemaqxcp/image/upload/c_scale,w_600/v1472450136/gulp_ekanyu.jpg)

		最终会在public/dist目录中生成abskd.xxxx.js，其中xxxx是根据文件内容生成的md5


		//自定义受众条件
		testinAB.setTags({
		userClass: 'gold'
		});

		testinAB.getVars(function(vars) {


		});
		```




		## Web/H5 可视化SDK集成
		仅需在第一次集成SDK时添加相关代码，之后进行的每一个可视化模式的A/B测试实验，产品和运营只需要通过可视化的操作方式就可以完成新版本编辑、指标埋点、新版本上线、对比新老版本数据、产品决策等整个A/B测试流程。

		```
		<html>
		<head>
		</head>
		<body>
		<!-- 假设开发者将下载后的SDK放到libs目录下 -->
		<script src="libs/testin-ab.js"></script>
		<script>
		testinAB.init('your AppKey');
		testinAB.getVars();
		</script>
		</body>
		</html>
		```
		## API参考

		[Web/H5 SDK API文档](https://ab.testin.cn/docs/api/web.html)

testin-ab - npm Package Compare versions

Fixed alerts

Improved metrics

Worsened metrics