JS-SDK

[TOC]

概述

企业微信JS-SDK是企业微信面向网页开发者提供的基于企业微信内的网页开发工具包。

通过使用企业微信JS-SDK,网页开发者可借助企业微信高效地使用拍照、选图、语音、位置等手机系统的能力,同时可以直接使用企业微信分享、扫一扫等企业微信特有的能力,为企业微信用户提供更优质的网页体验。

此文档面向网页开发者介绍企业微信JS-SDK如何使用及相关注意事项。

使用说明

所有的JS接口只能在企业微信应用的可信域名下调用(包括子域名),且可信域名必须有ICP备案且在管理端验证域名归属。
验证域名归属的方法在企业微信的管理后台“我的应用”里,进入应用,设置应用可信域名。

步骤一:引入JS文件

在需要调用JS接口的页面引入如下JS文件,(支持https):http://res.wx.qq.com/open/js/jweixin-1.2.0.js

为支持微工作台(原企业号)功能,请引用此文件。原企业微信的js文件在微工作台侧不生效。

备注:支持使用 AMD/CMD 标准模块加载方法加载

步骤二:通过config接口注入权限验证配置

所有需要使用JS-SDK的页面必须先注入配置信息,否则将无法调用(同一个url仅需调用一次,对于变化url的SPA的web app可在每次url变化时进行调用)。

wx.config({
    beta: true,// 必须这么写,否则wx.invoke调用形式的jsapi会有问题
    debug: true, // 开启调试模式,调用的所有api的返回值会在客户端alert出来,若要查看传入的参数,可以在pc端打开,参数信息会通过log打出,仅在pc端时才会打印。
    appId: '', // 必填,企业微信的corpID
    timestamp: , // 必填,生成签名的时间戳
    nonceStr: '', // 必填,生成签名的随机串
    signature: '',// 必填,签名,见附录1
    jsApiList: [] // 必填,需要使用的JS接口列表,所有JS接口列表见附录2
});

步骤三:通过ready接口处理成功验证

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

步骤四:通过error接口处理失败验证

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

接口调用说明

所有接口通过wx对象(也可使用jWeixin对象)来调用,参数是一个对象,除了每个接口本身需要传的参数之外,还有以下通用参数:

  1. success:接口调用成功时执行的回调函数。
  2. fail:接口调用失败时执行的回调函数。
  3. complete:接口调用完成时执行的回调函数,无论成功或失败都会执行。
  4. cancel:用户点击取消时的回调函数,仅部分有用户取消操作的api才会用到。
  5. trigger: 监听Menu中的按钮点击时触发的方法,该方法仅支持Menu中的相关接口。

注意:不要尝试在trigger中使用ajax异步请求修改本次分享的内容,因为客户端分享操作是一个同步操作,这时候使用ajax的回包会还没有返回

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

  1. 调用成功时:”xxx:ok” ,其中xxx为调用的接口名
  2. 用户取消时:”xxx:cancel”,其中xxx为调用的接口名
  3. 调用失败时:其值为具体错误信息

基础接口

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

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

通过agentConfig注入应用的权限

wx.agentConfig({
    corpid: '', // 必填,企业微信的corpid,必须与当前登录的企业一致
    agentid: '', // 必填,企业微信的应用id
    timestamp: , // 必填,生成签名的时间戳
    nonceStr: '', // 必填,生成签名的随机串
    signature: '',// 必填,签名,见附录1
    jsApiList: [], //必填
    success: function(res) {
        // 回调
    },
    fail: function(res) {
        if(res.errMsg.indexOf('function not exist') > -1){
            alert('版本过低请升级')
        }
    }
});

agentConfig的作用
config注入的是企业的身份与权限,而agentConfig注入的是应用的身份与权限。尤其是当调用者为第三方服务商时,通过config无法准确区分出调用者是哪个第三方应用,而在部分场景下,又必须严谨区分出第三方应用的身份,此时即需要通过agentConfig来注入应用的身份信息。

调用agentConfig的注意事项

  1. agentConfig与config的签名算法完全一样,但是jsapi_ticket的获取方法不一样,请特别注意,查看”获取应用身份的ticket“.
  2. 调用wx.agentConfig之前,必须确保先成功调用wx.config
  3. 当前页面url中的域名必须是在该应用中设置的可信域名。
  4. agentConfig仅在企业微信2.5.0及以后版本支持,微信侧不支持(微信开发者工具也不支持)。

需要agentConfig的接口列表

  • selectExternalContact
  • openUserProfile
  • thirdPartyOpenPage
  • getCurExternalContact

通讯录和会话接口

通讯录选人接口

wx.invoke("selectEnterpriseContact", {
                "fromDepartmentId": -1,// 必填,表示打开的通讯录从指定的部门开始展示,-1表示自己所在部门开始, 0表示从最上层开始
                "mode": "multi",// 必填,选择模式,single表示单选,multi表示多选
                "type": ["department", "user"],// 必填,选择限制类型,指定department、user中的一个或者多个
                "selectedDepartmentIds": ["2","3"],// 非必填,已选部门ID列表。用于多次选人时可重入,single模式下请勿填入多个id
                "selectedUserIds": ["lisi","lisi2"]// 非必填,已选用户ID列表。用于多次选人时可重入,single模式下请勿填入多个id
        },function(res){
                if (res.err_msg == "selectEnterpriseContact:ok")
                {
                        if(typeof res.result == 'string')
                        {
                                res.result = JSON.parse(res.result) //由于目前各个终端尚未完全兼容,需要开发者额外判断result类型以保证在各个终端的兼容性
                        }

                        var selectedDepartmentList = res.result.departmentList;// 已选的部门列表
                        for (var i = 0; i < selectedDepartmentList.length; i++)
                        {
                                var department = selectedDepartmentList[i];
                                var departmentId = department.id;// 已选的单个部门ID
                                var departemntName = department.name;// 已选的单个部门名称
                        }
                        var selectedUserList = res.result.userList; // 已选的成员列表
                        for (var i = 0; i < selectedUserList.length; i++)
                        {
                                var user = selectedUserList[i];
                                var userId = user.id; // 已选的单个成员ID
                                var userName = user.name;// 已选的单个成员名称
                                var userAvatar= user.avatar;// 已选的单个成员头像
                        }
                }
        }
);

此接口在企业微信1.3.11及以后版本支持,微信6.5.10及以后版本支持。调用此接口时,config接口必须传入beta参数

创建会话接口

wx.openEnterpriseChat({
        // 注意:userIds和externalUserIds至少选填一个,且userIds+openIds总数不能超过2000。
    userIds: 'zhangshan;lisi;wangwu',    //参与会话的企业成员列表,格式为userid1;userid2;...,用分号隔开。
    externalUserIds: 'wmEAlECwAAHrbWYDOK666Af13xlYDAAA;wmEAlECwAAHrbWY6665u3Af13xlYDAAA', // 参与会话的外部联系人列表,格式为userId1;userId2;…,用分号隔开。
    groupName: '讨论组',  // 必填,会话名称。单聊时该参数传入空字符串""即可。
    success: function(res) {
        // 回调
    },
    fail: function(res) {
        if(res.errMsg.indexOf('function not exist') > -1){
            alert('版本过低请升级')
        }
    }
});

此接口在企业微信2.0及以后版本支持,externalUserIds参数仅在企业微信2.4.20及以后版本支持,externalUserIds由外部联系人选人接口selectExternalContact获得;
由于目前暂不支持包含微信联系人的群聊,所以externalUserIds中最多只能有一个微信联系人,而且一旦externalUserIds中有微信联系人,就不能再传userIds参数。

外部联系人选人接口

调用此接口将唤起该成员里所有的外部联系人列表,获取员工选择的外部联系人的userid

wx.invoke('selectExternalContact', {
                        "filterType": 0, //0表示展示全部外部联系人列表,1表示仅展示未曾选择过的外部联系人。默认值为0;除了0与1,其他值非法。在企业微信2.4.22及以后版本支持该参数
        }, function(res){
        if(res.err_msg == "selectExternalContact:ok"){
            userIds  = res.userIds ; //返回此次选择的外部联系人userId列表,数组类型
        }else {
            //错误处理
        }
    });

此接口仅在企业微信2.4.20及以后版本支持,微信侧不支持(微信开发者工具也不支持)。
如果调用者是第三方服务商,必须先成功调用agentConfig,否则调用时会报no permission错误.

打开个人信息页接口

调用此接口将唤起成员或外部联系人的个人信息页面

