DIV CSS 佈局教程網

微信 JS-SDK 完整指南:權限配置、介面清單與簽名演算法
編輯:JavaScript基礎知識     

涵蓋能力:分享到朋友圈、分享給朋友、分享到 QQ、拍照或從手機相冊選圖、識別音訊並回傳結果、使用微信內建地圖查看位置等。

概述

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

有了它,網頁開發者可以藉助微信高效地調用拍照、選圖、語音、位置等手機系統能力,同時直接使用微信分享、掃一掃、卡券、支付等微信特有功能,為使用者提供更優質的網頁體驗。本文面向網頁開發者,說明 JS-SDK 的使用方式與注意事項。

使用說明

在調用對應的 JS 介面前,需先確認公眾號已取得該介面的權限,可登入微信公眾平台進入「開發者中心」查看。

注意:所有 JS 介面只能在公眾號綁定的域名下調用。開發者需先登入微信公眾平台,進入「公眾號設置」→「功能設置」填寫「JS 介面安全域名」。

步驟一:引入 JS 檔案

在需要調用 JS 介面的頁面引入(支援 https):

https://res.wx.qq.com/open/js/jweixin-1.0.0.js

備註:支援使用 AMD/CMD 標準模組載入方式。

步驟二:透過 config 介面注入權限驗證設定

所有使用 JS-SDK 的頁面都必須先注入設定資訊,否則無法調用(同一個 url 僅需調用一次;對於 url 會變化的 SPA,可在每次 url 變化時重新調用)。

wx.config({
  debug: true,   // 開啟除錯模式,所有 api 的返回值會在客戶端 alert 出來
  appId: '',     // 必填,公眾號的唯一標識
  timestamp: ,   // 必填,產生簽名的時間戳
  nonceStr: '',  // 必填,產生簽名的隨機串
  signature: '', // 必填,簽名(見附錄 1)
  jsApiList: []  // 必填,需要使用的 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:使用者點擊取消時的回呼,僅部分具取消操作的介面會用到。
  5. trigger:監聽選單按鈕點擊時觸發,僅支援選單相關介面。

以上回呼都帶一個物件參數,除各介面返回的資料外,還有一個通用屬性 errMsg,格式如下:

  1. 成功:"xxx:ok"(xxx 為介面名)
  2. 使用者取消:"xxx:cancel"
  3. 失敗:其值為具體錯誤資訊

基礎介面

判斷客戶端是否支援指定 JS 介面

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

附錄 1:JS-SDK 使用權限簽名演算法

jsapi_ticket

產生簽名前必須先理解 jsapi_ticket——它是公眾號用於調用微信 JS 介面的臨時票據,正常情況下有效期為 7200 秒,需透過 access_token 取得。由於取得 jsapi_ticket 的 api 調用次數非常有限,頻繁刷新會導致 api 呼叫受限、影響自身業務,因此開發者必須在自己的服務端全域快取 jsapi_ticket。

  1. 先取得 access_token(有效期 7200 秒,同樣必須全域快取)。
  2. 用該 access_token 以 HTTP GET 方式請求:
    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)。

示例:

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

步驟 1:排序拼接後的 string1:

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

步驟 2:對 string1 做 sha1 簽名,得到 signature:

f4d90daf4b3bca3078ab155816175ba34c443a7b

注意事項:

  1. 簽名用的 noncestr 與 timestamp,必須與 wx.config 中的 nonceStr、timestamp 相同。
  2. 簽名用的 url 必須是調用 JS 介面頁面的完整 URL。
  3. 基於安全考量,簽名邏輯必須在伺服器端實作。

附錄 2:所有 JS 介面清單(v1.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(使用者授權憑證,依 OAuth 2.0 協議取得)。

附錄 5:支付擴展欄位與簽名演算法

訂單詳情(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 攜帶了訂單詳情,微信會對其內容進行鑑權,確認資訊真實、有效、合理。步驟如下:

  1. 對所有傳入參數依欄位名 ASCII 碼由小到大排序(字典序),以 key1=value1&key2=value2&... 拼接成 string1。值為空的參數不參與簽名。
  2. 在 string1 末尾拼接 key=partnerKey 得到 stringSignTemp,對其做 md5 運算,再將結果全部轉為大寫,得到 sign 值 signValue。
  3. 對傳入參數中每一組鍵值對的 value 做 urlencode 編碼後重新拼接成 string2。對於 JS 前端程式,務必使用 encodeURIComponent(注意:urlencode 時空格要轉為 %20 而非 +)。
  4. 把 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&notify_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&notify_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&notify_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)。

附錄 6:卡券擴展欄位與簽名演算法

卡券擴展欄位 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)必填。

簽名說明:

  1. 將 appsecret、timestamp、card_id、code、openid、balance 的值進行字串字典序排序。
  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、timestamp、nonce_str、card_id、card_type 的值進行字典序排序。
  2. 把所有參數字串拼接後做 sha1 加密,得到 cardSign。

附錄 7:常見錯誤與解法

呼叫 config 介面時傳入 debug: true 可開啟除錯模式,頁面會 alert 出錯誤資訊。常見錯誤如下:

1、invalid url domain
目前頁面所在域名與使用的 appid 沒有綁定(一個 appid 可綁定三個有效域名)。

2、invalid signature(簽名錯誤)建議依序檢查:

  1. 確認簽名演算法正確,可用官方簽名校驗工具檢測。
  2. 確認 config 中的 noncestr、timestamp 與簽名時使用的對應值一致。
  3. 確認 url 是頁面完整的 url,包含 GET 參數部分。
  4. 確認 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 頁面:https://demo.open.weixin.qq.com/jssdk

示例程式碼:https://demo.open.weixin.qq.com/jssdk/sample.zip

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

XML學習教程| jQuery入門知識| AJAX入門| Dreamweaver教程| Fireworks入門知識| SEO技巧| SEO優化集錦|
Copyright © DIV+CSS佈局教程網 All Rights Reserved