windvane.md

WindVane Bridge API (v1.2.2)

提供与客户端通讯的机制。支持WindVane SDK v2.2 以上版本。

• WindVane SDK参考。

WindVane 独有UA

windvane 在客户端中，会将原始UA后面跟上 WindVane/WindVaneSDK的版本号，你可以通过判断UA的方式来检查环境 其中，淘宝主客户端1212版本（IOS 3.4.5 ANDROID 3.9.5）后格式为

[IOS平台] WindVane/WindVaneSDK的版本号 TBIOS/主客的TTID

[Android平台] WindVane/WindVaneSDK的版本号 TBANDROID/主客的TTID

举例

alert("获取到客户端的UA:"+window.navigator.userAgent);

if (window.navigator.userAgent.match(/WindVane/i)) {
	alert("当前运行环境为接入了WindVane Framework的客户端WebView.");
}

api.js [Public]

提供给业务方使用，封装了客户端的特性功能。依赖bridge.js。

引用地址：http://g.tbcdn.cn/mtb/lib-windvane/1.2.2/api.js。

以下API均在window.WindVane.api的命名空间下。展示的API列表第一行是JS调用的名称，第二行是访问的客户端对象方法。

基础 api.base [window.WindVane.api.base]###

isWindVaneEnvironment()

判断是否在WindVane的WebView环境中。该API在浏览器中也可以运行。

输入参数

无

输出参数

同步返回 true/false

举例

if (window.navigator.userAgent.match(/WindVane/i)) {
	alert("当前运行环境为接入了WindVane Framework的客户端WebView.");
}

isWindVaneSDK(success, failure)

用于获取当前WindVane SDK的版本，该参数的替代方法是自己从UA中获取到WindVane的SDK版本号。

输入参数

• [function] success 判断正确的回调
• [function] failure 判断失败的回调

输出参数

返回值将会在回调方法中传递，如果成功获取，则进入success回调，否则进入failure回调

• [string] version:windvane的版本号
• [string] os:平台类型（ios/android）

举例

Window.WindVane.api.base.isWindVaneSDK(function(e){
	alert(JSON.stringify(e));
}, function(e){
	alert("error");
});

plusUT(success, failure, option)

数据埋点，底层打通UserTrack进行数据埋点。

适用场景 目前该参数的主要目的是用于人机安全方案的行为埋点，请勿使用该函数进行其他方式的埋点行为。

注意 需求SDK版本：v2.5 该API只允许Alibaba域名页面使用。

输入参数

• [function] success 执行成功的回调
• [function] failure 执行失败的回调
• [object] option 入参对象包括如下字段
  • [string] eid 事件ID，如果你是活动页面，请传入9199，该参数接受范围[9100,9200)
  • [string] a1:数据埋点参数1，含义自定义，默认含义为活动/页面名称
  • [string] a2:数据埋点参数2，含义自定义，默认含义为控件名称
  • [string] a3:数据埋点参数3，含义自定义，默认含义为行为名称

输出参数

无输出参数，如果成功执行，则进入success回调，否则进入failure回调。

举例

var param = {};
param.eid = '9199';
param.a1 = 'redCouponAct';
param.a2 = 'Button';
param.a3 = 'Click';

window.WindVane.api.base.plusUT(function(r){
	alert(JSON.stringify(r));
}, function(e){
	alert(JSON.stringify(e));
}, param);

showShareMenu(success,failure,option)

淘宝主客专享API 淘宝主客户端API：分享

输入参数

• [function] success 执行成功的回调
• [function] failure 执行失败的回调
• [object] option 入参对象包括如下字段
  • [string] image 图片地址
  • [string] url 分享URL
  • [string] title 分享标题
  • [string] text 分享内容

输出参数

无输出参数，如果成功执行，则进入success回调，否则进入failure回调

getDeviceInfo(success,failure)

淘宝主客专享API 淘宝主客户端API：获取设备信息

输入参数

• [function] success 执行成功的回调
• [function] failure 执行失败的回调

输出参数

无输出参数，如果成功执行，则进入success回调，否则进入failure回调

摇一摇 api.shake [window.WindVane.api.shake]

startWatch(handler,failure,option)

开启摇动的监听。

输入参数

• [function] handler 成功接受到摇动事件行为的回调
• [function] failure 执行失败的回调
• [object] option 控制参数
  • timeout 启动监听超时参数，当超出该时间没有获取到摇动事件，则进入failure回调，单位 毫秒