wx.invoke('openUserProfile', {
                        "type": 1, //1表示该userid是企业成员,2表示该userid是外部联系人
                        "userid": "wmEAlECwAAHrbWY6665u3Af13xlYDAAA" //可以是企业成员,也可以是外部联系人
        }, function(res){
        if(res.err_msg != "openUserProfile:ok"){
            //错误处理
        }
    });

此接口仅在企业微信2.4.20及以后版本支持,微信侧不支持(微信开发者工具也不支持)。
如果调用者是第三方服务商,必须先成功调用agentConfig,否则调用时会报“no permission”错误.

获取当前外部联系人userid

从外部联系人的profile进入页面时才可成功调用该接口

wx.invoke('getCurExternalContact', {
        }, function(res){
        if(res.err_msg == "getCurExternalContact:ok"){
            userId  = res.userId ; //返回当前外部联系人userId
        }else {
            //错误处理
        }
    });

此接口仅在企业微信2.5.8及以后版本支持,微信侧不支持(微信开发者工具也不支持)。
必须先成功调用agentConfig,否则调用时会报“no permission”错误。
当前成员必须在agentConfig中所填agentid的应用的可见范围之内,否则会报“user not in allow list”错误。
需要从外部联系人的profile进入页面才能获取,否则会报错:without context of external contact

分享接口

分享接口仅激活的成员数超过200人且已经认证的企业才可在微信上调用

获取“转发”按钮点击状态及自定义分享内容接口

wx.onMenuShareAppMessage({
    title: '', // 分享标题
    desc: '', // 分享描述
    link: '', // 分享链接
    imgUrl: '', // 分享图标
    success: function () {
        // 用户确认分享后执行的回调函数
    },
    cancel: function () {
        // 用户取消分享后执行的回调函数
    }
});

获取“微信”按钮点击状态及自定义分享内容接口

wx.onMenuShareWechat({
    title: '', // 分享标题
    desc: '', // 分享描述
    link: '', // 分享链接
    imgUrl: '', // 分享图标
    success: function () {
        // 用户确认分享后执行的回调函数
    },
    cancel: function () {
        // 用户取消分享后执行的回调函数
    }
});

获取“分享到朋友圈”按钮点击状态及自定义分享内容接口

wx.onMenuShareTimeline({
    title: '', // 分享标题
    link: '', // 分享链接
    imgUrl: '', // 分享图标
    success: function () {
        // 用户确认分享后执行的回调函数
    },
    cancel: function () {
        // 用户取消分享后执行的回调函数
    }
});

自定义转发到会话

wx.invoke(
        "shareAppMessage", {
                title: '', // 分享标题
                desc: '', // 分享描述
                link: '', // 分享链接
                imgUrl: '' // 分享封面
    }, function(res) {
        if (res.err_msg == "shareAppMessage:ok") {
        }
    }
);

此接口在企业微信2.4.5及以后版本支持,微信侧不支持(微信开发者工具也不支持)

自定义转发到微信

wx.invoke(
        "shareWechatMessage", {
                title: '', // 分享标题
                desc: '', // 分享描述
                link: '', // 分享链接
                imgUrl: '' // 分享封面
    }, function(res) {
        if (res.err_msg == "shareWechatMessage:ok") {
        }
    }
);

此接口在企业微信2.4.5及以后版本支持,微信侧不支持(微信开发者工具也不支持)

图像与文件接口

获取本地图片接口

wx.getLocalImgData({
    localId: '', // 图片的localID
    success: function (res) {
        var localData = res.localData; // localData是图片的base64数据,可以用img标签显示
}
});

备注:此接口仅在 iOS WKWebview 下提供,用于兼容 iOS WKWebview 不支持 localId 直接显示图片的问题。要求IOS版本为2.4.6及以上

拍照或从手机相册中选图接口

wx.chooseImage({
    count: 1, // 默认9
    sizeType: ['original', 'compressed'], // 可以指定是原图还是压缩图,默认二者都有
    sourceType: ['album', 'camera'], // 可以指定来源是相册还是相机,默认二者都有
    defaultCameraMode: "batch", //表示进入拍照界面的默认模式,目前有normal与batch两种选择,normal表示普通单拍模式,batch表示连拍模式,不传该参数则为normal模式。(注:用户进入拍照界面仍然可自由切换两种模式)
    success: function (res) {
        var localIds = res.localIds; // 返回选定照片的本地ID列表,
                // andriod中localId可以作为img标签的src属性显示图片;
                // 而在IOS中需通过上面的接口getLocalImgData获取图片base64数据,从而用于img标签的显示
    }
});

此接口在企业微信2.3及以后版本支持相机连拍(当sourceType是camera时)
参数defaultCameraMode仅在企业微信2.4.20及以后版本支持
从2.4.6版本开始,IOS版企业微信浏览器将升级为WkWebView,因其不支持原有的直接通过localid作为img标签的src属性来显示图片的方式。开发者需要采用通过getLocalImgData来获取localid对应图片的base64数据。

预览图片接口

wx.previewImage({
    current: '', // 当前显示图片的http链接
    urls: [] // 需要预览的图片http链接列表
});

上传图片接口

wx.uploadImage({
    localId: '', // 需要上传的图片的本地ID,由chooseImage接口获得
    isShowProgressTips: 1, // 默认为1,显示进度提示
    success: function (res) {
        var serverId = res.serverId; // 返回图片的服务器端ID
    }
});

备注:上传图片有效期3天,可用素材管理接口下载图片到自己的服务器,此处获得的 serverId 即 media_id。

下载图片接口

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

预览文件接口

wx.previewFile({
    url: '', // 需要预览文件的地址(必填,可以使用相对路径)
    name: '', // 需要预览文件的文件名(不填的话取url的最后部分)
    size: 1048576 // 需要预览文件的字节大小(必填)
});

备注:此接口将url对应的文件下载后,在内置浏览器中预览。目前支持图片、音频、视频、文档等格式的文件。仅企业微信APP手机端可用

音频接口

开始录音接口

wx.startRecord();

停止录音接口

wx.stopRecord({
    success: function (res) {
        var localId = res.localId;
    }
});

监听录音自动停止接口

wx.onVoiceRecordEnd({
    // 录音时间超过一分钟没有停止的时候会执行 complete 回调
    complete: function (res) {
        var localId = res.localId;
    }
});

播放语音接口

wx.playVoice({
    localId: '' // 需要播放的音频的本地ID,由stopRecord接口获得
});

暂停播放接口

wx.pauseVoice({
    localId: '' // 需要暂停的音频的本地ID,由stopRecord接口获得
});

停止播放接口

wx.stopVoice({
    localId: '' // 需要停止的音频的本地ID,由stopRecord接口获得
});

监听语音播放完毕接口

wx.onVoicePlayEnd({
    success: function (res) {
        var localId = res.localId; // 返回音频的本地ID
    }
});

上传语音接口

wx.uploadVoice({
    localId: '', // 需要上传的音频的本地ID,由stopRecord接口获得
    isShowProgressTips: 1, // 默认为1,显示进度提示
    success: function (res) {
        var serverId = res.serverId; // 返回音频的服务器端ID
    }
});

备注:上传语音有效期3天,可用素材管理下载语音到自己的服务器,此处获得的 serverId 即 media_id。

下载语音接口

wx.downloadVoice({
    serverId: '', // 需要下载的音频的服务器端ID,由uploadVoice接口获得
    isShowProgressTips: 1, // 默认为1,显示进度提示
    success: function (res) {
        var localId = res.localId; // 返回音频的本地ID
    }
});

设备信息

获取网络状态接口

wx.getNetworkType({
    success: function (res) {
        var networkType = res.networkType; // 返回网络类型2g,3g,4g,wifi
    }
});

监听网络状态变化

wx.onNetworkStatusChange(function(res) {
  console.log(res.isConnected)
  console.log(res.networkType)
})

CALLBACK 返回参数说明

参数 类型 说明
isConnected Boolean 当前是否有网络连接
networkType String 网络类型

networkType 有效值:

说明
wifi wifi 网络
2g 2g 网络
3g 3g 网络
4g 4g 网络
none 无网络
unknown Android下不常见的网络类型

地理位置

使用企业微信内置地图查看位置接口

wx.openLocation({
    latitude: 0, // 纬度,浮点数,范围为90 ~ -90
    longitude: 0, // 经度,浮点数,范围为180 ~ -180。
    name: '', // 位置名
    address: '', // 地址详情说明
    scale: 1, // 地图缩放级别,整形值,范围从1~28。默认为16
});

获取地理位置接口

