微信JS接口说明

　　JS-SDK是公众平台面向网页开发者提供的基于内的网页开发工具包。

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

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

　　在使用JS-SDK对应的JS接口前，需确保公众号已获得使用对应JS接口的权限，可登录公众平台进入“开发者中心”查看对应的接口权限。

　　注意： 所有的JS接口只能在公众号绑定的域名下调用，公众号开发者需要先登录公众平台进入“公众号设置”》“功能设置”里填写“JS接口安全域名”。

　　在需要调用JS接口的页面引入如下JS文件，（支持s）：://res.wx./open/js/jweixin-1.0.0.js

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

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

　　wx.config({

　　debug: true, // 开启调试模式,调用的所有api的返回值会在客户端alert出来，若要查看传入的参数，可以在pc端打开，参数信息会通过log打出，仅在pc端时才会打印。

　　appId: '', // 必填，公众号的唯一标识

　　timestamp: , // 必填，生成签名的时间戳

　　nonceStr: '', // 必填，生成签名的随机串

　　signature: '',// 必填，签名，见附录1

　　jsApiList: [] // 必填，需要使用的JS接口列表，所有JS接口列表见附录2

　　});

　　wx.ready(function(){

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

　　});

　　wx.error(function(res){

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

　　});

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

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

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

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

　　wx.checkJsApi({

　　jsApiList: ['chooseImage'] // 需要检测的JS接口列表，所有JS接口列表见附录2,

　　success: function(res) {

　　// 以键值对的形式返回，可用的api值true，不可用为false

　　// 如：{"checkResult":{"chooseImage":true},"errMsg":"checkJsApi:ok"}

　　});

　　备注：checkJsApi接口是客户端6.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 () {

　　// 用户取消分享后执行的回调函数

　　}

　　});

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

　　wx.onMenuShareQQ({

　　title: '', // 分享标题

　　desc: '', // 分享描述

　　link: '', // 分享链接

　　imgUrl: '' // 分享图标

　　success: function () {

　　// 用户确认分享后执行的回调函数

　　},

　　cancel: function () {

　　// 用户取消分享后执行的回调函数

　　}

　　});

　　wx.onMenuShareWeibo({

　　title: '', // 分享标题

　　desc: '', // 分享描述

　　link: '', // 分享链接

　　imgUrl: '' // 分享图标

　　success: function () {

　　// 用户确认分享后执行的回调函数

　　},

　　cancel: function () {

　　// 用户取消分享后执行的回调函数

　　}

　　});

　　wx.chooseImage({

　　success: function (res) {

　　var localIds = res.localIds; // 返回选定照片的本地ID列表，localId可以作为img标签的src属性显示图片

　　}

　　});

　　wx.previewImage({

　　current: '', // 当前显示的图片链接

　　urls: [] // 需要预览的图片链接列表

　　});

　　wx.uploadImage({

　　localId: '', // 需要上传的图片的本地ID，由chooseImage接口获得

　　isShowProgressTips: 1// 默认为1，显示进度提示

　　success: function (res) {

　　var serverId = res.serverId; // 返回图片的服务器端ID

　　}

　　});

　　备注：可用下载多媒体文件接口下载上传的图片，此处获得的 serverId 即 media_id，参考文档 blog.csdn.net/cncco/article/12/58bfcfabbd501c7cd77c19bd9cfa8354.html

　　wx.downloadImage({

　　serverId: '', // 需要下载的图片的服务器端ID，由uploadImage接口获得

　　isShowProgressTips: 1// 默认为1，显示进度提示

　　success: function (res) {

　　var localId = res.localId; // 返回图片下载后的本地ID

　　}

　　});

　　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({

　　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

　　}

　　});

　　备注：可用下载多媒体文件接口下载上传的语音，此处获得的 serverId 即 media_id，参考文档 blog.csdn.net/cncco/article/12/58bfcfabbd501c7cd77c19bd9cfa8354.html

　　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.openLocation({

　　latitude: 0, // 纬度，浮点数，范围为90 ~ -90

　　longitude: 0, // 经度，浮点数，范围为180 ~ -180。

　　name: '', // 位置名

　　address: '', // 地址详情说明

　　scale: 1, // 地图缩放级别,整形值,范围从1~28。默认为最大

　　infoUrl: '' // 在查看位置界面底部显示的超链接,可点击跳转

　　});