输出参数

无输出参数，如果成功获取到摇动事件，则进入success回调，否则进入failure回调

举例

window.WindVane.api.shake.startWatch(function(){
	alert("检测到摇动");
}, function(e){
	alert("检测摇动失败！" + JSON.stringify(e));
}, {
	timeout:5000
});

stopWatch(success, failure, handler)

关闭摇动的监听。

输入参数

• [function] success 关闭成功回调
• [function] failure 关闭失败回调
• [function] handler 制定要关闭的某个监听摇动时间的回调，该值来源于监听方法的第一个函数的句柄，如果不传递，则清空所有监听者

输出参数

无输出参数，如果成功获取到摇动事件，则进入success回调，否则进入failure回调

举例

var listenShakeHandler = function(){
	alert("检测到摇动");
};

window.WindVane.api.shake.startWatch(listenShakeHandler, function(e){
	alert("检测摇动失败！" + JSON.stringify(e));
});

window.WindVane.api.shake.stopWatch(function(){
	alert("停止检测成功");
}, function(e){
	alert("停止检测失败"+JSON.stringify(e));
}, listenShakeHandler);

地理位置 api.geolocation [window.WindVnae.api.geolocation]

重要，必须阅读 地理位置API你可以选择直接使用如下API，也可以选择使用原生H5 API，当发现是在WindVane的客户端环境下，我们将原生API进行了重写，这样你无须担心webview中原生API的支持性。

推荐 我们建议你使用原生API的方法，但是原生API最终执行的同样为以下方法，这样，在windvane的环境中，最终执行到的为Native的方法，而在浏览器中，最终执行到的是H5原生的API实现。

get(callback, failure, option)

获取当前的地理位置。

输入参数

• [function] 获得地理位置后的成功回调
• [function] 获取地理位置后的失败回调
• [object] option 包括：
  • [string]enableHighAcuracy 是否使用高清准度，true/faluse
  • [string]address 是否获取地址描述，如中国杭州市，true/false

输出参数

• 如果成功获取，则进入success回调，否则进入failure回调
• [object] coords 经纬度信息
  • [string] latitude 纬度
  • [string] longitude 经度
  • [string] altitude 高度
  • [string] altitudeAccuracy 垂直经度
  • [string] accuracy 水平精度
  • [string] heading 宿主设备当前移动的角度方向，相对于正北方向顺时针计算
  • [string] speed 以米每秒为单位的设备的当前对地速度
• [object] address
  • [string] City 城市
  • [string] State 省
  • [string] SubLocality 区
  • [string] Thoroughfare 路
  • [string] FormattedAddressLines 详细地址

举例

function getLocation () {
	var op = {
		// 指示浏览器获取高精度的位置，默认为false
		enableHighAcuracy: true,
		//获取详细地址描述信息
		address:true
	};

	window.navigator.geolocation.getCurrentPosition/*get*/(function(e){
			alert("获取到地理位置:"+JSON.stringify(e));
		}, function(e){
			alert("获取错误:"+JSON.stringify(e));
	}, op);
}

search(callback, failure, option)

搜索给定地址的地理位置经纬度。

输入参数

• [function] callback获得地理位置后的成功回调
• [function] failure 获取地理位置的失败回调
• [object] option 包括：
  • [sting] addrs 地址

输出参数

• [string] latitude 纬度
• [string] longitude 经度

举例

function searchLocation () {
	var op = {
		addrs:"浙江省杭州市余杭区文一西路960号"
	};
	
	window.navigator.geolocation.searchPosition(function(e){
		alert("获取到经纬度："+JSON.stringify(e));
	}, function(e){
		alert(JSON.stringify(e));
	}, op);
}

watch(callback, failure, option)

需求客户端版本：1212版本，需求WindVane版本：2.6.0

监听地理位置变化，只有地理位置发生变化才会回调通知

输入参数

• [function] callback获得地理位置后的成功回调
• [function] failure 获取地理位置的失败回调
• [object] option 包括：
  • [string]enableHighAcuracy 是否使用高清准度，true/faluse
  • [string]address 是否获取地址描述，如中国杭州市，true/false
  • [sting] failure 检测时间片长度，单位 毫秒

返回值

• [int] id 任务ID

clear(i)

需求客户端版本：1212版本，需求WindVane版本：2.6.0

清理监听地理位置变化任务

输入参数