wx.getLocation({
    type: 'wgs84', // 默认为wgs84的gps坐标,如果要返回直接给openLocation用的火星坐标,可传入'gcj02'
    success: function (res) {
        var latitude = res.latitude; // 纬度,浮点数,范围为90 ~ -90
        var longitude = res.longitude; // 经度,浮点数,范围为180 ~ -180。
        var speed = res.speed; // 速度,以米/每秒计
        var accuracy = res.accuracy; // 位置精度
    }
});

企业微信App不支持speed参数,输出固定为0

打开持续定位接口

开始持续获取LBS信息

wx.invoke('startAutoLBS',{
                    type: 'gcj02', // wgs84是gps坐标,gcj02是火星坐标
                },
          function(res) {
             if(res.err_msg == "startAutoLBS:ok"){
                //调用成功
             }else {
                //错误处理
            }
          });

此接口仅在企业微信2.4.20及以后版本支持。

停止持续定位接口

停止获取LBS信息

wx.invoke('stopAutoLBS',{},
          function(res) {
             if(res.err_msg == "stopAutoLBS:ok"){
                //调用成功
             }else {
                //错误处理
            }
          });

此接口仅在企业微信2.4.20及以后版本支持。

监听地理位置变化

用于监听地理位置的变化,前提是已经成功调用startAutoLBS。(注意:需提醒用户一直停留在当前页面)

wx.onLocationChange( 
  function(res) {
    if(res.errMsg == "auto:location:report:ok"){
      var latitude = res.latitude; // 纬度,浮点数,范围为90 ~ -90
      var longitude = res.longitude; // 经度,浮点数,范围为180 ~ -180。
      var speed = res.speed; // 速度,以米/每秒计
      var accuracy = res.accuracy; // 位置精度
      var lbsIndex = 0;
    }else {
      //错误处理
    }
  }
);

此接口仅在企业微信2.4.20及以后版本支持。

界面操作

监听页面返回事件

接口说明:该接口可在用户返回上个页面时,回调开发者注册的函数,处理业务需要的逻辑(如确认或重定向到指定的页面)

wx.onHistoryBack(function(){
    return confirm('确定要放弃当前页面的修改?')
});

响应函数须返回布尔值false或true。false表示中断此次返回操作,否则继续执行返回操作
当页面左上角没有关闭按钮(即已是顶级页面),不产生该事件,强制执行返回
iOS系统使用手势返回时,不产生该事件,强制执行返回
此接口在企业微信IOS/Anriod端2.2.0及以后版本支持,PC/Mac端在2.4.5版本及以后版本支持

隐藏右上角菜单接口

wx.hideOptionMenu();

显示右上角菜单接口

wx.showOptionMenu();

关闭当前网页窗口接口

wx.closeWindow();

批量隐藏功能按钮接口

wx.hideMenuItems({
    menuList: [] // 要隐藏的菜单项,所有menu项见附录3
});

批量显示功能按钮接口

wx.showMenuItems({
    menuList: [] // 要显示的菜单项,所有menu项见附录3
});

隐藏所有非基础按钮接口

wx.hideAllNonBaseMenuItem();

显示所有功能按钮接口

wx.showAllNonBaseMenuItem();

打开系统默认浏览器

接口说明:该接口可在PC版企业微信用系统浏览器打开指定的URL,以获得更好的体验。指定的URL支持oauth2标准,从而实现在系统浏览器内免登录的效果。

wx.invoke('openDefaultBrowser', {
        'url': "https://open.weixin.qq.com/connect/oauth2/authorize?appid=CORPID&redirect_uri=REDIRECT_URI&response_type=code&scope=SCOPE&agentid=AGENTID&state=STATE#wechat_redirect", // 在默认浏览器打开redirect_uri,并附加code参数;也可以直接指定要打开的url,此时不会附带上code参数。
        }, function(res){
        if(res.err_msg != "openDefaultBrowser:ok"){
            //错误处理
                }
        });

此接口仅在企业微信PC版2.3及以后版本支持。其中url支持oauth2链接,具体参考“网页授权登录”。

用户截屏事件

监听用户主动截屏事件,用户使用系统截屏按键截屏时触发此事件

用户截屏事件接口在企业微信2.5.0版本及以上支持,仅andriod及ios端支持。

wx.onUserCaptureScreen(function(res) {
    console.log('用户截屏了')
})

企业微信扫一扫

调起企业微信扫一扫接口

wx.scanQRCode({
    desc: 'scanQRCode desc',
    needResult: 0, // 默认为0,扫描结果由企业微信处理,1则直接返回扫描结果,
    scanType: ["qrCode", "barCode"], // 可以指定扫二维码还是一维码,默认二者都有
    success: function(res) {
        // 回调
    },
    error: function(res) {
        if (res.errMsg.indexOf('function_not_exist') > 0) {
            alert('版本过低请升级')
        }
    }
});

拉起电子发票列表

接口说明:该接口功能为在微信内拉起用户发票卡券列表,用户勾选需要提交报销的发票后,开发者获得所选发票的标识信息。仅手机端可用

wx.invoke('chooseInvoice', {
                'timestamp': '', // 卡券签名时间戳 
                'nonceStr': '', // 卡券签名随机串 
                'signType': '', // 签名方式,默认'SHA1' 
                'cardSign': '', // 卡券签名 
        }, function(res) {
        // 这里是回调函数 
                alert(JSON.stringify(res)); // 返回的结果 
        });

注意,调用此接口时,config接口必须传入beta参数。

参数说明

返回值 说明
err_msg choose_invoice:ok 选取发票成功
err_msg choose_invoice: fail 选取发票失败
err_msg choose_invoice: cancel 选取发票取消
choose_invoice_info 用户选中的发票列表

choose_invoice_info的元素的结构如下

{ card_id = “”, encrypt_code = “” app_id=”” }

使用说明

此接口在企业微信2.1.0及以后版本支持

发票签名方法

参数说明

参数 说明
cardType 填入INVOICE
timestamp 拉起发票列表时使用的时间戳
appid 调用该接口的appid
nonceStr 随机字符串
api_ticket 通过acess_token换取的临时票据,详情请见获取电子发票ticket

签名方法
将 api_ticket、appid、timestamp、nonceStr、cardType的value值进行字符串的字典序排序。再将所有参数字符串拼接成一个字符串进行sha1加密,得到cardSign。
例如:api_ticket=aaa、appid=bbb、timestamp=ddd、nonceStr=ccc、cardType=eee,那么先拼成字符串aaabbbcccdddeee,再将此字符串进行sha1加密,得到cardSign。
签名算法工具,参考 电子发票签名签名生成工具

获取电子发票ticket

请求方式:GET(HTTPS
请求地址:https://qyapi.weixin.qq.com/cgi-bin/ticket/get?access_token=ACCESS_TOKEN&type=wx_card

参数说明:

参数 必须 说明
access_token 调用接口凭证

返回数据:

{
   "errcode":0,
   "errmsg":"ok",
   "ticket":"pIKi3wRPNWCGF-pyP-YU5KWjDDD",
   "expires_in":7200
}

参数说明:

参数 说明
errcode 错误码
errmsg 错误描述
ticket 发票签名临时票据
expires_in 有效期,以秒为单位。在有效期内重复请求,ticket不会被刷新

Wi-Fi 接口

支持搜索周边的 Wi-Fi,同时可以针对指定 Wi-Fi,传入密码发起连接。

连接指定 Wi-Fi 接口调用时序:
startWifi —> connectWifi —> onWifiConnected

Wi-Fi接口仅企业微信andriod 2.4.16版本及以上支持。
Android 6.0 以上版本,在没有打开定位开关的时候会导致设备不能正常获取周边的 Wi-Fi 信息。

初始化 Wi-Fi 模块

wx.startWifi({
  success: function(res) {
    console.log(res.errMsg)
  }
})

请求参数说明

参数 类型 必填 说明
success Function 接口调用成功的回调函数
fail Function 接口调用失败的回调函数
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)

关闭 Wi-Fi 模块

wx.stopWifi({
  success: function(res) {
    console.log(res.errMsg)
  }
})

请求参数说明

参数 类型 必填 说明
success Function 接口调用成功的回调函数
fail Function 接口调用失败的回调函数
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)

连接 Wi-Fi

若已知 Wi-Fi 信息,可以直接利用该接口连接。

wx.connectWifi({
  SSID: 'vincenthome',  // 设备SSID
  BSSID: '8c:a6:df:c8:f7:4b',  // 设备BSSID
  password: 'test1234',  // 设备密码
  success: function(res) {
    console.log(res.errMsg)
  }
})

请求参数说明