　　wx.getLocation({

　　timestamp: 0, // 位置签名时间戳，仅当需要兼容6.0.2版本之前时提供

　　nonceStr: '', // 位置签名随机串，仅当需要兼容6.0.2版本之前时提供

　　addrSign: '', // 位置签名，仅当需要兼容6.0.2版本之前时提供，详见附录4

　　success: function (res) {

　　var longitude = res.longitude; // 纬度，浮点数，范围为90 ~ -90

　　var latitude = res.latitude; // 经度，浮点数，范围为180 ~ -180。

　　var speed = res.speed; // 速度，以米/每秒计

　　var accuracy = res.accuracy; // 位置精度

　　}

　　});

　　wx.hideOptionMenu();

　　wx.showOptionMenu();

　　wx.closeWindow();

　　wx.hideMenuItems({

　　menuList: [] // 要隐藏的菜单项，所有menu项见附录3

　　});

　　wx.showMenuItems({

　　menuList: [] // 要显示的菜单项，所有menu项见附录3

　　});

　　wx.hideAllNonBaseMenuItem();

　　wx.showAllNonBaseMenuItem();

　　wx.scanQRCode({

　　desc: 'scanQRCode desc',

　　needResult: 0, // 默认为0，扫描结果由处理，1则直接返回扫描结果，

　　scanType: ["qrCode","barCode"], // 可以指定扫二维码还是一维码，默认二者都有

　　success: function (res) {

　　var result = res.resultStr; // 当needResult 为 1 时，扫码返回的结果

　　}

　　});

　　wx.openProductSpecificView({

　　productId: '', // 商品id

　　viewType: '' // 0.默认值，普通商品详情页1.扫一扫商品详情页2.小店商品详情页

　　});

　　wx.chooseCard({

　　shopId: '', // 门店Id

　　cardType: '', // 卡券类型

　　cardId: '', // 卡券Id

　　timeStamp: 0, // 卡券签名时间戳

　　nonceStr: '', // 卡券签名随机串

　　cardSign: '', // 卡券签名，详见附录6

　　success: function (res) {

　　var cardList= res.cardList; // 用户选中的卡券列表信息

　　}

　　});

　　wx.addCard({

　　cardList: [{

　　cardId: '',

　　cardExt: ''

　　}], // 需要添加的卡券列表

　　success: function (res) {

　　var cardList = res.cardList; // 添加的卡券列表信息

　　}

　　});

　　wx.openCard({

　　cardList: [{

　　cardId: '',

　　code: ''

　　}]// 需要打开的卡券列表

　　});

　　wx.chooseWXPay({

　　timestamp: 0, // 支付签名时间戳

　　noncestr: '', // 支付签名随机串

　　package: '', // 订单详情扩展字符串，详见附录5

　　paySign: '', // 支付签名，详见附录5

　　});

　　jsapi_ticket

　　生成签名之前必须先了解一下jsapi_ticket，jsapi_ticket是公众号用于调用JS接口的临时票据。正常情况下，jsapi_ticket的有效期为7200秒，通过access_token来获取。由于获取jsapi_ticket的api调用次数非常有限，频繁刷新jsapi_ticket会导致api调用受限，影响自身业务，开发者必须在自己的服务全局缓存jsapi_ticket 。

　　参考以下文档获取access_token（有效期7200秒，开发者必须在自己的服务全局缓存access_token）：blog.csdn.net/cncco/article/15/54ce45d8d30b6bf6758f68d2e95bc627.html 用第一步拿到的access_token 采用 GET方式请求获得jsapi_ticket（有效期7200秒，开发者必须在自己的服务全局缓存jsapi_ticket）：api.weixin./cgi-bin/ticket/getticket?access_token=ACCESS_TOKEN&type=jsapi

　　成功返回如下JSON：

　　{

　　"errcode":0,

　　"errmsg":"ok",

　　"ticket":"bxLdikRXVbTPdHSM05e5u5sUoXNKd8-41ZO3MhKoyN5OfkWITDGgnr2fwJ0m9E8NYzWKVZvdVtaUgWvsdshFKA",

　　"expires_in":7200

　　}

　　获得jsapi_ticket之后，就可以生成JS-SDK权限验证的签名了。

　　签名算法

　　签名生成规则如下：参与签名的字段包括noncestr（随机字符串）, 有效的jsapi_ticket, timestamp（时间戳）, url（当前网页的URL，不包含#及其后面部分） 。对所有待签名参数按照字段名的ASCII 码从小到大排序（字典序）后，使用URL键值对的格式（即key1=value1&key2=value2…）拼接成字符串string1。这里需要注意的是所有参数名均为小写字符。对string1作sha1加密，字段名和字段值都采用原始值，不进行URL 转义。

　　即signature=sha1(string1)。示例：

