跨平台 JSSDK 参考手册

优质

小牛编辑

136浏览

2023-12-01

开始 :id=ks

通用说明 :id=tysm

微哨WPSDK集成了微哨JSSDK和微信JSSDk，是一组可以同时运行于微哨和微信内置浏览器的扩展JavaScript API。应用可以通过这些扩展API获得访问移动设备上的文件，摄像头，图片库以及扫描二维码等。

所有接口通过wp对象来调用，参数是一个对象，除了每个接口本身需要传的参数之外，还有以下通用参数：

success：接口调用成功时执行的回调函数。
fail：接口调用失败时执行的回调函数。
complete：接口调用完成时执行的回调函数，无论成功或失败都会执行。
cancel：用户点击取消时的回调函数，仅部分有用户取消操作的api才会用到。

注意：以上几个函数都带有一个参数，类型为对象，其中除了每个接口本身返回的数据之外，还有一个通用属性errMsg，其值格式如下：

调用成功时："xxx:ok" ，其中xxx为调用的接口名
用户取消时："xxx:cancel"，其中xxx为调用的接口名
调用失败时：其值为具体错误信息

环境要求 :id=hjyq

目前WPSDK仅支持android和iOS两个平台，因此WPSDK仅能在android和iOS的微哨和微信内置浏览器中运行。

注意：在android和iOS平台的自带浏览器中也无法正常运行。

步骤一: 绑定域名（微信必需） :id=bz1

如果应用需要支持在微信中运行，必须在微信公众平台绑定域名。

登录微信公众平台进入“公众号设置”的“功能设置”里填写“JS接口安全域名”。
登录后，可在“开发者中心”查看对应的接口权限。

如果应用只运行在微哨平台，则不需要此步骤。

步骤二：引入文件 :id=bz2

请下载wp.js，并在页面中引入。

示例：

<script> type="text/javascript" src="js/wp-1.0.js" charset="utf-8" </>

按需导入

应用运行在微哨平台: 请下载Whistle.js，并在页面中引入。

<script> type="text/javascript" src="js/whistle-5.3.js" charset="utf-8" </>

应用运行在微信平台：在需要调用JS接口的页面引入微信公众平台的JSSDK文件。

<script> type="text/javascript" src="//res.wx.qq.com/open/js/jweixin-1.0.0.js" charset="utf-8" </>

步骤三：通过config接口注入权限验证配置（微信必需） :id=bz3

所有需要使用JS-SDK的页面必须先注入配置信息，否则将无法调用。

wp.config({
    whistle: {
        appId: ''  //必填，微哨ms创建应用时生成的app key
    },
    weixin: {
        debug: true, // 开启调试模式,调用的所有api的返回值会在客户端alert出来，若要查看传入的参数，可以在pc端打开，参数信息会通过log打出，仅在pc端时才会打印。
        appId: '', // 必填，公众号的唯一标识
           timestamp: , // 必填，生成签名的时间戳
        nonceStr: '', // 必填，生成签名的随机串
        signature: '',// 必填，签名，见附录1
        jsApiList: [] // 必填，需要使用的JS接口列表，所有JS接口列表见附录2
    }
});

步骤四：通过ready接口处理成功验证 :id=bz4

WPSDK的API只有在整个页面加载完毕有才有效，在页面没有加载完成前使用扩展API，可能不会有任何效果。

针对微哨平台，当WPSDK的API准备完毕后，将会回调该ready方法参数。

针对微信平台，config信息验证后会执行ready方法，所有接口调用都必须在config接口获得结果之后，config是一个客户端的异步操作，所以如果需要在页面加载时就调用相关接口，则须把相关接口放在ready函数中调用来确保正确执行。对于用户触发时才调用的接口，则可以直接调用，不需要放在ready函数中。

简而言之，微信平台运行会比微哨平台多一个配置验证的过程，两个平台都需要在ready方法之后才能调用WPSDK的API。

wp.ready(function(){
//调用WPSDK API的代码
});

步骤五：通过error接口处理失败验证 :id=bz5

wp.error(function(res){

    // config信息验证失败会执行error函数，如签名过期导致验证失败，具体错误信息可以打开config的debug模式查看，也可以在返回的res参数中查看，对于SPA可以在这里更新签名。
});

基础接口 :id=jcjk

获取wp对象 :id=whistledx

页面一旦引入WPSDK后，wp对象将自动创建，所有的扩展API都将通过这个对象进行调用。

osName主要用于区分当前的运行系统：


wp.sys.osName == wp.sys.ANDROID如果为true，表示当前页面运行在android系统。
wp.sys.osName == wp.sys.IOS如果为true，表示当前页面运行在iOS系统。
wp.sys.osName == wp.sys.OTHER如果为true，表示当页面前运行在微哨不支持的系统。

platformName主要用于区分当前的运行平台：