参数 类型 必填 说明
SSID String Wi-Fi 设备SSID
BSSID String Wi-Fi 设备BSSID
password String Wi-Fi 设备密码
success Function 接口调用成功的回调函数
fail Function 接口调用失败的回调函数
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)

请求获取 Wi-Fi 列表

请求获取 Wi-Fi 列表,在 onGetWifiList 注册的回调中返回 wifiList 数据。

wx.getWifiList({
  success: function(res) {
      console.log(res.errMsg)
  }
})

请求参数说明

参数 类型 必填 说明
success Function 接口调用成功的回调函数
fail Function 接口调用失败的回调函数
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)

监听获取到 Wi-Fi 列表事件

监听在获取到 Wi-Fi 列表数据时的事件,在回调中将返回 wifiList。

wx.onGetWifiList(function(res) {
  if (res.wifiList.length) {
       for(var i = 0; i < res.wifiList.length; i++)
       {
           console.log("=====wifiList======")
           console.log("SSID:"  +  res.wifiList[i].SSID)
           console.log("BSSID:" + res.wifiList[i].BSSID)
           console.log("secure:" + res.wifiList[i].secure)
           console.log("secure:" + res.wifiList[i].signalStrength)
           console.log("====================")
        }
  }
})

CALLBACK 返回参数说明

参数 类型 说明
wifiList Array Wi-Fi 列表数据

Wi-Fi 列表项说明:

参数 类型 说明
SSID String Wi-Fi 的SSID
BSSID String Wi-Fi 的BSSID
secure Boolean Wi-Fi 是否安全
signalStrength Number Wi-Fi 信号强度

监听连接上 Wi-Fi 的事件

wx.onWifiConnected(function(res) {
   console.log(res.wifi)
})

CALLBACK 返回参数说明

参数 类型 说明
wifi Object Wi-Fi 信息

Wi-Fi 信息说明:

参数 类型 说明
SSID String Wi-Fi 的SSID
BSSID String Wi-Fi 的BSSID
secure Boolean Wi-Fi 是否安全
signalStrength Number Wi-Fi 信号强度

获取已连接中的 Wi-Fi 信息

wx.getConnectedWifi({
   success: function(res){
       console.log(res.wifi)
   }
})

请求参数说明

参数 类型 必填 说明
success Function 接口调用成功的回调函数
fail Function 接口调用失败的回调函数
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)

success返回参数说明:

参数 类型 说明
wifi Object Wi-Fi 信息

Wi-Fi 信息说明:

参数 类型 说明
SSID String Wi-Fi 的SSID
BSSID String Wi-Fi 的BSSID
secure Boolean Wi-Fi 是否安全
signalStrength Number Wi-Fi 信号强度

Wi-Fi接口错误码列表

错误码 错误码说明
0 正常
12000 未先调用startWifi接口
12001 当前系统不支持相关能力
12002 Wi-Fi 密码错误
12003 连接超时
12004 重复连接 Wi-Fi
12005 Android特有,未打开 Wi-Fi 开关
12006 Android特有,未打开 GPS 定位开关
12007 用户拒绝授权连接 Wi-Fi
12008 无效SSID
12009 系统运营商配置拒绝连接 Wi-Fi
12010 系统其他错误,需要在errmsg打印具体的错误原因
12011 应用在后台无法配置 Wi-Fi

剪贴板接口

支持设置及获取系统剪贴板内容

剪贴板接口在企业微信2.4.16版本及以上支持,仅andriod及ios端支持。

设置系统剪贴板的内容

wx.setClipboardData({
  data: 'data',    // 设置的
  success: function(res) {
      console.log(res.errMsg)
  }
})

请求参数说明

参数 类型 必填 说明
data String 剪贴板的内容
success Function 接口调用成功的回调函数
fail Function 接口调用失败的回调函数
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)

获取系统剪贴板内容

wx.getClipboardData({
   success: function(res) {
       console.log(res.data)
  }
})

请求参数说明

参数 类型 必填 说明
success Function 接口调用成功的回调函数
fail Function 接口调用失败的回调函数
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)

success返回参数说明:

参数 类型 说明
data String 剪贴板的内容

蓝牙接口

wx.openBluetoothAdapter

初始化蓝牙模块

wx.openBluetoothAdapter({
  success: function (res) {
    console.log(res)
  }
})

请求参数说明

参数 类型 必填 说明
success Function 接口调用成功的回调函数
fail Function 接口调用失败的回调函数
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)

wx.closeBluetoothAdapter

关闭蓝牙模块,使其进入未初始化状态。调用该方法将断开所有已建立的链接并释放系统资源。

wx.closeBluetoothAdapter({
  success: function (res) {
    console.log(res)
  }
})

请求参数说明

参数 类型 必填 说明
success Function 接口调用成功的回调函数
fail Function 接口调用失败的回调函数
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)

wx.getBluetoothAdapterState

获取本机蓝牙适配器状态

wx.getBluetoothAdapterState({
  success: function (res) {
    console.log(res)
  }
})

请求参数说明

参数 类型 必填 说明
success Function 接口调用成功的回调函数
fail Function 接口调用失败的回调函数
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)

success返回参数说明:

参数 类型 说明
discovering Boolean 是否正在搜索设备
available Boolean 蓝牙适配器是否可用
errMsg String 成功:ok,错误:详细信息

wx.onBluetoothAdapterStateChange

监听蓝牙适配器状态变化事件

wx.onBluetoothAdapterStateChange(function(res) {
  console.log(`adapterState changed, now is`, res)
})

CALLBACK 返回参数说明

参数 类型 说明
discovering Boolean 是否正在搜索设备
available Boolean 蓝牙适配器是否可用

wx.startBluetoothDevicesDiscovery

开始搜寻附近的蓝牙外围设备。注意,该操作比较耗费系统资源,请在搜索并连接到设备后调用 stop 方法停止搜索。

// 以微信硬件平台的蓝牙智能灯为例,主服务的 UUID 是 FEE7。传入这个参数,只搜索主服务 UUID 为 FEE7 的设备
wx.startBluetoothDevicesDiscovery({
  services: ['FEE7'],
  success: function (res) {
    console.log(res)
  }
})

请求参数说明

参数 类型 必填 说明
services Array 蓝牙设备主 service 的 uuid 列表
allowDuplicatesKey Boolean 是否允许重复上报同一设备, 如果允许重复上报,则onDeviceFound 方法会多次上报同一设备,但是 RSSI 值会有不同
interval Number 上报设备的间隔,默认为0,意思是找到新设备立即上报,否则根据传入的间隔上报
success Function 接口调用成功的回调函数
fail Function 接口调用失败的回调函数
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)

services参数说明:某些蓝牙设备会广播自己的主 service 的 uuid。如果这里传入该数组,那么根据该 uuid 列表,只搜索发出广播包有这个主服务的蓝牙设备,建议主要通过该参数过滤掉周边不需要处理的其他蓝牙设备。

success返回参数说明:

参数 类型 说明
errMsg String 成功:ok,错误:详细信息

wx.stopBluetoothDevicesDiscovery

停止搜寻附近的蓝牙外围设备。若已经找到需要的蓝牙设备并不需要继续搜索时,建议调用该接口停止蓝牙搜索。

wx.stopBluetoothDevicesDiscovery({
  success: function (res) {
    console.log(res)
  }
})

请求参数说明

参数 类型 必填 说明
success Function 接口调用成功的回调函数
fail Function 接口调用失败的回调函数
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)

success返回参数说明:

参数 类型 说明
errMsg String 成功:ok,错误:详细信息

wx.getBluetoothDevices

获取在蓝牙模块生效期间所有已发现的蓝牙设备,包括已经和本机处于连接状态的设备。

// ArrayBuffer转16进度字符串示例
function ab2hex(buffer) {
  var hexArr = Array.prototype.map.call(
    new Uint8Array(buffer),
    function(bit) {
      return ('00' + bit.toString(16)).slice(-2)
    }
  )
  return hexArr.join('');
}
wx.getBluetoothDevices({
  success: function (res) {
    console.log(res)
    if (res.devices[0]) {
      console.log(ab2hex(res.devices[0].advertisData))
    }
  }
})

请求参数说明

参数 类型 必填 说明
success Function 接口调用成功的回调函数
fail Function 接口调用失败的回调函数
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)

success返回参数说明:

参数 类型 说明
errMsg String 成功:ok,错误:详细信息
devices Array uuid 对应的的已连接设备列表

device 对象:
蓝牙设备信息

