微信JS-SDK是微信公眾平臺面向網頁開發者提供的基於微信內的網頁開發工具包。

通過使用微信JS-SDK，網頁開發者可藉助微信高效地使用拍照、選圖、語音、位置等手機系統的能力，同時可以直接使用微信分享、掃一掃、卡券、支付等微信特有的能力，為微信使用者提供更優質的網頁體驗。

此文件面向網頁開發者介紹微信JS-SDK如何使用及相關注意事項。

使用說明

在使用微信JS-SDK對應的JS介面前，需確保公眾號已獲得使用對應JS介面的許可權，可登入微信公眾平臺進入“開發者中心”檢視對應的介面許可權。

注意： 所有的JS介面只能在公眾號繫結的域名下呼叫，公眾號開發者需要先登入微信公眾平臺進入“公眾號設定”》“功能設定”裡填寫“JS介面安全域名”。

步驟一：引入JS檔案

備註：支援使用 AMD/CMD 標準模組載入方法載入

步驟二：通過config介面注入許可權驗證配置

所有需要使用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
});

步驟三：通過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中的相關介面。

以上幾個函式都帶有一個引數，型別為物件，其中除了每個介面本身返回的資料之外，還有一個通用屬性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"}
    });

備註：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
    }
});

下載圖片介面

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
    }
});

下載語音介面

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
});

附錄1-JS-SDK使用許可權簽名演算法

jsapi_ticket

生成簽名之前必須先了解一下jsapi_ticket，jsapi_ticket是公眾號用於呼叫微信JS介面的臨時票據。正常情況下，jsapi_ticket的有效期為7200秒，通過access_token來獲取。由於獲取jsapi_ticket的api呼叫次數非常有限，頻繁重新整理jsapi_ticket會導致api呼叫受限，影響自身業務，開發者必須在自己的服務全域性快取jsapi_ticket 。

成功返回如下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

步驟1. 對所有待簽名引數按照欄位名的ASCII 碼從小到大排序（字典序）後，使用URL鍵值對的格式（即key1=value1&key2=value2…）拼接成字串string1：

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

步驟2. 對string1進行sha1簽名，得到signature：

f4d90daf4b3bca3078ab155816175ba34c443a7b

注意事項

1. 簽名用的noncestr和timestamp必須與wx.config中的nonceStr和timestamp相同。
2. 簽名用的url必須是呼叫JS介面頁面的完整URL。
3. 出於安全考慮，開發者必須在伺服器端實現簽名的邏輯。

附錄2-所有JS介面列表

版本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

附錄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"
• 分享到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"

附錄4-位置簽名生成演算法

addrSign的生成規則與JS-SDK許可權驗證的簽名生成規則相同（參考附錄1），只是參與簽名引數有所不同。參與addrSign的簽名引數有：appId、url（當前網頁url）、timestamp、noncestr、accesstoken（使用者授權憑證，請參照oauth2.0 協議獲取）。

附錄5-支付擴充套件欄位及簽名生成演算法

訂單詳情（package）擴充套件字串定義

在商戶調起JS API 時，商戶需要此時確定該筆訂單詳情，並將該訂單詳情通過一定的方式進行組合放入package。JS API 呼叫後，微信將通過package 的內容生成預支付單。下 面將定義package 的所需欄位列表以及簽名方法。 介面需要注意：所有傳入引數都是字串型別！

package 所需欄位列表:

package 生成方法： 由於package中攜帶了生成訂單的詳細資訊，因此在微信將對package裡面的內容進行鑑 權，確定package攜帶的資訊是真實、有效、合理的。因此，這裡將定義生成package字元 串的方法。

1. 對所有傳入引數按照欄位名的ASCII碼從小到大排序（字典序）後，使用URL鍵值對的格式（即key1=value1&key2=value2…）拼接成字串string1，注意：值為空的引數不參與簽名；
2. 在string1最後拼接上key=paternerKey得到stringSignTemp字串，並對stringSignTemp進行md5運算，再將得到的字串所有字元轉換為大寫，得到sign值signValue。
3. 對傳入引數中所有鍵值對的value進行urlencode轉碼後重新拼接成字串string2。對於JS前端程式，一定要使用函式encodeURIComponent進行urlencode編碼（注意！進行urlencode時要將空格轉化為%20而不是+）。
4. 將sign=signValue拼接到string2後面得到最終的package字串。

下面定義了一段生成package字串的示範過程： 假設以下為package傳入引數：

• bank_type=WX
• body=支付測試
• fee_type=1
• input_charset=UTF-8
• 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&notify_url=http://we
ixin.qq.com&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&notify_url=htt
p://weixin.qq.com&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&notify_url=http%3A%2F%2Fweixin.qq.com&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&notify_url=http%3A%2F%2Fweixin.qq.com&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）。

附錄6-卡券擴充套件欄位及簽名生成演算法

卡券擴充套件欄位cardExt說明

cardExt本身是一個JSON字串，是商戶為該張卡券分配的唯一性資訊，包含以下欄位：

簽名說明

1. 將appsecret（第三方使用者唯一憑證密）、timestamp、card_id、code、openid、balance的value值進行字串的字典序排序。
2. 將所有引數字串拼接成一個字串進行sha1加密，得到signature。
3. signature中的timestamp和card_ext中的timestamp必須保持一致。
4. 假如資料示例中code=23456，timestamp=141231233，card_id=345667，appsecret=45678則signature=sha1(14123123323456345667456789)=4F76593A4245644FAE4E1BC940F6422A0C3EC03E。

卡券簽名cardSign說明

1. 將appsecret、app_id、location_id、times_tamp、nonce_str、card_id、card_type的value值進行字串的字典序排序。
2. 將所有引數字串拼接成一個字串進行sha1加密，得到cardSign。

附錄7-常見錯誤及解決方法

呼叫config 介面的時候傳入引數 debug: true 可以開啟debug模式，頁面會alert出錯誤資訊。以下為常見錯誤及解決方法：

1. invalid url domain當前頁面所在域名與使用的appid沒有繫結（一個appid可以繫結三個有效域名）。
2. invalid signature簽名錯誤。建議按如下順序檢查：
   1. 確認config中noncestr, timestamp與用以簽名中的對應noncestr, timestamp一致。
   2. 確認url是頁面完整的url，包括GET引數部分。
   3. 確認 config 中的 appid 與用來獲取 jsapi_ticket 的 appid 一致。
3. the permission value is offline verifying這個錯誤是因為config沒有正確執行，或者是呼叫的JSAPI沒有傳入config的jsApiList引數中。建議按如下順序檢查：
   1. 確認config正確通過。
   2. 如果是在頁面載入好時就呼叫了JSAPI，則必須寫在wx.ready的回撥中。
   3. 確認config的jsApiList引數包含了這個JSAPI。
4. permission denied該應用沒有許可權使用這個JSAPI。

附錄8-DEMO頁面和示例程式碼

DEMO頁面：

示例程式碼：

備註：連結中包含php、java、nodejs以及python的示例程式碼供第三方參考，第三方切記要對獲取的accesstoken以及jsapi_ticket進行快取以確保不會觸發頻率限制。