涵蓋能力:分享到朋友圈、分享給朋友、分享到 QQ、拍照或從手機相冊選圖、識別音訊並回傳結果、使用微信內建地圖查看位置等。
微信 JS-SDK 是微信公眾平台面向網頁開發者提供的、基於微信環境的網頁開發工具包。
有了它,網頁開發者可以藉助微信高效地調用拍照、選圖、語音、位置等手機系統能力,同時直接使用微信分享、掃一掃、卡券、支付等微信特有功能,為使用者提供更優質的網頁體驗。本文面向網頁開發者,說明 JS-SDK 的使用方式與注意事項。
在調用對應的 JS 介面前,需先確認公眾號已取得該介面的權限,可登入微信公眾平台進入「開發者中心」查看。
注意:所有 JS 介面只能在公眾號綁定的域名下調用。開發者需先登入微信公眾平台,進入「公眾號設置」→「功能設置」填寫「JS 介面安全域名」。
在需要調用 JS 介面的頁面引入(支援 https):
https://res.wx.qq.com/open/js/jweixin-1.0.0.js
備註:支援使用 AMD/CMD 標準模組載入方式。
所有使用 JS-SDK 的頁面都必須先注入設定資訊,否則無法調用(同一個 url 僅需調用一次;對於 url 會變化的 SPA,可在每次 url 變化時重新調用)。
wx.config({
debug: true, // 開啟除錯模式,所有 api 的返回值會在客戶端 alert 出來
appId: '', // 必填,公眾號的唯一標識
timestamp: , // 必填,產生簽名的時間戳
nonceStr: '', // 必填,產生簽名的隨機串
signature: '', // 必填,簽名(見附錄 1)
jsApiList: [] // 必填,需要使用的 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:使用者點擊取消時的回呼,僅部分具取消操作的介面會用到。trigger:監聽選單按鈕點擊時觸發,僅支援選單相關介面。以上回呼都帶一個物件參數,除各介面返回的資料外,還有一個通用屬性 errMsg,格式如下:
"xxx:ok"(xxx 為介面名)"xxx:cancel"wx.checkJsApi({
jsApiList: ['chooseImage'], // 需要檢測的介面清單
success: function(res) {
// 以鍵值對形式回傳,可用為 true,不可用為 false
// 如:{"checkResult":{"chooseImage":true},"errMsg":"checkJsApi:ok"}
}
});
備註:checkJsApi 是客戶端 6.0.2 新增的預留介面,首期開放的介面均可不使用它檢測。
請勿有誘導分享等違規行為,違規者將被永久回收介面權限。
分享到朋友圈:
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 清單,可作為 img 標籤的 src
}
});
// 預覽圖片
wx.previewImage({
current: '', // 目前顯示的圖片連結
urls: [] // 需要預覽的圖片連結清單
});
// 上傳圖片
wx.uploadImage({
localId: '', // 由 chooseImage 取得的本地 ID
isShowProgressTips: 1, // 預設為 1,顯示進度提示
success: function (res) {
var serverId = res.serverId; // 圖片的伺服器端 ID
}
});
// 下載圖片
wx.downloadImage({
serverId: '', // 由 uploadImage 取得的伺服器端 ID
isShowProgressTips: 1,
success: function (res) {
var localId = res.localId;
}
});
備註:上傳後取得的 serverId 即 media_id,可搭配微信多媒體檔案下載介面使用。
wx.startRecord(); // 開始錄音
wx.stopRecord({ // 停止錄音
success: function (res) { var localId = res.localId; }
});
wx.onVoiceRecordEnd({ // 錄音超過一分鐘未停止時執行
complete: function (res) { var localId = res.localId; }
});
wx.playVoice({ localId: '' }); // 播放語音
wx.pauseVoice({ localId: '' }); // 暫停播放
wx.stopVoice({ localId: '' }); // 停止播放
wx.onVoicePlayEnd({ // 監聽語音播放完畢
serverId: '', // 由 uploadVoice 取得的伺服器端 ID
success: function (res) { var localId = res.localId; }
});
wx.uploadVoice({ // 上傳語音
localId: '', isShowProgressTips: 1,
success: function (res) { var serverId = res.serverId; }
});
wx.downloadVoice({ // 下載語音
serverId: '', isShowProgressTips: 1,
success: function (res) { var localId = res.localId; }
});
wx.translateVoice({
localId: '', // 由錄音相關介面取得的本地 ID
isShowProgressTips: 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: '', // 位置簽名隨機串
addrSign: '', // 位置簽名(見附錄 4)
success: function (res) {
var longitude = res.longitude;
var latitude = res.latitude;
var speed = res.speed; // 速度,公尺/秒
var accuracy = res.accuracy; // 位置精度
}
});
wx.hideOptionMenu(); // 隱藏右上角選單
wx.showOptionMenu(); // 顯示右上角選單
wx.closeWindow(); // 關閉目前網頁視窗
wx.hideAllNonBaseMenuItem(); // 隱藏所有非基礎按鈕
wx.showAllNonBaseMenuItem(); // 顯示所有功能按鈕
wx.hideMenuItems({ menuList: [] }); // 批量隱藏功能按鈕
wx.showMenuItems({ menuList: [] }); // 批量顯示功能按鈕
wx.scanQRCode({
desc: 'scanQRCode desc',
needResult: 0, // 預設 0,結果交由微信處理;1 則直接回傳掃描結果
scanType: ["qrCode", "barCode"], // 可指定 QR Code 或一維條碼,預設兩者皆可
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——它是公眾號用於調用微信 JS 介面的臨時票據,正常情況下有效期為 7200 秒,需透過 access_token 取得。由於取得 jsapi_ticket 的 api 調用次數非常有限,頻繁刷新會導致 api 呼叫受限、影響自身業務,因此開發者必須在自己的服務端全域快取 jsapi_ticket。
https://api.weixin.qq.com/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)。
示例:
步驟 1:排序拼接後的 string1:
jsapi_ticket=sM4AOVdWfPE4DxkXGEs8VMCPGGVi4C3VM0P37wVUCFvkVAy_90u5h9nbSlYy3-Sl-HhTdfl2fzFy1AOcHKP7qg&noncestr=Wm3WZYTPz0wzccnW×tamp=1414587457&url=https://mp.weixin.qq.com
步驟 2:對 string1 做 sha1 簽名,得到 signature:
f4d90daf4b3bca3078ab155816175ba34c443a7b
注意事項:
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: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"。
addrSign 的產生規則與 JS-SDK 權限驗證的簽名規則相同(見附錄 1),差別只在參與簽名的參數不同。addrSign 的簽名參數為:appId、url(目前網頁 url)、timestamp、noncestr、accesstoken(使用者授權憑證,依 OAuth 2.0 協議取得)。
訂單詳情(package)擴展字串定義
商戶調起 JS API 時,需確定該筆訂單詳情並組合放入 package。JS API 調用後,微信會依 package 內容產生預支付單。注意:所有傳入參數都是字串型別。
package 所需欄位:
bank_type(必填)銀行通道類型,固定為 "WX"(注意大寫);body(必填)商品描述,128 位元組以下;attach(選填)附加資料,原樣回傳;partner(必填)商戶號 partnerId;out_trade_no(必填)商戶系統內訂單號,32 字元內且需唯一;total_fee(必填)訂單總金額,單位為分;fee_type(必填)支付幣種,預設 "1"(人民幣);notify_url(必填)支付完成後接收通知的絕對路徑,255 字元內;spbill_create_ip(必填)使用者瀏覽器端 IP(非商戶伺服器 IP),IPV4 格式;time_start(選填)交易起始時間,格式 yyyyMMddHHmmss,時區 GMT+8;time_expire(選填)交易結束時間,格式同上;transport_fee(選填)物流費用,單位為分;product_fee(選填)商品費用,單位為分;goods_tag(選填)商品標記,用優惠券時可能用到;input_charset(必填)傳入參數字元編碼,"GBK" 或 "UTF-8",預設 "GBK"。
若有填 transport_fee 與 product_fee,必須滿足 transport_fee + product_fee = total_fee。
package 產生方法:由於 package 攜帶了訂單詳情,微信會對其內容進行鑑權,確認資訊真實、有效、合理。步驟如下:
key1=value1&key2=value2&... 拼接成 string1。值為空的參數不參與簽名。key=partnerKey 得到 stringSignTemp,對其做 md5 運算,再將結果全部轉為大寫,得到 sign 值 signValue。encodeURIComponent(注意:urlencode 時空格要轉為 %20 而非 +)。sign=signValue 拼到 string2 後面,得到最終的 package 字串。示範過程:假設 package 傳入參數為 bank_type=WX、body=支付測試、fee_type=1、input_charset=UTF-8、notify_url=https://weixin.qq.com、out_trade_no=7240b65810859cbf2a8d9f76a638c0a3、partner=1900000109、spbill_create_ip=196.168.1.1、total_fee=1。
i:排序拼接後的 string1:
bank_type=WX&body=支付測試&fee_type=1&input_charset=UTF-8¬ify_url=https://weixin.qq.com&out_trade_no=7240b65810859cbf2a8d9f76a638c0a3&partner=1900000109&spbill_create_ip=196.168.1.1&total_fee=1
ii:拼接 key 並做 md5 後轉大寫,得到 sign:
sign = md5(string1 + "&key=8934e7d15453e97507ef794cf7b0519d").toUpperCase()
= "7f77b507b755b3262884291517e380f8".toUpperCase()
= "7F77B507B755B3262884291517E380F8"
iii:對每個 value 做 urlencode 編碼後得到:
bank_type=WX&body=%E6%94%AF%E4%BB%98%E6%B5%8B%E8%AF%95&fee_type=1&input_charset=UTF-8¬ify_url=http%3A%2F%2Fweixin.qq.com&out_trade_no=7240b65810859cbf2a8d9f76a638c0a3&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_type=1&input_charset=UTF-8¬ify_url=http%3A%2F%2Fweixin.qq.com&out_trade_no=7240b65810859cbf2a8d9f76a638c0a3&partner=1900000109&spbill_create_ip=196.168.1.1&total_fee=1&sign=7F77B507B755B3262884291517E380F8
支付簽名(paySign)產生方法
paySign 是對本次發起 JSAPI 行為的鑑權,只有通過 paySign 鑑權,才能繼續對 package 鑑權並產生預支付單。其產生規則與 JS-SDK 權限驗證的簽名規則相同(見附錄 1)。
參與 paySign 簽名的欄位包括:appid、timestamp、noncestr、package,以及 appkey(即 paySignkey)。
卡券擴展欄位 cardExt 說明
cardExt 本身是一個 JSON 字串,是商戶為該卡券分配的唯一性資訊,包含:
code(選填)指定的卡券 code 碼,只能被領取一次;use_custom_code 為 true 的卡券必填。openid(選填)指定領取者的 openid,只有該使用者能領取;bind_openid 為 true 的卡券必填。timestamp(必填)從 1970 年 1 月 1 日 00:00:00 至今的秒數,需轉為字串形式。signature(必填)依指定方式做 SHA1 簽名。balance(選填)紅包餘額,單位為分,紅包類型(LUCKY_MONEY)必填。
簽名說明:
卡券簽名 cardSign 說明:
呼叫 config 介面時傳入 debug: true 可開啟除錯模式,頁面會 alert 出錯誤資訊。常見錯誤如下:
1、invalid url domain
目前頁面所在域名與使用的 appid 沒有綁定(一個 appid 可綁定三個有效域名)。
2、invalid signature(簽名錯誤)建議依序檢查:
3、the permission value is offline verifying
此錯誤是因為 config 沒有正確執行,或調用的 JSAPI 未出現在 config 的 jsApiList 參數中。建議依序檢查:
wx.ready 的回呼中。4、permission denied
該應用沒有權限使用這個 JSAPI。
DEMO 頁面:https://demo.open.weixin.qq.com/jssdk
示例程式碼:https://demo.open.weixin.qq.com/jssdk/sample.zip
備註:連結中包含 php、java、nodejs 與 python 的示例程式碼供第三方參考。第三方切記要對取得的 access_token 與 jsapi_ticket 進行快取,以確保不會觸發頻率限制。