参数 类型 说明
name String 蓝牙设备名称,某些设备可能没有
deviceId String 用于区分设备的 id
RSSI Number 当前蓝牙设备的信号强度
advertisData ArrayBuffer 当前蓝牙设备的广播数据段中的ManufacturerData数据段 (注意:vConsole 无法打印出 ArrayBuffer 类型数据)
advertisServiceUUIDs Array 当前蓝牙设备的广播数据段中的ServiceUUIDs数据段
localName String 当前蓝牙设备的广播数据段中的LocalName数据段
serviceData ArrayBuffer 当前蓝牙设备的广播数据段中的ServiceData数据段
  1. tip: Mac系统可能无法获取advertisData及RSSI,请使用真机调试
  2. tip: 开发者工具和 Android 上获取到的deviceId为设备 MAC 地址,iOS 上则为设备 uuid。因此deviceId不能硬编码到代码中
  3. tip: 注意该接口获取到的设备列表为蓝牙模块生效期间所有搜索到的蓝牙设备,若在蓝牙模块使用流程结束后未及时调用 wx.closeBluetoothAdapter 释放资源,会存在调用该接口会返回之前的蓝牙使用流程中搜索到的蓝牙设备,可能设备已经不在用户身边,无法连接。
  4. tip: 蓝牙设备在被搜索到时,系统返回的 name 字段一般为广播包中的LocalName字段中的设备名称,而如果与蓝牙设备建立连接,系统返回的 name 字段会改为从蓝牙设备上获取到的GattName。若需要动态改变设备名称并展示,建议使用localName字段。

wx.onBluetoothDeviceFound

监听寻找到新设备的事件

// ArrayBuffer转16进度字符串示例
function ab2hex(buffer) {
  var hexArr = Array.prototype.map.call(
    new Uint8Array(buffer),
    function(bit) {
      return ('00' + bit.toString(16)).slice(-2)
    }
  )
  return hexArr.join('');
}
wx.onBluetoothDeviceFound(function(devices) {
  console.log('new device list has founded')
  console.dir(devices)
  console.log(ab2hex(devices[0].advertisData))
})

CALLBACK 返回参数说明

参数 类型 说明
devices Array 新搜索到的设备列表

device 对象
蓝牙设备信息

参数 类型 说明
name String 蓝牙设备名称,某些设备可能没有
deviceId String 用于区分设备的 id
RSSI Number 当前蓝牙设备的信号强度
advertisData ArrayBuffer 当前蓝牙设备的广播数据段中的ManufacturerData数据段 (注意:vConsole 无法打印出 ArrayBuffer 类型数据)
advertisServiceUUIDs Array 当前蓝牙设备的广播数据段中的ServiceUUIDs数据段
localName String 当前蓝牙设备的广播数据段中的LocalName数据段
serviceData ArrayBuffer 当前蓝牙设备的广播数据段中的ServiceData数据段
  1. tip: Mac系统可能无法获取advertisData及RSSI,请使用真机调试
  2. tip: 开发者工具和 Android 上获取到的deviceId为设备 MAC 地址,iOS 上则为设备 uuid。因此deviceId不能硬编码到代码中
  3. tip: 若在onBluetoothDeviceFound回调了某个设备,则此设备会添加到 wx.getBluetoothDevices 接口获取到的数组中

wx.getConnectedBluetoothDevices

根据 uuid 获取处于已连接状态的设备

wx.getConnectedBluetoothDevices({
  success: function (res) {
    console.log(res)
  }
})

请求参数说明

参数 类型 必填 说明
services Array 蓝牙设备主 service 的 uuid 列表
success Function 接口调用成功的回调函数
fail Function 接口调用失败的回调函数
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)

success返回参数说明:

参数 类型 说明
errMsg String 成功:ok,错误:详细信息
devices Array 搜索到的设备列表

device 对象:
蓝牙设备信息

参数 类型 说明
name String 蓝牙设备名称,某些设备可能没有
deviceId String 用于区分设备的 id

Bug & Tip

  1. tip: 开发者工具和 Android 上获取到的deviceId为设备 MAC 地址,iOS 上则为设备 uuid。因此deviceId不能硬编码到代码中

低功耗蓝牙接口

wx.createBLEConnection

连接低功耗蓝牙设备。

wx.createBLEConnection({
  // 这里的 deviceId 需要已经通过 createBLEConnection 与对应设备建立链接 
  deviceId: deviceId,
  success: function (res) {
    console.log(res)
  }
})

请求参数说明

参数 类型 必填 说明
deviceId String 蓝牙设备 id,参考 getDevices 接口
success Function 接口调用成功的回调函数
fail Function 接口调用失败的回调函数
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)

success返回参数说明:

参数 类型 说明
errMsg String 成功:ok,错误:详细信息

Bug & Tip

  1. tip: 安卓手机上如果多次调用create创建连接,有可能导致系统持有同一设备多个连接的实例,导致调用close的时候并不能真正的断开与设备的连接。因此请保证尽量成对的调用create和close接口
  2. tip: 蓝牙链接随时可能断开,建议监听 wx.onBLEConnectionStateChange 回调事件,当蓝牙设备断开时按需执行重连操作
  3. tip: 若对未连接的设备或已断开连接的设备调用数据读写操作的接口,会返回10006错误,详见错误码,建议进行重连操作

wx.closeBLEConnection

断开与低功耗蓝牙设备的连接

wx.closeBLEConnection({
  deviceId:deviceId
  success: function (res) {
    console.log(res)
  }
})

请求参数说明

参数 类型 必填 说明
deviceId String 蓝牙设备 id,参考 getDevices 接口
success Function 接口调用成功的回调函数
fail Function 接口调用失败的回调函数
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)

success返回参数说明:

参数 类型 说明
errMsg String 成功:ok,错误:详细信息

wx.onBLEConnectionStateChange

监听低功耗蓝牙连接状态的改变事件,包括开发者主动连接或断开连接,设备丢失,连接异常断开等等

wx.onBLEConnectionStateChange(function(res) {
  // 该方法回调中可以用于处理连接意外断开等异常情况
  console.log(`device ${res.deviceId} state has changed, connected: ${res.connected}`)
})

CALLBACK 返回参数说明

参数 类型 说明
deviceId String 蓝牙设备 id,参考 device 对象
connected Boolean 连接目前的状态

wx.getBLEDeviceServices

获取蓝牙设备所有 service(服务)

wx.getBLEDeviceServices({
  // 这里的 deviceId 需要已经通过 createBLEConnection 与对应设备建立链接 
  deviceId: deviceId,
  success: function (res) {
    console.log('device services:', res.services)
  }
})

请求参数说明

参数 类型 必填 说明
deviceId String 蓝牙设备 id,参考 getDevices 接口
success Function 接口调用成功的回调函数
fail Function 接口调用失败的回调函数
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)

success返回参数说明:

参数 类型 说明
services Array 设备服务列表
errMsg String 成功:ok,错误:详细信息

service对象
蓝牙设备service(服务)信息

参数 类型 说明
uuid String 蓝牙设备服务的 uuid
isPrimary Boolean 该服务是否为主服务

Bug & Tip

  1. tip:iOS平台上后续对特征值的read、write、notify,由于系统需要获取特征值实例,传入的 serviceId 与 characteristicId 必须由 getBLEDeviceServices 与 getBLEDeviceCharacteristics 中获取到后才能使用。建议双平台统一在建立链接后先执行 getBLEDeviceServices 与 getBLEDeviceCharacteristics 后再进行与蓝牙设备的数据交互

wx.getBLEDeviceCharacteristics

获取蓝牙设备某个服务中的所有 characteristic(特征值)

wx.getBLEDeviceServices({
  // 这里的 deviceId 需要已经通过 createBLEConnection 与对应设备建立链接 
  deviceId: deviceId,
  success: function (res) {
    console.log('device services:', res.services)
  }
})

请求参数说明

参数 类型 必填 说明
deviceId String 蓝牙设备 id,参考 getDevices 接口
serviceId String 蓝牙服务 uuid
success Function 接口调用成功的回调函数
fail Function 接口调用失败的回调函数
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)

success返回参数说明:

参数 类型 说明
characteristics Array 设备特征值列表
errMsg String 成功:ok,错误:详细信息

characteristic对象
蓝牙设备characteristic(特征值)信息

参数 类型 说明
uuid String 蓝牙设备特征值的 uuid
properties Object 该特征值支持的操作类型

properties对象

参数 类型 说明
read Boolean 该特征值是否支持 read 操作
write Boolean 该特征值是否支持 write 操作
notify Boolean 该特征值是否支持 notify 操作
indicate Boolean 该特征值是否支持 indicate 操作