　　noncestr=Wm3WZYTPz0wzccnW jsapi_ticket=sM4AOVdWfPE4DxkXGEs8VMCPGGVi4C3VM0P37wVUCFvkVAy_90u5h9nbSlYy3-Sl-HhTdfl2fzFy1AOcHKP7qg timestamp=1414587457 url=://mp.weixin.

　　步骤1. 对所有待签名参数按照字段名的ASCII 码从小到大排序（字典序）后，使用URL键值对的格式（即key1=value1&key2=value2…）拼接成字符串string1：

　　jsapi_ticket=sM4AOVdWfPE4DxkXGEs8VMCPGGVi4C3VM0P37wVUCFvkVAy_90u5h9nbSlYy3-Sl-HhTdfl2fzFy1AOcHKP7qg&noncestr=Wm3WZYTPz0wzccnW×tamp=1414587457&url=://mp.weixin.

　　步骤2. 对string1进行sha1签名，得到signature：

　　f4d90daf4b3bca3078ab155816175ba34c443a7b

　　注意事项

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

　　版本1.0.0接口

　　onMenuShareTimeline onMenuShareAppMessage onMenuShareQQ onMenuShareWeibo startRecord stopRecord onVoiceRecordEnd playVoice pauseVoice stopVoice onVoicePlayEnd uploadVoice downloadVoice chooseImage previewImage uploadImage downloadImage translateVoice getNetworkType openLocation getLocation hideOptionMenu showOptionMenu hideMenuItems showMenuItems hideAllNonBaseMenuItem showAllNonBaseMenuItem closeWindow scanQRCode chooseWXPay openProductSpecificView addCard chooseCard openCard

　　基本类

　　举报: "menuItem:exposeArticle" 调整字体: "menuItem:setFont" 日间模式: "menuItem:dayMode" 夜间模式: "menuItem:nightMode" 刷新: "menuItem:refresh" 查看公众号（已添加）: "menuItem:profile" 查看公众号（未添加）: "menuItem:addContact"

　　传播类

　　发送给朋友: "menuItem:share:appMessage" 分享到朋友圈: "menuItem:share:timeline" 分享到QQ: "menuItem:share:" 分享到Weibo: "menuItem:share:weiboApp" 收藏: "menuItem:favorite" 分享到FB: "menuItem:share:facebook"

　　保护类

　　调试: "menuItem:jsDebug" 编辑标签: "menuItem:editTag" 删除: "menuItem:delete" 复制链接: "menuItem:copyUrl" 原网页: "menuItem:originPage" 阅读模式: "menuItem:readMode" 在QQ浏览器中打开: "menuItem:openWithQQBrowser" 在Safari中打开: "menuItem:openWithSafari" 邮件: "menuItem:share:email" 一些特殊公众号: "menuItem:share:brand"

　　addrSign的生成规则与JS-SDK权限验证的签名生成规则相同（参考附录1），只是参与签名参数有所不同。参与addrSign的签名参数有：appId、url（当前网页url）、timestamp、noncestr、accesstoken（用户授权凭证，请参照oauth2.0 协议获取）。

　　订单详情（package）扩展字符串定义

　　在商户调起JS API 时，商户需要此时确定该笔订单详情，并将该订单详情通过一定的方式进行组合放入package。JS API 调用后，将通过package 的内容生成预支付单。下面将定义package 的所需字段列表以及签名方法。接口需要注意：所有传入参数都是字符串类型！

　　package 所需字段列表:

　　package 生成方法：由于package中携带了生成订单的详细信息，因此在将对package里面的内容进行鉴权，确定package携带的信息是真实、有效、合理的。因此，这里将定义生成package字符串的方法。

　　对所有传入参数按照字段名的ASCII码从小到大排序（字典序）后，使用URL键值对的格式（即key1=value1&key2=value2…）拼接成字符串string1，注意：值为空的参数不参与签名； 在string1最后拼接上key=paternerKey得到stringSignTemp字符串，并对stringSignTemp进行md5运算，再将得到的字符串所有字符转换为大写，得到sign值signValue。 对传入参数中所有键值对的value进行urlencode转码后重新拼接成字符串string2。对于JS前端程序，一定要使用函数encodeURIComponent进行urlencode编码（注意！进行urlencode时要将空格转化为%20而不是+）。 将sign=signValue拼接到string2后面得到最终的package字符串。

　　下面定义了一段生成package字符串的示范过程：假设以下为package传入参数：

　　bank_type=WX body=支付测试 fee_type=1 input_charset=UTF-8 notify_url=://weixin. out_trade_no=7240b65810859cbf2a8d9f76a638c0a3 partner=1900000109 spbill_create_ip=196.168.1.1 total_fee=1