• [id] id 任务ID

摄像头Camera [window.WindVane.camera]

takePhoto(success, failure, option)

调用摄像头并拍照，自主选择是否自动上传

注意 该API仅允许Alibaba域名的页面使用

输入参数

• [function] success: 成功执行的回调方法
• [function] failure: 失败执行的回调方法
• [object] option
  • [string] type:拍照后上传类型，[1]代表拍照完成确认后自动上传；[0]代表拍照完成后不自动上传（默认）

输出参数

• [function] success:拍照成功后的回调函数
  • [string] url: 访问URL，页面将此URL填写给img的src属性，用于进行页面的预览，该URL非真实的CDN URL，浏览器无法访问。
  • [string] localPath: 本地文件路径，该路径可以用于后续的上传过程。
  • [string] resourceURL: 上传到TFS后的回传CDN地址，该地址可以在浏览器里真实访问。
• [function] failure:拍照失败后的回调函数

输出事件

WVPhoto.Event.takePhotoSuccess 获取照片成功，即将上传。参数值同上（url、localPath），此时JS可以用来做预览处理。

WVPhoto.Event.prepareUploadPhotoSuccess 上传准备成功，即与服务端的第一次握手通信成功。

举例

var path; // 保存本地文件的路径
function takePhoto (type) {
	var p = {
		"type" : type // "1" OR "0"
	};
	window.WindVane.api.camera.takePhoto(function(e){
		if (e && e.url) {
			document.getElementById("wv_preview_image").src = e.url;
			path = e.localPath;
		}
	}, function(e){
		alert("take photo failed.mseesge:"+JSON.stringify(e));
	});
}

document.addEventListener("WVPhoto.Event.takePhotoSuccess", function (e) {
	if (e && e.url) {
		alert("获取照片成功"); 
		document.getElementById("wv_preview_image").src = e.url; 
	}
}, false);

document.addEventListener("WVPhoto.Event.prepareUploadPhotoSuccess", function (e) {
	alert("准备上传成功，即将上传");
}, false);

confirmUploadPhoto(success, failure, option)

确认上传照片

输入参数

• [function] success: 成功执行的回调方法
• [function] failure: 失败执行的回调方法
• [object] option:
  • path: 需要上传的照片的路径，必须为takePhoto回传回来的localPath字段的值。

输出参数

无输出参数，执行成功则进入成功回调方法，执行失败则进入失败回调方法。

吹气检测blow [window.WindVane.api.blow]

listenBlow(success, failure, blowCllback, option)

监听吹气动作

注意 该API仅允许Alibaba域名的页面使用

输入参数

• [function] success: 成功执行的回调方法
• [function] failure: 失败执行的回调方法
• [function] blowCallback: 吹气行为发生后出发的回调方法
• [object] option : 备用字段，目前不接受参数

输出参数

执行成功，进入成功回调方法，执行失败，进入失败回调方法。

• [float] pass: 吹气检测值。该值随着硬件的不同有所不同，在iOS平台，该值未0-1区间范围值，伴随着吹气过程，该值为逐渐增长的值；在Android平台，该值为固定的1。

举例

window.WindVane.api.blow.listenBlow(function(e) {
		alert("检测吹气任务成功！");
	}, function(e) {
		alert("检测吹气任务失败！"+JSON.stringify(e));
	}, function (e) {
		document.getElementById('bresult').innerHTML = e.pass;
});

stopListenBolw(succeess, failure, option)

停止监听吹气动作

注意 该API仅允许Alibaba域名的页面使用

输入参数

• [function] success: 成功执行的回调方法
• [function] failure: 失败执行的回调方法
• [function] blowCallback: 吹气行为发生后出发的回调方法
• [object] option : 备用字段，目前不接受参数

输出参数

执行成功，进入成功回调方法，执行失败，进入失败回调方法。

举例

window.WindVane.api.blow.stopListenBlow(function(e) {
	alert("停止检测工程");
}, function (e) {
	alert("停止检测失败");
});

跨域Cookie [window.WindVane.cookies]

危险 该API不确保执行成功，使用请谨慎

read(url, callback)

读取给定url的cookie。

输入参数

• [string] url
• [function] callback 获得cookie后的回调

write(name, value, options, callback)

写入cookie。

输出参数

• [string] name cookie名
• [string] value cookie值
• [object] options 参数（domain/path/expire/secure）

WebURL [window.WindVane.weburl]