Bug & Tip

  1. tip:传入的serviceId需要在getBLEDeviceServices获取到
  2. tip:iOS平台上后续对特征值的read、write、notify,由于系统需要获取特征值实例,传入的 serviceId 与 characteristicId 必须由 getBLEDeviceServices 与 getBLEDeviceCharacteristics 中获取到后才能使用。建议双平台统一在建立链接后先执行 getBLEDeviceServices 与 getBLEDeviceCharacteristics 后再进行与蓝牙设备的数据交互

wx.readBLECharacteristicValue

读取低功耗蓝牙设备的特征值的二进制数据值。注意:必须设备的特征值支持read才可以成功调用,具体参照 characteristic 的 properties 属性

// 必须在这里的回调才能获取
wx.onBLECharacteristicValueChange(function(characteristic) {
  console.log('characteristic value comed:', characteristic)
})

wx.readBLECharacteristicValue({
  // 这里的 deviceId 需要已经通过 createBLEConnection 与对应设备建立链接  [**new**]
  deviceId: deviceId,
  // 这里的 serviceId 需要在上面的 getBLEDeviceServices 接口中获取
  serviceId: serviceId,
  // 这里的 characteristicId 需要在上面的 getBLEDeviceCharacteristics 接口中获取
  characteristicId: characteristicId,
  success: function (res) {
    console.log('readBLECharacteristicValue:', res.errCode)
  }
})

请求参数说明

参数 类型 必填 说明
deviceId String 蓝牙设备 id,参考 device 对象
serviceId String 蓝牙特征值对应服务的 uuid
characteristicId String 蓝牙特征值的 uuid
success Function 接口调用成功的回调函数
fail Function 接口调用失败的回调函数
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)

success返回参数说明:

参数 类型 说明
errCode Number 错误码
errMsg String 成功:ok,错误:详细信息

Bug & Tip

  1. tip:并行调用多次读写接口存在读写失败的可能性。
  2. tip:read接口读取到的信息需要在onBLECharacteristicValueChange方法注册的回调中获取。

wx.writeBLECharacteristicValue

向低功耗蓝牙设备特征值中写入二进制数据。注意:必须设备的特征值支持write才可以成功调用,具体参照 characteristic 的 properties 属性

tips: 并行调用多次读写接口存在读写失败的可能性

// 向蓝牙设备发送一个0x00的16进制数据
let buffer = new ArrayBuffer(1)
let dataView = new DataView(buffer)
dataView.setUint8(0, 0)

wx.writeBLECharacteristicValue({
  // 这里的 deviceId 需要在上面的 getBluetoothDevices 或 onBluetoothDeviceFound 接口中获取
  deviceId: deviceId,
  // 这里的 serviceId 需要在上面的 getBLEDeviceServices 接口中获取
  serviceId: serviceId,
  // 这里的 characteristicId 需要在上面的 getBLEDeviceCharacteristics 接口中获取
  characteristicId: characteristicId,
  // 这里的value是ArrayBuffer类型
  value: buffer,
  success: function (res) {
    console.log('writeBLECharacteristicValue success', res.errMsg)
  }
})

请求参数说明

参数 类型 必填 说明
deviceId String 蓝牙设备 id,参考 device 对象
serviceId String 蓝牙特征值对应服务的 uuid
characteristicId String 蓝牙特征值的 uuid
value ArrayBuffer 蓝牙设备特征值对应的二进制值
success Function 接口调用成功的回调函数
fail Function 接口调用失败的回调函数
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)

success返回参数说明:

参数 类型 说明
errMsg String 成功:ok,错误:详细信息

Bug & Tip

  1. tip: 并行调用多次读写接口存在读写失败的可能性。
  2. tip: 接口不会对写入数据包大小做限制,但系统与蓝牙设备会确定蓝牙4.0单次传输的数据大小,超过最大字节数后会发生写入错误,建议每次写入不超过20字节。
  3. tip: 安卓平台上,在调用notify成功后立即调用write接口,在部分机型上会发生 10008 系统错误
  4. bug: 若单次写入数据过长,iOS平台上存在系统不会有任何回调的情况(包括错误回调)。

wx.notifyBLECharacteristicValueChange

启用低功耗蓝牙设备特征值变化时的 notify 功能,订阅特征值。注意:必须设备的特征值支持notify或者indicate才可以成功调用,具体参照 characteristic 的 properties 属性

另外,必须先启用notify才能监听到设备 characteristicValueChange 事件

wx.notifyBLECharacteristicValueChange({
  state: true, // 启用 notify 功能
  // 这里的 deviceId 需要已经通过 createBLEConnection 与对应设备建立链接  
  deviceId: deviceId,
  // 这里的 serviceId 需要在上面的 getBLEDeviceServices 接口中获取
  serviceId: serviceId,
  // 这里的 characteristicId 需要在上面的 getBLEDeviceCharacteristics 接口中获取
  characteristicId: characteristicId,
  success: function (res) {
    console.log('notifyBLECharacteristicValueChange success', res.errMsg)
  }
})

请求参数说明

参数 类型 必填 说明
deviceId String 蓝牙设备 id,参考 device 对象
serviceId String 蓝牙特征值对应服务的 uuid
characteristicId String 蓝牙特征值的 uuid
state Boolean true: 启用 notify; false: 停用 notify
success Function 接口调用成功的回调函数
fail Function 接口调用失败的回调函数
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)

success返回参数说明:

参数 类型 说明
errMsg String 成功:ok,错误:详细信息

Bug & Tip

  1. tip: 订阅操作成功后需要设备主动更新特征值的value,才会触发 wx.onBLECharacteristicValueChange 回调。
  2. tip: 安卓平台上,在调用notify成功后立即调用write接口,在部分机型上会发生 10008 系统错误

wx.onBLECharacteristicValueChange

监听低功耗蓝牙设备的特征值变化。必须先启用notify接口才能接收到设备推送的notification。

// ArrayBuffer转16进度字符串示例
function ab2hex(buffer) {
  var hexArr = Array.prototype.map.call(
    new Uint8Array(buffer),
    function(bit) {
      return ('00' + bit.toString(16)).slice(-2)
    }
  )
  return hexArr.join('');
}
wx.onBLECharacteristicValueChange(function(res) {
  console.log(`characteristic ${res.characteristicId} has changed, now is ${res.value}`)
  console.log(ab2hext(res.value))
})

CALLBACK 返回参数说明

参数 类型 说明
deviceId String 蓝牙设备 id,参考 device 对象
serviceId String 特征值所属服务 uuid
characteristicId String 特征值 uuid
value ArrayBuffer 特征值最新的值 (注意:vConsole 无法打印出 ArrayBuffer 类型数据)

蓝牙错误码(errCode)列表

错误码 说明 备注
0 ok 正常
10000 not init 未初始化蓝牙适配器
10001 not available 当前蓝牙适配器不可用
10002 no device 没有找到指定设备
10003 connection fail 连接失败
10004 no service 没有找到指定服务
10005 no characteristic 没有找到指定特征值
10006 no connection 当前连接已断开
10007 property not support 当前特征值不支持此操作
10008 system error 其余所有系统上报的异常
10009 system not support Android 系统特有,系统版本低于 4.3 不支持BLE

iBeacon接口

wx.startBeaconDiscovery

开始搜索附近的iBeacon设备

wx.startBeaconDiscovery({
    success(res) {
    }
})

请求参数说明

参数 类型 必填 说明
uuids StringArray iBeacon设备广播的 uuids
success Function 接口调用成功的回调函数
fail Function 接口调用失败的回调函数
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)

success返回参数说明:

参数 类型 说明
errMsg String 成功:ok,错误:详细信息

wx.stopBeaconDiscovery

停止搜索附近的iBeacon设备

wx.stopBeaconDiscovery({
    success(res) {
    }
})

请求参数说明

参数 类型 必填 说明
success Function 接口调用成功的回调函数
fail Function 接口调用失败的回调函数
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)

success返回参数说明:

参数 类型 说明
errMsg String 成功:ok,错误:详细信息

wx.getBeacons

获取所有已搜索到的iBeacon设备

请求参数说明

参数 类型 必填 说明
success Function 接口调用成功的回调函数
fail Function 接口调用失败的回调函数
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)

success返回参数说明:

参数 类型 说明
beacons ObjectArray iBeacon 设备列表
errMsg String 成功:ok,错误:详细信息

iBeacon 结构:

参数 类型 说明
uuid String iBeacon 设备广播的 uuid
major String iBeacon 设备的主 id
minor String iBeacon 设备的次 id
proximity Number 表示设备距离的枚举值
accuracy Number iBeacon 设备的距离
rssi Number 表示设备的信号强度