　　i: 经过a过程URL键值对字典序排序后的字符串string1为：

　　bank_type=WX&body=支付测试&fee_type=1&input_charset=UTF-8¬ify_url=://we

　　ixin.&out_trade_no=7240b65810859cbf2a8d9f76a638c0a3&partner=1900000109&spbill_

　　create_ip=196.168.1.1&total_fee=1

　　ii：经过b过程后得到sign为：

　　sign

　　=md5(string1&key=8934e7d15453e97507ef794cf7b0519d).toUpperCase

　　=md5(bank_type=WX&body=支付测试&fee_type=1&input_charset=UTF-8¬ify_url=htt

　　p://weixin.&out_trade_no=7240b65810859cbf2a8d9f76a638c0a3&partner=1900000109&

　　spbill_create_ip=196.168.1.1&total_fee=1&key=8934e7d15453e97507ef794cf7b0519d).toUpper

　　Case()

　　="7f77b507b755b3262884291517e380f8".toUpperCase()

　　="7F77B507B755B3262884291517E380F8"

　　iii：再对传入参数中的每一个键值对中的value进行urlencode编码后得到：

　　bank_type=WX&body=%E6%94%AF%E4%BB%98%E6%B5%8B%E8%AF%95&fee_typ

　　e=1&input_charset=UTF-8¬ify_url=%3A%2F%2Fweixin.&out_trade_no=7240b6

　　5810859cbf2a8d9f76a638c0a3&partner=1900000109&spbill_create_ip=196.168.1.1&total_fee=1

　　iv：拼接上sign后得到最终package结果：

　　bank_type=WX&body=%E6%94%AF%E4%BB%98%E6%B5%8B%E8%AF%95&fee_typ

　　e=1&input_charset=UTF-8¬ify_url=%3A%2F%2Fweixin.&out_trade_no=7240b6

　　5810859cbf2a8d9f76a638c0a3&partner=1900000109&spbill_create_ip=196.168.1.1&total_fee=1

　　&sign=7F77B507B755B3262884291517E380F8

　　支付签名（paySign）生成方法

　　paySign字段是对本次发起JSAPI的行为进行鉴权，只有通过了paySign鉴权，才能继续对package鉴权并生成预支付单。paySign的生成规则与JS-SDK权限验证的签名生成规则相同（参考附录1）。

　　参与paySign签名的字段包括：appid、timestamp、noncestr、package以及appkey（即 paySignkey）。

　　卡券扩展字段cardExt说明

　　cardExt本身是一个JSON字符串，是商户为该张卡券分配的唯一性信息，包含以下字段：

　　签名说明

　　将appsecret（第三方用户唯一凭证密）、timestamp、card_id、code、openid、balance的value值进行字符串的字典序排序。 将所有参数字符串拼接成一个字符串进行sha1加密，得到signature。 signature中的timestamp和card_ext中的timestamp必须保持一致。 假如数据示例中code=23456，timestamp=141231233，card_id=345667，appsecret=45678则signature=sha1(14123123323456345667456789)=4F76593A4245644FAE4E1BC940F6422A0C3EC03E。

　　卡券签名cardSign说明

　　将appsecret、app_id、location_id、times_tamp、nonce_str、card_id、card_type的value值进行字符串的字典序排序。 将所有参数字符串拼接成一个字符串进行sha1加密，得到cardSign。

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

　　invalid url domain当前页面所在域名与使用的appid没有绑定（一个appid可以绑定三个有效域名）。 invalid signature签名错误。建议按如下顺序检查：

　　确认签名算法正确，可用 ://mp.weixin./debug/cgi-bin/sandbox?t=jsapisign 页面工具进行校验。 确认config中noncestr, timestamp与用以签名中的对应noncestr, timestamp一致。 确认url是页面完整的url，包括GET参数部分。 确认 config 中的 appid 与用来获取 jsapi_ticket 的 appid 一致。 the permission value is offline verifying这个错误是因为config没有正确执行，或者是调用的JSAPI没有传入config的jsApiList参数中。建议按如下顺序检查：

　　确认config正确通过。 如果是在页面加载好时就调用了JSAPI，则必须写在wx.ready的回调中。 确认config的jsApiList参数包含了这个JSAPI。 permission denied该应用没有权限使用这个JSAPI。

　　DEMO页面：

　　://demo.open.weixin./jssdk

　　示例代码：

　　://demo.open.weixin./jssdk/sample.zip

　　备注：链接中包含php、java、nodejs以及python的示例代码供第三方参考，第三方切记要对获取的accesstoken以及jsapi_ticket进行缓存以确保不会触发频率限制。