该API为主动的URL拦截请求行为，目前客户端的实用性不高，已经有其他好的方案

intercept(url, success, failure)

通知需要被拦截的url。

输入参数

• [string] url 被拦截的url
• [function] success 拦截成功后的回调
• [function] failure 拦截失败后的回调

输出参数

本地成功的进行了URL拦截，并触发了特定模块功能，进入成功回调，执行失败进入失败回调

Server [window.WindVane.server]

send(success,failure,option)

需求SDK版本：v2.5

使用本地代理发送安全mtop请求

输入参数

• [function] success 成功回调
• [function] failure 失败回调
• [object] option 包括
  • [string] api :请求api名称
  • [string] v:版本号
  • [string] post:是否使用post方式请求,"1" 是
  • [string] ecode:是否使用ecode签名，需要与服务端API约定，“1” 是
  • [string] isSec:是否是安全请求，默认是“1”，如果是非安全请求，请设置为“0”，支持版本：主客户端1128版本，WindVane 2.6.0 版本
  • [object] param:请求参数，json对象

输出参数

执行成功，则进入成功回调，失败会则进入失败回调

• [object] object: mtop返回的信息的透传，具体JSON格式请参见MTOP文档。
  • [string] code : code 字段为mtop返回非success的时候，客户端将responseStatusCode额外补充到其中的特别参数。我们不建议服务端通过返回不同的code的方式来标记不同的业务错误，业务错误应该跟系统错误有明确的标记。

举例

var param = {};
param.api = 'mtop.security.plugins';
param.v = '1.0';
param.ecode = '1';
param.post = '1';

param.param = {
	f:'detail',
};

window.WindVane.api.server.send(function(r){
		alert("接收到mtop返回值:"+JSON.stringify(r));
	}, function(r){
		alert("接收到mtop返回错误:"+JSON.stringify(r));
},param);

人机安全方案举例

function drawCoupon () {
	var param = {};
	param.eid = '9199';
	param.a1 = 'redCouponAct';
	param.a2 = 'Button';
	param.a3 = 'Click';

	// 先主动埋点，然后无论埋点是否OK都直接执行mtop请求
	window.WindVane.api.base.plusUT(function(r){
		sendProxyReqeust ();
	}, function(e){
		sendProxyReqeust ();
	}, param);
}

function sendProxyReqeust () {
	var param = {};
	param.api = 'mtop.security.plugins';
	param.v = '1.0';
	param.ecode = '1';
	param.post = '1';

	param.param = {
		f:'detail',
	};

	window.WindVane.api.server.send(function(r){
			alert("接收到mtop返回值:"+JSON.stringify(r));
		}, function(r){
			alert("接收到mtop返回错误:"+JSON.stringify(r));
	},param);
}

bridge.js

提供与客户端通讯的API。

引用地址：http://g.tbcdn.cn/mtb/lib-windvane/1.2.2/bridge.js。

供JS端调用的API [Public]

直接调用JSBridge提供的API,理论上任何的客户端开放的API,都可以通过该API使用，但是我们不建议你这样做，除非api.js没有提供这个API并且你对客户端提供的API有一定了解.

window.WindVane.call(obj, method, param, successCallback, failureCallback, timeout)

调用客户端的对象方法。

• [string] obj 客户端的对象
• [string] method 客户端的方法
• [object] param 传入的参数
• [function] successCallback 调用成功后的回调
• [function] failureCallback 调用失败后的回调
• [number] timeout 调用超时，可省略

被客户端调用的API[Private方法，JS请勿调用]

JSBridge内部使用方法，JS请勿调用，仅供了解测试

window.WindVane.fireEvent(eventname, eventparam)

在document触发事件。

• [string] eventname 事件名
• [string] eventparam 事件参数（序列化的JSON）

window.WindVane.getParam(sid)

获取某次调用的参数。

• [string] sid 某次调用的唯一标识

window.WindVane.onSuccess(sid, msg)

调用成功后，执行的回调。

• [string] sid 某次调用的唯一标识
• [string] msg 传回的参数（序列化的JSON）

window.WindVane.onFailure(sid, msg)

调用失败后，执行的回调。

• [string] sid 某次调用的唯一标识
• [string] msg 传回的参数（序列化的JSON）

hooks.js

提供给mixsln来访问客户端特性功能。支持mixsln v0.4.0以上版本。依赖bridge.js，api.js。 Recommend To CReader... View List