wx.onBeaconUpdate

监听 iBeacon 设备的更新事件

CALLBACK 返回参数说明

参数 类型 说明
beacons ObjectArray 当前搜寻到的所有 iBeacon 设备列表

iBeacon 结构:

参数 类型 说明
uuid String iBeacon 设备广播的 uuid
major String iBeacon 设备的主 id
minor String iBeacon 设备的次 id
proximity Number 表示设备距离的枚举值
accuracy Number iBeacon 设备的距离
rssi Number 表示设备的信号强度

wx.onBeaconServiceChange

监听 iBeacon 服务的状态变化

CALLBACK 返回参数说明

参数 类型 说明
available Boolean 服务目前是否可用
discovering Boolean 目前是否处于搜索状态

错误码列表

错误码 说明 备注
0 ok 正常
11000 unsupport 系统或设备不支持
11001 bluetooth service unavailable 蓝牙服务不可用
11002 location service unavailable 位置服务不可用
11003 already start 已经开始搜索

硬件接口

发起无线投屏

wx.invoke('startWecast',{},
          function(res) {
             if(res.err_msg == "startWecast:ok"){
                //调用成功
             }else {
                //错误处理
            }
          });

该接口调用需要配合硬件设备使用,硬件接入流程参考 无线投屏,目前仅支持第三方服务商接入。

添加设备

wx.invoke("discoverDevice", {
        "type": "qrcode",        // 设备发现方式,支持 qrcode/bluetooth/input
        "qrcode_url": "https://open.work.weixin.qq.com/connect?xxx"
    },function(res){
        if (res.err_msg == "discoverDevice:ok")
        {
            // 设备绑定成功
        }
    }
);

此接口在企业微信2.5.8及以后版本支持,仅IOS/Andriod版本支持
调用者必须为企业超级管理员身份,才可以发起

请求参数说明:

参数 类型 必填 说明
type String 设备发现方式,支持三种类型:qrcode(二维码识别)/bluetooth(蓝牙发现)/input(sn码输入)
qrcode_url String 当type=qrcode时必填 设备静态/动态二维码链接
  • 指定 type=qrcode,此时会识别传递的 qrcode_url,如果是正确的链接,则直接进入到设备详情。
  • 指定 type=bluetooth,则进入蓝牙发现的列表页,进行搜索识别
  • 指定 type=input,则进到输入sn的流程

返回参数说明:

参数 类型 说明
err_msg String 当添加设备成功返回/取消添加返回时,err_msg为 discoverDevice:ok
参数失败情况,err_msg为 discoverDevice:fail

视频会议

查询当前是否在视频会议

wx.invoke('queryCurrHWOpenTalk', {
    }, function(res){
        if(res.err_msg == "queryCurrHWOpenTalk:ok"){
            if (res.inTalkType != "None") {
                // busy
                if (res.inTalkType == "HWOpenTalk") {
                    //res.ticket
                }
            }
        }else {
            //错误处理
        }
});

此接口在企业微信2.5.0及以后版本支持

返回参数说明:

参数 类型 说明
err_msg String 当查询成功时,err_msg为 queryCurrHWOpenTalk:ok
查询失败情况,err_msg为 queryCurrHWOpenTalk:fail
inTalkType String 当查询成功时,返回当前通话的类型,类型定义详见下面的inTalkType类型说明表
ticket String 如果当前通话类型为视频会议,会将当前会议码票据(enterHWOpenTalk中携带的ticket)回传

inTalkType类型说明:

inTalkType取值 说明
None 当前不在任何通话中
HWOpenTalk 视频会议中
VoIP voip通话中
SystemCall 系统通话中

加入视频会议

wx.invoke('enterHWOpenTalk', {
        'code': "",
        'ticket': "",
    }, function(res){
        if(res.err_msg == "enterHWOpenTalk:ok"){
        // 发起加入会议请求成功
        }else {
        // 发起加入会议请求失败
    }
 });

此接口在企业微信2.5.0及以后版本支持
只能加入同企业硬件创建的视频会议

参数说明:

参数 类型 必填 说明
code String 会议码,从对应的视频会议硬件上获取
ticket String 会议码票据,调用方可以根据会议码生成对应的会议码票据。此票据会在调用queryCurrHWOpenTalk时返回,便于换回对应的会议码(调用方需要记录票据->会议码的映射关系)

审批流程引擎接口

自建、第三方应用:发起审批、查看审批详情

注:企业微信客户端2.5.0及以上版本支持。

wx.invoke('thirdPartyOpenPage', {
    "oaType": "10001",// String
    "templateId": "46af67a118a6ebf000002",// String
    "thirdNo": "thirdNo",// String
    "extData": {
        'fieldList': [{
            'title': '采购类型',
            'type': 'text',
            'value': '市场活动',
        },
        {
            'title': '订单链接',
            'type': 'link',
            'value': 'https://work.weixin.qq.com',
        }]
    },// JSON
})

参数说明:

参数 必须 说明
oaType 操作类型,目前支持:10001-发起审批;10002-查看审批详情。
templateId 发起审批的模板ID,在自建应用-审批接口中创建模板可获取。
thirdNo 审批单号,由开发者自行定义,不可重复。
extData 详情数据,Json格式,用于审批详情页信息展示。

extData数据说明:
extData在发起时由开发者传入,其中数据将全部展示在审批申请中:
1.开发者可利用此特性,在发起审批时,传入需要申请人、审批人、抄送人看到的信息;
2.若需用户填写数据,可在自行使用表单收集,并传入exData中,用于展示。

{  
    "extData": {
        'fieldList': [
            {
                'title': '采购类型',
                'type': 'text',
                'value': '市场活动',
            },
            {
                'title': '采购说明',
                'type': 'text',
                'value': '购买个人办公电脑',
            },
            {
                'title': '采购金额',
                'type': 'text',
                'value': '4839.00元',
            },
            {
                'title': '申请时间',
                'type': 'text',
                'value': '2018/06/20',
            },
            {
                'title': '订单链接',
                'type': 'link',                // link类型,用于在审批详情页展示第三方订单跳转地址
                'value': 'https://www.qq.com',
            },
        ],

    },
}

参数说明:

参数 必须 说明
title 字段标题,将会在审批详情页中展示。
type 字段类型,目前支持:text-文本;link:链接。link仅展示在审批详情页。
value 字段值,将会在审批详情页中展示。

错误说明:

错误提示 说明
已存在相同的审批编号 oaType为10001时,传入的thirdNo已经被其他审批单占用。
审批申请不存在 oaType为10002时,在历史记录中,传入的thirdNo对应的审批单不存在。
审批模板ID不正确 调用接口时传入了错误的templateId
应用ID不正确 使用了错误的 agentId

附录1-JS-SDK使用权限签名算法

获取企业的jsapi_ticket

生成签名之前必须先了解一下jsapi_ticket,jsapi_ticket是H5应用调用企业微信JS接口的临时票据。正常情况下,jsapi_ticket的有效期为7200秒,通过access_token来获取。由于获取jsapi_ticket的api调用次数非常有限(一小时内,一个企业最多可获取400次,且单个应用不能超过100次),频繁刷新jsapi_ticket会导致api调用受限,影响自身业务,开发者必须在自己的服务全局缓存jsapi_ticket