wp.sys.platformName == wp.sys.WHISTLE如果为true，表示当前页面运行在微哨平台。
wp.sys.platformName == wp.sys.WEIXIN如果为true，表示当前页面运行在微信平台。

判断当前客户端版本是否支持指定JS接口 :id=checkjsapi

wp.checkJsApi({
    jsApiList: ['chooseImage'], // 需要检测的JS接口列表，所有JS接口列表见附录2,
    success: function(res) {
        // 以键值对的形式返回，可用的api值true，不可用为false
        // 如：{"checkResult":{"chooseImage":true},"errMsg":"checkJsApi:ok"}
    }
});

微哨/微信通用接口 :id=tyjk

wp.getNetworkType获取当前网络类型 :id=wllx

获取当前手机所使用的网络类型以及IPv4地址。

wp.getNetworkType({
    success: function (res) {
        var networkType = res.networkType; // 返回网络类型2g，3g，4g，wifi,unknown(未知,可能由于当前设备没有联网)

        //微哨平台会额外返回ip地址和接入ap的ssid
        if(res.netaddress){
            var ip = res.netaddress; // 返回对应的网络ip地址,如果无法获取地址,则为undefined.
        }
        if(res.ssid){
            var ssid = res.ssid; // 返回对应的wifi网络接入的ssid名字,如果不是wifi,则为undefined.
        }
    }
});

wp.getLocation获取当前地理位置 :id=geoapiid

获取当前设备的地理位置信息。

wp.getLocation({
    success: function (res) {
        var latitude = res.latitude; // 纬度，浮点数，范围为90 ~ -90
        var longitude = res.longitude; // 经度，浮点数，范围为180 ~ -180。
        var speed = res.speed; // 速度，以米/每秒计
        var accuracy = res.accuracy; // 位置精度
    }
});

wp.scanQRCode扫一扫 :id=sao

调起条形码和二维码扫描并获得识别结果。

wp.scanQRCode({
    needResult:0,//默认为0，扫描结果由微哨处理，1则直接返回扫描结果
    scanType:["qrCode","barCode"],//可以指定扫二维码还是一维码，默认是两者都有
    success:function(res){
        var result = res.resultStr;//当needResult为1时，可以通过这种方式获得扫码结果
    }
});

wp.chooseImage拍照或从相册取图片 :id=qtp

调起拍照或从相册取图片。

 wp.chooseImage({
    count: 1, // 默认9
    sizeType: ['original', 'compressed'], // 可以指定是原图还是压缩图，默认二者都有
    sourceType: ['album', 'camera'], // 可以指定来源是相册还是相机，默认二者都有
    success: function (res) {
        var localIds = res.localIds; // 返回选定照片的本地ID列表，
        $("#image").src = localIds[0];//localId可以作为img标签的src属性显示图片
    },
    cancel:function(res){
        $('#chooseimage_case1').text('用户取消!');
    }
});

wp.uploadImage上传图片 :id=sctp

上传图片。

 wp.uploadImage({
    localId: '', // 需要上传的图片的本地ID，由chooseImage接口获得
    isShowProgressTips: 1, // 默认为1，显示进度提示
    success: function (res) {
        var imageUrl = res.imageUrl; // 返回图片上传后的访问url
    }
});

注意：目前该接口不支持同时调用多次来上传多个图片，程序逻辑必须等待一张图片完成后再上传下一张。

wp.downloadImage下载图片 :id=xztp

下载图片。

 wp.downloadImage({
    imageUrl: '', // 需要下载的图片的地址，由uploadImage接口获得
    isShowProgressTips: 1, // 默认为1，显示进度提示
    success: function (res) {
        var localId = res.localId; // 返回图片下载后的本地ID
    }
});

微哨特有接口 :id=wstyjk

wp.getDeviceId获取设备唯一id :id=sbid

获取当前设备的唯一标识。

wp.getDeviceId({
    success: function (res) {
        var deviceId = res.deviceId; // 返回设备的唯一标识符
    }
});

wp.startPedometer启动计步器 :id=qdjbq

wp.startPedometer({
    success:function(){
        //当回调到此方法时,说明计步器启动成功
    },
    fail:function(result){
    }

});

wp.stopPedometer关闭计步器 :id=gbjbq

wp.stopPedometer({
    success:function(){
        //当回调到此方法时,说明计步器关闭成功
    },
    fail:function(result){
    }

});

wp.getPedometerStatus查询计步器状态 :id=cxjbqzt

wp.getPedometerStatus({
    success:function(res){
            var status = res.status; //true为启动,false为关闭
            var steps = res.steps;  //最近7天步数值, steps[0]为当天的步数,steps[1]为昨天的步数,依次类推
    }
});

自定义微信调用 :id=zdywx

wp.getWXProxy获取微信API代理 :id=hqwx

获取微信JSSDK的API代理。使用该API代理，可以调用微信JSSDK的API。

const wxProxy = wp.getWXProxy();
//调用微信JSSDK的API
wxProxy.startSearchBeacons({
    ... 
});