微信JS-SDK是微信公众平台面向网页开发者提供的基于微信内的网页开发工具包。
通过使用微信JS-SDK,网页开发者可借助微信高效地使用拍照、选、语音、位置等手机系统的能力,同时可以直接使用微信分享、扫一扫等微信特有的能力,为微信用户提供更优质的网页体验。
使用说明
在使用微信JS-SDK对应的JS接口前,需确保已获得使用对应JS接口的权限,可在下表中根据自己的帐号角色查看。企业号帐号角色分为注册号和认证号,其中认证号拥有更多的JS-SDK权限,具体详见下方表格:
注意:所有的JS接口只能在企业号应用的可信域名下调用(包括子域名),可在企业号应用中心里设置应用可信域名。
步骤引入JS文件
在需要调用JS接口的页面引入如下JS文件,:http://res.wx.qq.com/open/js/jweixin-0.0.js
备注:支持使用AMD/CMD标准模块加载方法加载
步骤通过config接口注入权限验证配置
所有需要使用JS-SDK的页面必须先注入配置信息,否则将无法调用。
wx.config({
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对象)来调用,参数是一个对象,除了每个接口本身需要传的参数之外,还有以下通用参数:
注意:不要尝试在trigger中使用ajax异步请求修改本次分享的内容,因为客户端分享操作是一个同步操作,这时候使用ajax的回包会还没有返回。
以上几个函数都带有一个参数,类型为对象,其中除了每个接口本身返回的数据之外,还有一个通用属性errMsg,其值格式如下:
调用成功时:'xxx:ok',其中xxx为调用的接口名用户取消时:'xxx:cancel',其中xxx为调用的接口名调用失败时:其值为具体错误信息
基础接口
判断当前客户端版本是否支持指定JS接口
wx.checkJsApi({
jsApiList: ['chooseImage'] // 需要检测的JS接口列表,所有JS接口列表见附录2,
success: function(res) {
// 以键值对的形式返回,可用的api值true,不可用为false
// 如:{'checkResult':{'chooseImage':true},'errMsg':'checkJsApi:ok'}
});
备注:checkJsApi接口是客户端0.2新引入的一个预留接口,第一期开放的接口均可不使用checkJsApi来检测。
分享接口
请注意不要有诱导分享等违规行为,对于诱导分享行为将永久回收企业号接口权限,详细规则请查看:朋友圈管理常见问题。
wx.onMenuShareTimeline({
title: '', // 分享标题
link: '', // 分享链接
imgUrl: '', // 分享图标
success: function () {
// 用户确认分享后执行的回调函数
},
cancel: function () {
// 用户取消分享后执行的回调函数
}
});
wx.onMenuShareAppMessage({
title: '', // 分享标题
desc: '', // 分享描述
link: '', // 分享链接
imgUrl: '', // 分享图标
type: '', // 分享类型,music、video或link,不填默认为link
dataUrl: '', // 如果type是music或video,则要提供数据链接,默认为空
success: function () {
// 用户确认分享后执行的回调函数
},
cancel: function () {
// 用户取消分享后执行的回调函数
}
});
wx.onMenuShareQQ({
title: '', // 分享标题
desc: '', // 分享描述
link: '', // 分享链接
imgUrl: '', // 分享图标
success: function () {
// 用户确认分享后执行的回调函数
},
cancel: function () {
// 用户取消分享后执行的回调函数
}
});
wx.onMenuShareWeibo({
title: '', // 分享标题
desc: '', // 分享描述
link: '', // 分享链接
imgUrl: '', // 分享图标
success: function () {
// 用户确认分享后执行的回调函数
},
cancel: function () {
// 用户取消分享后执行的回调函数
}
});
wx.onMenuShareWeibo({
title: '', // 分享标题
desc: '', // 分享描述
link: '', // 分享链接
imgUrl: '', // 分享图标
success: function () {
// 用户确认分享后执行的回调函数
},
cancel: function () {
// 用户取消分享后执行的回调函数
}
});
像接口
拍照或从手机相册中选接口
wx.chooseImage({
count: 1, // 默认9
sizeType: ['original', 'compressed'], // 可以指定是原图还是压缩图,默认二者都有
sourceType: ['album', 'camera'], // 可以指定来源是相册还是相机,默认二者都有
success: function (res) {
var localIds = res.localIds; // 返回选定照片的本地ID列表,localId可以作为img标签的src属性显示图片
}
});
预览片接口
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,参考文档目前多媒体文件下载接口的频率限制为10000次/天,如需要调高频率,请邮件weixin-open@qq.com,邮件主题为【申请多媒体接口调用量】,请对你的项目进行简单描述,附上产品体验链接,并对用户量和使用量进行说明。
下载片接口
wx.downloadImage({
serverId: '', // 需要下载的图片的服务器端ID,由uploadImage接口获得
isShowProgressTips: 1// 默认为1,显示进度提示
success: function (res) {
var localId = res.localId; // 返回图片下载后的本地ID
}
});
音频接口
开始录音接口
停止录音接口
监听录音自动停止接口
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({
serverId: '', // 需要下载的音频的服务器端ID,由uploadVoice接口获得
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,参考文档目前多媒体文件下载接口的频率限制为10000次/天,如需要调高频率,请邮件weixin-open@qq.com,邮件主题为【申请多媒体接口调用量】,请对你的项目进行简单描述,附上产品体验链接,并对用户量和使用量进行说明。
下载语音接口
wx.downloadVoice({
serverId: '', // 需要下载的音频的服务器端ID,由uploadVoice接口获得
isShowProgressTips: 1// 默认为1,显示进度提示
success: function (res) {
var localId = res.localId; // 返回音频的本地ID
}
});
智能接口
识别音频并返回识别结果接口
wx.translateVoice({
localId: '', // 需要识别的音频的本地Id,由录音相关接口获得
isShowProgressTips: 1, // 默认为1,显示进度提示
success: function (res) {
alert(res.translateResult); // 语音识别的结果
}
});
设备信息
获取网络状态接口
wx.getNetworkType({
success: function (res) {
var networkType = res.networkType; // 返回网络类型2g,3g,4g,wifi
}
});
地理位置
使用微信内置地查看位置接口
获取地理位置接口
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; // 位置精度
}
});
界面操作
隐藏右上角菜单接口
显示右上角菜单接口
关闭当前网页窗口接口
批量隐藏功能按钮接口
wx.hideMenuItems({
menuList: [] // 要隐藏的菜单项,所有menu项见附录3
});
批量显示功能按钮接口
wx.showMenuItems({
menuList: [] // 要显示的菜单项,所有menu项见附录3
});
隐藏所有非基础按钮接口
显示所有功能按钮接口
微信扫一扫
调起微信扫一扫接口
wx.scanQRCode({
desc: 'scanQRCode desc',
needResult: 0, // 默认为0,扫描结果由微信处理,1则直接返回扫描结果,
scanType: ['qrCode','barCode'], // 可以指定扫二维码还是一维码,默认二者都有
success: function (res) {
var result = res.resultStr; // 当needResult 为 1 时,扫码返回的结果
}
});
企业号会话
创建企业号会话
接口描述
功能:通过JS-SDK创建企业号会话
请求参数
参数 | 必填 | 说明 |
---|---|---|
userIds | 是 | 参与会话的成员列表。格式为userid1;userid2;...,用分号隔开,最大限制为1000个。userid单个时为单聊,多个时为群聊。 |
groupName | 是 | 会话名称。单聊时该参数不需要传。 |
代码示例
wx.openEnterpriseChat({
userIds: ‘zhangshan;lisi;wangwu’,
groupName: ‘openEnterpriseChat讨论组’,
success: function(res){
// 回调
},
error: function(res){
if(res.errMsg.indexOf('function_not_exist') > 0){
alert('版本过低请升级')
}
}
});
备注:引入新版js文件http://res.wx.qq.com/open/js/jweixin-0.js。微信客户端5支持该接口,可通过function_not_exist错误信息提示用户升级微信。
返回码
附录1-JS-SDK使用权限签名算法
生成签名之前必须先了解一下jsapi_ticket,jsapi_ticket是企业号号用于调用微信JS接口的临时票据。正常情况下,jsapi_ticket的有效期为7200秒,通过access_token来获取。由于获取jsapi_ticket的api调用次数非常有限,频繁刷新jsapi_ticket会导致api调用受限,影响自身业务,开发者必须在自己的服务全局缓存jsapi_ticket。
参考以下文档获取access_token:http://qydev.weixiqq.com/wiki/index.php?title=%E4%B8%BB%E5%8A%A8%E8%B0%83%E7%94%A8用第一步拿到的access_token采用httpGET方式请求获得jsapi_ticket:https://qyapweixiqq.com/cgi-bin/get_jsapi_ticket?access_token=ACCESS_TOKE
成功返回如下JSON:
{
'errcode':0,
'errmsg':'ok',
'ticket':'bxLdikRXVbTPdHSM05e5u5sUoXNKd8-41ZO3MhKoyN5OfkWITDGgnr2fwJ0m9E8NYzWKVZvdVtaUgWvsdshFKA',
'expires_in':7200
}
获得jsapi_ticket之后,就可以生成JS-SDK权限验证的签名了。
签名算法
签名生成规则如下:参与签名的字段包括noncestr,有效的jsapi_ticket,timestamp,url。对所有待签名参数按照字段名的ASCII码从小到大排序后,使用URL键值对的格式拼接成字符串string这里需要注意的是所有参数名均为小写字符。对string1作sha1加密,字段名和字段值都采用原始值,不进行URL转义。
即signature=sha1(string。示例:
noncestr=Wm3WZYTPz0wzccnWjsapi_ticket=sM4AOVdWfPE4DxkXGEs8VMCPGGVi4C3VM0P37wVUCFvkVAy_90u5h9nbSlYy3-Sl-HhTdfl2fzFy1AOcHKP7qgtimestamp=1414587457url=http://mp.weixiqq.com
步骤对所有待签名参数按照字段名的ASCII码从小到大排序后,使用URL键值对的格式拼接成字符串string
jsapi_ticket=sM4AOVdWfPE4DxkXGEs8VMCPGGVi4C3VM0P37wVUCFvkVAy_90u5h9nbSlYy3-Sl-HhTdfl2fzFy1AOcHKP7qg&noncestr=Wm3WZYTPz0wzccnW×tamp=1414587457&url=http://mp.weixin.qq.com
附录2-所有JS接口列表
版本0.0接口
onMenuShareTimelineonMenuShareAppMessageonMenuShareQQonMenuShareWeiboonMenuShareQZonestartRecordstopRecordonVoiceRecordEndplayVoicepauseVoicestopVoiceonVoicePlayEnduploadVoicedownloadVoicechooseImagepreviewImageuploadImagedownloadImagetranslateVoicegetNetworkTypeopenLocationgetLocationhideOptionMenushowOptionMenuhideMenuItemsshowMenuItemshideAllNonBaseMenuItemshowAllNonBaseMenuItemcloseWindowscanQRCode
附录3-所有菜单项列表
基本类
举报:'menuItem:exposeArticle'调整字体:'menuItem:setFont'日间模式:'menuItem:dayMode'夜间模式:'menuItem:nightMode'刷新:'menuItem:refresh'查看企业号:'menuItem:profile'查看企业号:'menuItem:addContact'
传播类
发送给朋友:'menuItem:share:appMessage'分享到朋友圈:'menuItem:share:timeline'分享到QQ:'menuItem:share:qq'分享到QQ空间:'menuItem:share:QZone'分享到Weibo:'menuItem:share:weiboApp'收藏:'menuItem:favorite'分享到FB:'menuItem:share:facebook'分享到QQ空间:'menuItem:share:QZone'
保护类
调试:'menuItem:jsDebug'编辑标签:'menuItem:editTag'删除:'menuItem:delete'复制链接:'menuItem:copyUrl'原网页:'menuItem:originPage'阅读模式:'menuItem:readMode'在QQ浏览器中打开:'menuItem:openWithQQBrowser'在Safari中打开:'menuItem:openWithSafari'邮件:'menuItem:share:email'一些特殊企业号:'menuItem:share:brand'
附录4-常见错误及解决方法
调用config接口1的时候传入参数debug:true可以开启debug模式,页面会alert出错误信息。以下为常见错误及解决方法:
附录5-DEMO页面和示例代码
DEMO页面:
示例代码:
备注:链接中包含php、javnodejs以及python的示例代码供第三方参考,第三方切记要对获取的accesstoken以及jsapi_ticket进行缓存以确保不会触发频率限制。
附录6-问题反馈
文章为作者独立观点,不代表 股票程序化软件自动交易接口观点