请求方式:GET(HTTPS
请求URL:https://qyapi.weixin.qq.com/cgi-bin/get_jsapi_ticket?access_token=ACCESS_TOKEN

参数说明:

参数 必须 说明
access_token 调用接口凭证,获取方式参考“获取access_token

返回结果:

{
    "errcode":0,
    "errmsg":"ok",
    "ticket":"bxLdikRXVbTPdHSM05e5u5sUoXNKd8-41ZO3MhKoyN5OfkWITDGgnr2fwJ0m9E8NYzWKVZvdVtaUgWvsdshFKA",
    "expires_in":7200
}
参数 说明
ticket 生成签名所需的jsapi_ticket,最长为512字节
expires_in 凭证的有效时间(秒)

签名算法

签名生成规则如下:
参与签名的参数有四个: noncestr(随机字符串), jsapi_ticket, timestamp(时间戳), url(当前网页的URL, 不包含#及其后面部分

将这些参数使用URL键值对的格式 (即 key1=value1&key2=value2…)拼接成字符串string1。
有两个注意点:1. 字段值采用原始值,不要进行URL转义;2. 必须严格按照如下格式拼接,不可变动字段顺序。

jsapi_ticket=JSAPITICKET&noncestr=NONCESTR&timestamp=TIMESTAMP&url=URL

然后对string1作sha1加密即可。
示例 :

假如有如下参数:

noncestr=Wm3WZYTPz0wzccnW
jsapi_ticket=sM4AOVdWfPE4DxkXGEs8VMCPGGVi4C3VM0P37wVUCFvkVAy_90u5h9nbSlYy3-Sl-HhTdfl2fzFy1AOcHKP7qg
timestamp=1414587457
url=http://mp.weixin.qq.com?params=value

步骤1. 将这些参数拼接成字符串string1:

jsapi_ticket=sM4AOVdWfPE4DxkXGEs8VMCPGGVi4C3VM0P37wVUCFvkVAy_90u5h9nbSlYy3-Sl-HhTdfl2fzFy1AOcHKP7qg&noncestr=Wm3WZYTPz0wzccnW&timestamp=1414587457&url=http://mp.weixin.qq.com?params=value

步骤2. 对string1进行sha1签名,得到signature:

0f9de62fce790f9a083d5c99e95740ceb90c27ed

注意事项

  1. 签名用的noncestr和timestamp必须与wx.config中的nonceStr和timestamp相同。
  2. 签名用的url必须是调用JS接口页面的完整URL。
  3. 出于安全考虑,开发者必须在服务器端实现签名的逻辑。

如出现invalid signature 等错误详见附录4常见错误及解决办法。

获取应用的jsapi_ticket

应用的jsapi_ticket用于计算agentConfig(参见“通过agentConfig注入应用的权限”)的签名,签名计算方法与上述介绍的config的签名算法完全相同,但需要注意以下区别:

  1. 签名的jsapi_ticket必须使用以下接口获取。且必须用wx.agentConfig中的agentid对应的应用secret去获取access_token。
  2. 签名用的noncestr和timestamp必须与wx.agentConfig中的nonceStr和timestamp相同。

请求方式:GET(HTTPS
请求URL:https://qyapi.weixin.qq.com/cgi-bin/ticket/get?access_token=ACCESS_TOKEN&type=agent_config

参数说明:

参数 必须 说明
access_token 应用的调用凭证,获取方式参考“获取access_token

返回结果:

{
    "errcode":0,
    "errmsg":"ok",
    "ticket":"bxLdikRXVbTPdHSM05e5u5sUoXNKd8-41ZO3MhKoyN5OfkWITDGgnr2fwJ0m9E8NYzWKVZvdVtaUgWvsdshFKA",
    "expires_in":7200
}
参数 说明
ticket 生成签名所需的jsapi_ticket,最长为512字节
expires_in 凭证的有效时间(秒)

附录2-所有JS接口列表

  • onMenuShareAppMessage
  • onMenuShareWechat
  • onMenuShareTimeline
  • startRecord
  • stopRecord
  • onVoiceRecordEnd
  • playVoice
  • pauseVoice
  • stopVoice
  • onVoicePlayEnd
  • uploadVoice
  • downloadVoice
  • chooseImage
  • previewImage
  • uploadImage
  • downloadImage
  • getLocalImgData
  • previewFile
  • getNetworkType
  • onNetworkStatusChange
  • openLocation
  • getLocation
  • startAutoLBS
  • stopAutoLBS
  • onLocationChange
  • onHistoryBack
  • hideOptionMenu
  • showOptionMenu
  • hideMenuItems
  • showMenuItems
  • hideAllNonBaseMenuItem
  • showAllNonBaseMenuItem
  • closeWindow
  • openDefaultBrowser
  • scanQRCode
  • selectEnterpriseContact
  • openEnterpriseChat
  • chooseInvoice
  • selectExternalContact
  • getCurExternalContact
  • openUserProfile
  • shareAppMessage
  • shareWechatMessage
  • startWifi
  • stopWifi
  • connectWifi
  • getWifiList
  • onGetWifiList
  • onWifiConnected
  • getConnectedWifi
  • setClipboardData
  • getClipboardData

附录3-所有菜单项列表

基本类

  • 调整字体: “menuItem:setFont”
  • 刷新: “menuItem:refresh”

传播类

  • 转发: “menuItem:share:appMessage”
  • 微信: “menuItem:share:wechat”
  • 收藏: “menuItem:favorite”

保护类

  • 复制链接: “menuItem:copyUrl”
  • Safari: “menuItem:openWithSafari”
  • 邮件: “menuItem:share:email”

附录4-常见错误及解决方法

调用config接的时候传入参数debug: true 可以开启debug模式,页面会alert出错误信息。以下为常见错误及解决方法:

  1. invalid url domain:当前页面所在域名与使用的corpid没有绑定(可在该应用的可信域名中配置域名)。
  2. invalid signature签名错误:建议按如下顺序检查:
    1. 确认签名算法正确,可用http://work.weixin.qq.com/api/jsapisign页面工具进行校验。
    2. 确认config中nonceStr(js中驼峰标准大写S), timestamp与用以签名中的对应noncestr, timestamp一致。
    3. 确认url是页面完整的url(请在当前页面alert(location.href.split(‘#’)[0])确认),包括’http(s)://‘部分,以及’?’后面的GET参数部分,但不包括’#’hash后面的部分。
    4. 确认config中的appid与用来获取jsapi_ticket的corpid一致。
    5. 确保一定缓存access_token和jsapi_ticket。
    6. 确保你获取用来签名的url是动态获取的,动态页面可参见实例代码中php的实现方式。如果是html的静态页面在前端通过ajax将url传到后台签名,前端需要用js获取当前页面除去’#’hash部分的链接(可用location.href.split(‘#’)[0]获取,而且需要encodeURIComponent),因为页面一旦分享,企业微信客户端会在你的链接末尾加入其它参数,如果不是动态获取当前链接,将导致分享后的页面签名失败
  3. the permission value is offline verifying 或者 fail_nopermission:这个错误是因为config没有正确执行,或者是调用的JSAPI没有传入config的jsApiList参数中。建议按如下顺序检查:
    1. 确认config正确通过。
    2. 如果是在页面加载好时就调用了JSAPI,则必须写在wx.ready的回调中。
    3. 确认config的jsApiList参数包含了这个JSAPI。
  4. permission denied:该应用没有权限使用这个接口。
  5. function not exist:当前客户端版本不支持该接口,请升级到新版体验。
  6. 服务上线之后无法获取jsapi_ticket,自己测试时没问题:因为access_token和jsapi_ticket必须要在自己的服务器缓存,否则上线后会触发频率限制。请确保一定对token和ticket做缓存以减少服务器请求,不仅可以避免触发频率限制,还加快你们自己的服务速度。目前为了方便测试提供了1w的获取量,超过阀值后,服务将不再可用,请确保在服务上线前一定全局缓存access_token和jsapi_ticket,两者有效期均为7200秒(以返回结果中的expires_in为准),否则一旦上线触发频率限制,服务将不再可用
  7. uploadImage怎么传多图:目前只支持一次上传一张,多张图片需等前一张图片上传之后再调用该接口。
  8. 没法对本地选择的图片进行预览:chooseImage接口本身就支持预览,不需要额外支持。
  9. 通过a链接(例如先通过企业微信授权登录)跳转到b链接,invalid signature签名失败:后台生成签名的链接为使用jssdk的当前链接,也就是跳转后的b链接,请不要用企业微信登录的授权链接进行签名计算,后台签名的url一定是使用jssdk的当前页面的完整url除去’#’部分。
  10. 出现config:fail错误:这是由于传入的config参数不全导致,请确保传入正确的appId、timestamp、nonceStr、signature和需要使用的jsApiList。
  11. 如何把jsapi上传到企业微信的多媒体资源下载到自己的服务器:请参见文档中uploadVoice和uploadImage接口的备注说明。
  12. Android通过jssdk上传到企业微信服务器,第三方再从企业微信下载到自己的服务器,会出现杂音:企业微信团队已经修复此问题,目前后台已优化上线。
  13. 绑定父级域名,是否其子域名也是可用的:是的,合法的子域名在绑定父域名之后是完全支持的。
  14. 是否需要对低版本自己做兼容:jssdk都是兼容低版本的,不需要第三方自己额外做更多工作,但有的接口是新引入的,只有新版才可调用。
  15. getLocation返回的坐标在openLocation有偏差,因为getLocation返回的是gps坐标,openLocation打开的腾讯地图为火星坐标,getLocation也可以直接获取火星坐标。

附录5-JSAPI Demo页面

在[企业微信]里面访问地址 http://work.weixin.qq.com/api/jsapidemo 即可体验JSAPI的功能。
(可用企业微信扫一扫以下二维码)
联系我们

© 1998 - 2021 Tencent Inc. All Rights Reserved