Skip to content

Instantly share code, notes, and snippets.

@yehgdotnet
Forked from sandywu/windvane.md
Created November 10, 2021 09:44
Show Gist options
  • Save yehgdotnet/83c454d7a8314e58c7402e308d14d859 to your computer and use it in GitHub Desktop.
Save yehgdotnet/83c454d7a8314e58c7402e308d14d859 to your computer and use it in GitHub Desktop.

WindVane Bridge API (v1.2.2)

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

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.jsapi.js。 Recommend To CReader... View List

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment