微信JS-SDK說明文檔
目錄
概述
微信JS-SDK是微信公眾平台面向網頁開發者提供的基於微信內的網頁開發工具包。
通過使用微信JS-SDK，網頁開發者可借助微信高效地使用拍照、選圖、語音、位置等手機系統的能力，同時可以直接使用微信分享、掃一掃等微信特有的能力，為微信用戶提供更優質的網頁體驗。
此文檔面向網頁開發者介紹微信JS-SDK如何使用及相關注意事項。
使用說明
在使用微信JS-SDK對應的JS接口前，需確保已獲得使用對應JS接口的權限，可在下表中根據自己的帳號類型查看。 企業號帳號類型分為注冊號和認證號，其中認證號擁有更多的JS-SDK權限，具體詳見下方表格：
| 功能 | 接口 | 認證號 | 注冊號 |
|---|---|---|---|
| 基礎接口 | 判斷當前客戶端版本是否支持指定JS接口 | 有 | 有 |
| 企業號 | 創建企業會話 | 有 | 有 |
| 打開企業通訊錄選人 | 有 | 有 | |
| 分享接口 | 獲取“分享到朋友圈”按鈕點擊狀態及設置分享內容接口 | 有 | 無 |
| 獲取“分享給朋友”按鈕點擊狀態及設置分享內容接口 | 有 | 無 | |
| 獲取“分享到QQ”按鈕點擊狀態及設置分享內容接口 | 有 | 無 | |
| 獲取“分享到騰訊微博”按鈕點擊狀態及設置分享內容接 | 有 | 無 | |
| 圖像接口 | 本地選圖或拍照接口 | 有 | 有 |
| 圖片預覽接口 | 有 | 有 | |
| 上傳圖片接口 | 有 | 有 | |
| 下載圖片接口 | 有 | 有 | |
| 音頻接口 | 開始錄音接口 | 有 | 有 |
| 停止錄音接口 | 有 | 有 | |
| 播放音頻接口 | 有 | 有 | |
| 暫停播放接口 | 有 | 有 | |
| 停止播放接口 | 有 | 有 | |
| 上傳語音接口 | 有 | 有 | |
| 下載語音接口 | 有 | 有 | |
| 智能接口 | 識別音頻並返回識別結果接口 | 有 | 有 |
| 設備信息 | 獲取網絡狀態接口 | 有 | 有 |
| 地理位置 | 查看地理位置地圖接口 | 有 | 有 |
| 獲取地理位置接口 | 有 | 有 | |
| 界面操作 | 隱藏右上角菜單接口 | 有 | 有 |
| 顯示右上角菜單接口 | 有 | 有 | |
| 關閉當前窗口接口 | 有 | 有 | |
| 批量隱藏菜單項接口 | 有 | 有 | |
| 批量顯示菜單項接口 | 有 | 有 | |
| 隱藏所有非基本菜單項接口 | 有 | 有 | |
| 顯示所有被隱藏的非基本菜單項接口 | 有 | 有 | |
| 微信掃一掃 | 掃一掃接口 | 有 | 有 |
注意： 所有的JS接口只能在企業號應用的可信域名下調用(包括子域名)，可在企業號應用中心里設置應用可信域名。
步驟一：引入JS文件
在需要調用JS接口的頁面引入如下JS文件，（支持https）：http://res.wx.qq.com/open/js/jweixin-1.2.0.js
備注：支持使用 AMD/CMD 標准模塊加載方法加載
步驟二：通過config接口注入權限驗證配置
所有需要使用JS-SDK的頁面必須先注入配置信息，否則將無法調用（同一個url僅需調用一次，對於變化url的SPA的web app可在每次url變化時進行調用,目前Android微信客戶端不支持pushState的H5新特性，所以使用pushState來實現web app的頁面會導致簽名失敗，此問題會在Android6.2中修復）。
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對象)來調用，參數是一個對象，除了每個接口本身需要傳的參數之外，還有以下通用參數：
- success：接口調用成功時執行的回調函數。
- fail：接口調用失敗時執行的回調函數。
- complete：接口調用完成時執行的回調函數，無論成功或失敗都會執行。
- cancel：用戶點擊取消時的回調函數，僅部分有用戶取消操作的api才會用到。
- trigger: 監聽Menu中的按鈕點擊時觸發的方法，該方法僅支持Menu中的相關接口。
注意：不要嘗試在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接口是客戶端6.0.2新引入的一個預留接口，第一期開放的接口均可不使用checkJsApi來檢測。
企業號
企業號接口為企業號應用專有的JS-SDK接口
創建企業會話
wx.openEnterpriseChat({
userIds: 'zhangshan;lisi;wangwu', // 必填，參與會話的成員列表。格式為userid1;userid2;...，用分號隔開，最大限制為2000個。userid單個時為單聊，多個時為群聊。
groupName: 'openEnterpriseChat討論組', // 必填，會話名稱。單聊時該參數傳入空字符串""即可。
success: function(res) {
// 回調
},
fail: function(res) {
if(res.errMsg.indexOf('function not exist') > -1){
alert('版本過低請升級')
}
}
});
打開企業通訊錄選人
注意：該JS-SDK需要驗證企業號管理組權限，請參考：附錄2-企業號管理組權限驗證方法
var evalWXjsApi = function(jsApiFun) {
if (typeof WeixinJSBridge == "object" && typeof WeixinJSBridge.invoke == "function") {
jsApiFun();
} else {
document.attachEvent && document.attachEvent("WeixinJSBridgeReady", jsApiFun);
document.addEventListener && document.addEventListener("WeixinJSBridgeReady", jsApiFun);
}
}
document.querySelector('#openEnterpriseContact_invoke').onclick = function() {
evalWXjsApi(function() {
WeixinJSBridge.invoke("openEnterpriseContact", {
"groupId": "g50a5axxxx91706a", // 必填，管理組權限驗證步驟1返回的group_id
"timestamp": "1447334894", // 必填，管理組權限驗證步驟2使用的時間戳
"nonceStr": "Wm3WZYTPz0wzccnW", // 必填，管理組權限驗證步驟2使用的隨機字符串
"signature": "f9afc6f80a0c81xxxxxxxxxxxxedff5001878", // 必填，管理組權限驗證步驟2生成的簽名
"params" : {
'departmentIds' : [1], // 非必填，可選部門ID列表（如果ID為0，表示可選管理組權限下所有部門）
'tagIds' : [1], // 非必填，可選標簽ID列表（如果ID為0，表示可選所有標簽）
'userIds' : ['zhangsan','lisi'], // 非必填，可選用戶ID列表
'mode' : 'single', // 必填，選擇模式，single表示單選，multi表示多選
'type' : ['department','tag','user'], // 必填，選擇限制類型，指定department、tag、user中的一個或者多個
'selectedDepartmentIds' : [], // 非必填，已選部門ID列表
'selectedTagIds' : [], // 非必填，已選標簽ID列表
'selectedUserIds' : [], // 非必填，已選用戶ID列表
},
}, function(res) {
if (res.err_msg.indexOf('function_not_exist') > -1) {
alert('版本過低請升級');
} else if (res.err_msg.indexOf('openEnterpriseContact:fail') > -1) {
return;
}
var result = JSON.parse(res.result); // 返回字符串，開發者需自行調用JSON.parse解析
var selectAll = result.selectAll; // 是否全選（如果是，其余結果不再填充）
if (!selectAll)
{
var selectedDepartmentList = result.departmentList; // 已選的部門列表
for (var i = 0; i < selectedDepartmentList.length; i++) {
var department = selectedDepartmentList[i];
var departmentId = department.id; // 已選的單個部門ID
var departemntName = department.name; // 已選的單個部門名稱
}
var selectedTagList = result.tagList; // 已選的標簽列表
for (var i = 0; i < selectedTagList.length; i++) {
var tag = selectedTagList[i];
var tagId = tag.id; // 已選的單個標簽ID
var tagName = tag.name; // 已選的單個標簽名稱
}
var selectedUserList = result.userList; // 已選的成員列表
for (var i = 0; i < selectedUserList.length; i++) {
var user = selectedUserList[i];
var userId = user.id; // 已選的單個成員ID
var userName = user.name; // 已選的單個成員名稱
}
}
})
});
}
向當前企業會話發送消息
注意：該JS-SDK僅適用於從應用的“關聯到會話”入口進入的網頁
var evalWXjsApi = function(jsApiFun) {
if (typeof WeixinJSBridge == "object" && typeof WeixinJSBridge.invoke == "function") {
jsApiFun();
} else {
document.attachEvent && document.attachEvent("WeixinJSBridgeReady", jsApiFun);
document.addEventListener && document.addEventListener("WeixinJSBridgeReady", jsApiFun);
}
}
// 發送文本消息
document.querySelector('#sendEnterpriseChat_text_invoke').onclick = function() {
evalWXjsApi(function() {
WeixinJSBridge.invoke("sendEnterpriseChat", {
"type": "text", // 必填，text表示發送的內容是文字
"data": {
"content": "text sent to enterprise chat", // 必填，表示發送的文字內容
}
}, function(res) {
alert(JSON.stringify(res));
})
});
}
// 發送鏈接消息
document.querySelector('#sendEnterpriseChat_link_invoke').onclick = function() {
evalWXjsApi(function() {
WeixinJSBridge.invoke("sendEnterpriseChat", {
"type": "link", // 必填，link表示發送的內容是鏈接
"data": {
"imgUrl": "http://shp.qpic.cn/bizmp/PiajxSqBRaEJ60dDSjCqczZFTTHsyX5MvxibUq1L3jwokHORAYOV0OdQ/", // 必填，表示消息的圖標
"title": "test title", // 非必填，但與desc不能同時為空
"desc": "test desc", // 非必填，但與title不能同時為空
"link": "http://qy.weixin.qq.com", // 必填，表示消息的鏈接
}
}, function(res) {
alert(JSON.stringify(res));
})
});
}
分享接口
請注意不要有誘導分享等違規行為，對於誘導分享行為將永久回收企業號接口權限，詳細規則請查看：朋友圈管理常見問題 。
獲取“分享到朋友圈”按鈕點擊狀態及自定義分享內容接口
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 () {
// 用戶取消分享后執行的回調函數
}
});
獲取“分享到QQ空間”按鈕點擊狀態及自定義分享內容接口
wx.onMenuShareQZone({
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，參考文檔
下載圖片接口
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({
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，參考文檔
下載語音接口
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({
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.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) {
// 回調
}
error: function(res){
if(res.errMsg.indexOf('function_not_exist') > 0){
alert('版本過低請升級')
}
}
});
微信卡券
微信卡券接口中使用的簽名憑證api_ticket，與步驟二中config使用的簽名憑證jsapi_ticket不同，開發者在調用微信卡券JS-SDK的過程中需依次完成兩次不同的簽名，並確保憑證的緩存。
獲取api_ticket
api_ticket 是用於調用微信卡券JS API的臨時票據，有效期為7200 秒，通過access_token 來獲取。
開發者注意事項：
1.此用於卡券接口簽名的api_ticket與步驟三中通過config接口注入權限驗證配置使用的jsapi_ticket不同。
2.由於獲取api_ticket 的api 調用次數非常有限，頻繁刷新api_ticket 會導致api調用受限，影響自身業務，開發者需在自己的服務存儲與更新api_ticket。
- 請求說明
Https請求方式：GET
https://qyapi.weixin.qq.com/cgi-bin/ticket/get?access_token=ACCESS_TOKEN&type=wx_card
- 參數說明
| 參數 | 必須 | 說明 |
|---|---|---|
| access_token | 是 | 調用接口憑證 |
| type | 是 | 此處固定為wx_card |
- 返回說明
{
"errcode":0,
"errmsg":"ok",
"ticket":"bxLdikRXVbTPdHSM05e5u5sUoXNKdvsdshFKA",
"expires_in":7200
}
- 參數說明
| 參數 | 說明 |
|---|---|
| errcode | 錯誤碼 |
| errmsg | 錯誤信息 |
| ticket | api_ticket，卡券接口中簽名所需憑證 |
| expires_in | 有效時間 |
拉取適用卡券列表並獲取用戶選擇信息
wx.chooseCard({
shopId: '', // 門店Id
cardType: '', // 卡券類型
cardId: '', // 卡券Id
timestamp: 0, // 卡券簽名時間戳
nonceStr: '', // 卡券簽名隨機串
signType: '', // 簽名方式，默認'SHA1'
cardSign: '', // 卡券簽名
success: function (res) {
var cardList= res.cardList; // 用戶選中的卡券列表信息
}
});
- 參數說明
| 參數 | 必須 | 說明 |
|---|---|---|
| shopId | 否 | 門店ID。shopID用於篩選出拉起帶有指定location_list(shopID)的卡券列表，非必填,企業號暫不支持。 |
| cardType | 否 | 卡券類型，用於拉起指定卡券類型的卡券列表。當cardType為空時，默認拉起所有卡券的列表，非必填。 |
| cardId | 否 | 卡券ID，用於拉起指定cardId的卡券列表，當cardId為空時，默認拉起所有卡券的列表，非必填。 |
| timestamp | 是 | 時間戳。 |
| nonceStr | 是 | 隨機字符串。 |
| signType | 是 | 簽名方式，目前僅支持SHA1 |
| cardSign | 是 | 簽名。 |
cardSign詳見附錄5。開發者特別注意：簽名錯誤會導致拉取卡券列表異常為空，請仔細檢查參與簽名的參數有效性。
特別提醒 拉取列表僅與用戶本地卡券有關，拉起列表異常為空的情況通常有三種：簽名錯誤、時間戳無效、篩選機制有誤。請開發者依次排查定位原因。
批量添加卡券接口
wx.addCard({
cardList: [{
cardId: '',
cardExt: ''
}], // 需要添加的卡券列表
success: function (res) {
var cardList = res.cardList; // 添加的卡券列表信息
}
});
cardExt詳見附錄5，值得注意的是，這里的card_ext參數必須與參與簽名的參數一致，格式為字符串而不是Object，否則會報簽名錯誤。
查看微信卡包中的卡券接口
wx.openCard({
cardList: [{
cardId: '',
code: : ''
}], // // 需要打開的卡券列表
});
SOTER生物認證認證接口
獲取本機支持的SOTER生物認證方式
使用場景：開發者調用該接口獲取本機支持的SOTER生物認證方式，以便確定所開發功能是否可用，以及確定使用何種方式進行SOTER生物識別(兼容版本：ios/android 6.3.16及以上版本)
wx.config({
beta:true,
});
wx.ready(function () {
wx.invoke("getSupportSoter", {},function(res){
var ret = " support_mode: " + res.support_mode;
alert(ret);
});
});
- 返回參數說明
| 參數 | 說明 |
|---|---|
| support_mode | 該設備支持的可被SOTER識別的生物識別方式，十六進制無浮點整數。生物識別方式定義如表1（持續更新中） |
| err_msg | 本地生物識別結果的錯誤信息 |
表1：生物識別方式定義
| 生物識別方式 | 十六進制定義 |
|---|---|
| 指紋識別 | 0x1 |
例如：該設備不支持SOTER或者不具備任何被SOTER支持的生物識別方式，則返回0x0；該設備支持SOTER方案指紋識別接口，則返回0x1；該設備同時支持SOTER方案指紋和人臉識別接口，則返回0x3 (0x1 | 0x2)；以此類推
請求SOTER生物認證接口
使用場景：開發者調用該接口使用給定的生物認證方式進行符合SOTER規范的可信鑒權
wx.config({
beta:true,
});
wx.ready(function () {
wx.invoke("requireSoterBiometricAuthentication", {"auth_mode": 0xff, "challenge": "sample_challenge",
"auth_content": "請將使用指紋識別"},function(res){
if(res.errCode == 0) {
//檢查use_mode
//使用result_json和result_son_signature本地驗簽是否合法
//使用所提供的后台接口將result_json和result_son_signature發送到微信企業號后台進行驗簽
//處理驗簽結果
} else {
var ret = res.err_msg;
ret += " errCode: " + res.resultCode;
alert(ret);
}
});
});
- 請求參數說明
| 參數 | 必須 | 說明 |
|---|---|---|
| auth_mode | 是 | 生物識別方式（注1） |
| challege | 是 | 挑戰因子（注2） |
| auth_content | 否 | 驗證描述，即識別過程中顯示在界面上的對話框提示內容。 |
- 返回示例
{
"err_code":0,
"err_msg":"ok",
"use_mode":"bxLdikRXVbTPdHSM05e5u5sUoXNKdvsdshFKA",
"result_json":"$RESULRTJSON",
"result_json_signature":"$RESULRTJSONSIGNATURE",
}
- 參數說明
| 參數 | 說明 |
|---|---|
| err_code | 本地生物識別結果（錯誤碼見表3） |
| err_msg | 本地生物識別結果的錯誤信息 |
| use_mode | 所使用的生物識別方式（定義見表1） |
| result_json | 在設備安全區域（TEE）內獲得的本機安全信息（如TEE名稱版本號等以及防重放參數）以及本次認證信息（僅Android支持，本次認證的指紋ID）（注3） |
| result_json_signature | 使用SOTER安全密鑰對result_json的簽名(SHA256withRSA/PSS, saltlen=20) |
注1：本次請求使用的生物識別方式。生物識別方式及其定義見表1。例如：如果本次請求使用指紋識別，則填入0x1；目前只支持指紋識別。
注2：挑戰因子為調用者為此次生物鑒權准備的用於簽名的字符串關鍵是別信息，將作為result_json的一部分，供調用者識別本次請求。例如：如果場景為請求用戶對某訂單進行授權確認，則可以將訂單號填入此參數。
注3：此數據為設備TEE中，將傳入的challenge和TEE內其他安全信息組成的數據進行組裝而來的JSON，對下述字段的解釋如表2。例子如下：
{ "raw":"msg", "fid":"2", "counter":123, "tee_n":"TEE Name", "tee_v":"TEE Version", "fp_n":"Fingerprint Sensor Name", "fp_v":"Fingerprint Sensor Version", "cpu_id":"CPU Id", "uid":"21"}
表1：生物識別方式定義
| 生物識別方式 | 十六進制定義 |
|---|---|
| 指紋識別 | 0x1 |
表2：result_json中個字段含義
| 字段名 | 含義 |
|---|---|
| raw | 調用者傳入的challenge |
| fid | （僅Android支持）本次生物識別認證的生物信息編號（如指紋識別則是指紋信息在本設備內部編號） |
| counter | 防重放特征參數 |
| tee_n | TEE名稱（如高通或者trustonic等） |
| tee_v | TEE版本號 |
| fp_n | 指紋以及相關邏輯模塊提供商（如FPC等） |
| fp_v | 指紋以及相關模塊版本號 |
| cpu_id | 機器唯一識別ID |
| uid | 概念同Android系統定義uid，即應用程序編號 |
表3：本接口err_code以及對應的解釋
| 錯誤碼 | 解釋 |
|---|---|
| 0 | 識別成功 |
| 90001 | 本設備不支持SOTER |
| 90002 | 用戶未授權微信使用該生物認證接口 |
| 90003 | 請求使用的生物識別方式不支持 |
| 90004 | 未傳入challenge或challenge長度過長（最長512字符） |
| 90005 | auth_content長度超過限制（最長42個字符） |
| 90007 | 內部錯誤 |
| 90008 | 用戶取消授權 |
| 90009 | 識別失敗 |
| 90010 | 重試次數過多被凍結 |
對於本接口，官方推薦的流程如下：
1.調用請求SOTER生物認證jsapi
2.jsapi返回成功之后，即err_code返回0,開發者本地進行校驗簽名，校驗方法參見注4（可選）
3.異步調用指紋認證后台接口校驗
注4：此處使用SHA256withRSA/PSS作為簽名算法進行驗簽。此公式數學定義如下： bool 驗簽結果=verify(result_json，result_json_signature，auth_key)。
SOTER生物認證后台接口
- 請求說明
Https請求方式: POST
https://qyapi.weixin.qq.com/cgi-bin/soter/verify_signature?access_token=ACCESS_TOKEN
post數據格式json：
{
"openid":"OWefdsjafasEFD",
"json_string" : "JSON",
"json_signature" : "FDJSFSOIDUSAIDASJDASD"
}
- 請求參數說明
| 參數 | 必須 | 說明 |
|---|---|---|
| access_token | 是 | 企業號接口調用憑證 |
| openid | 是 | 用戶在企業號的openid |
| json_string | 是 | requireSoterBiometricAuthentication接口返回的result_json_string字段（注意該字段需要json轉義） |
| json_signature | 是 | requireSoterBiometricAuthentication接口返回的result_json_signature字段 |
- 返回結果
如果驗證成功，返回
{"is_ok":ok}
驗證失敗返回
{"is_ok":false}
附錄1-JS-SDK使用權限簽名算法
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）：http://qydev.weixin.qq.com/wiki/index.php?title=%E4%B8%BB%E5%8A%A8%E8%B0%83%E7%94%A8
- 用第一步拿到的access_token 采用http GET方式請求獲得jsapi_ticket（有效期7200秒，開發者必須在自己的服務全局緩存jsapi_ticket）：https://qyapi.weixin.qq.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（當前網頁的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=http://mp.weixin.qq.com
步驟1. 對所有待簽名參數按照字段名的ASCII 碼從小到大排序（字典序）后，使用URL鍵值對的格式（即key1=value1&key2=value2…）拼接成字符串string1：
jsapi_ticket=sM4AOVdWfPE4DxkXGEs8VMCPGGVi4C3VM0P37wVUCFvkVAy_90u5h9nbSlYy3-Sl-HhTdfl2fzFy1AOcHKP7qg&noncestr=Wm3WZYTPz0wzccnW×tamp=1414587457&url=http://mp.weixin.qq.com
步驟2. 對string1進行sha1簽名，得到signature：
0f9de62fce790f9a083d5c99e95740ceb90c27ed
注意事項
- 簽名用的noncestr和timestamp必須與wx.config中的nonceStr和timestamp相同。
- 簽名用的url必須是調用JS接口頁面的完整URL。
- 出於安全考慮，開發者必須在服務器端實現簽名的邏輯。
如出現invalid signature 等錯誤詳見附錄5常見錯誤及解決辦法。
附錄2-企業號管理組權限驗證方法
企業號部分JS-SDK（如：打開企業通訊錄選人）的使用需要經過兩部分的權限驗證：
- 通過config接口進行JS-SDK權限驗證，與普通JS-SDK相同，請參考：步驟二：通過config接口注入權限驗證配置
- 企業號管理組權限驗證，步驟如下：
步驟1：通過API獲取管理組JS-SDK憑據
與附錄1-JS-SDK使用權限簽名算法中的jsapi_ticket類似，開發者也是用access_token通過http GET請求獲取管理組臨時票據：https://qyapi.weixin.qq.com/cgi-bin/ticket/get?access_token=ACCESS_TOKEN&type=contact
成功返回如下JSON：
{
"errcode": 0,
"errmsg": "ok",
"group_id": "g50a5axxxx91706a",
"ticket": "WSfTOWPg35IBK9TpwfIi_dVRKrfigCi0TOCw-ZdFnLm4GgxxxxxxxxxxwB7AD64",
"expires_in": 7200
}
- 與jsapi_ticket類似，該ticket有效期通常也為7200秒（以返回結果中的expires_in為准），開發者必須在自己的服務全局緩存該ticket）
- group_id是access_token對應管理組的標識符
步驟2：生成簽名
簽名算法與附錄1-JS-SDK使用權限簽名算法類似。參與簽名的字段包括noncestr（隨機字符串）, 有效的group_ticket（在這里即是步驟1獲取的ticket）, timestamp（時間戳）, url（要使用該JS-SDK的頁面的url，生成的簽名只允許在該url頁面使用） 。對所有待簽名參數按照字段名的ASCII碼從小到大排序（字典序）后，使用URL鍵值對的格式（即key1=value1&key2=value2…）拼接成字符串string1：
group_ticket=WSfTOWPg35xxxxxxxxxCi0TOCw-ZdFnLm4Ggvssk4suhakGwB7AD64&noncestr=Wm3WZYTPz0wzccnW×tamp=1447334894&url=http://your.website.com
將string1作sha1加密，得到簽名signature：
f211c9c1b375aae79ad74685450149825b2b2353
附錄3-所有JS接口列表
版本1.1.0接口
- openEnterpriseChat
- openEnterpriseContact
- onMenuShareTimeline
- onMenuShareAppMessage
- onMenuShareQQ
- onMenuShareWeibo
- onMenuShareQZone
- 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
附錄4-所有菜單項列表
基本類
- 舉報: "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"
附錄5-卡券擴展字段及簽名生成算法
JSSDK使用者請讀這里，JSAPI用戶可以跳過
卡券簽名和JSSDK的簽名完全獨立，兩者的算法和意義完全不同，請不要混淆。JSSDK的簽名是使用所有JS接口都需要走的一層鑒權，用以標識調用者的身份，和卡券本身並無關系。其次，卡券的簽名考慮到協議的擴展性和簡單的防數據擅改，設計了一套獨立的簽名協議。另外由於歷史原因，卡券的JS接口先於JSSDK出現，當時的JSAPI並沒有鑒權體系，所以在卡券的簽名里也加上了appsecret/api_ticket這些身份信息，希望開發者理解。
卡券 api_ticket
卡券 api_ticket 是用於調用卡券相關接口的臨時票據，有效期為 7200 秒，通過 access_token 來獲取。這里要注意與 jsapi_ticket 區分開來。由於獲取卡券 api_ticket 的 api 調用次數非常有限，頻繁刷新卡券 api_ticket 會導致 api 調用受限，影響自身業務，開發者必須在自己的服務全局緩存卡券 api_ticket 。參考獲取api_ticket文檔
卡券擴展字段cardExt說明
cardExt本身是一個JSON字符串，是商戶為該張卡券分配的唯一性信息，包含以下字段：
| 字段 | 是否必須 | 是否參與簽名 | 說明 |
|---|---|---|---|
| code | 否 | 是 | 指定的卡券code碼，只能被領一次。use_custom_code字段為true的卡券必須填寫，非自定義code和get_custom_code_mode(預存code模式的卡券)不必填寫。 |
| openid | 否 | 是 | 指定領取者的openid，只有該用戶能領取。bind_openid字段為true的卡券必須填寫，bind_openid字段為false不必填寫。 |
| timestamp | 是 | 是 | 時間戳，商戶生成從1970年1月1日00:00:00至今的秒數,即當前的時間,且最終需要轉換為字符串形式;由商戶生成后傳入,不同添加請求的時間戳須動態生成，若重復將會導致領取失敗！。 |
| nonce_str | 否 | 是 | 隨機字符串，由開發者設置傳入，加強安全性（若不填寫可能被重放請求）。隨機字符串，不長於32位。推薦使用大小寫字母和數字，不同添加請求的nonce須動態生成，若重復將會導致領取失敗。 |
| outer_str | 否 | 否 | 領取渠道參數，用於標識本次領取的渠道值。 |
| signature | 是 | 是 | 簽名，商戶將接口列表中的參數按照指定方式進行簽名,簽名方式使用SHA1,具體簽名方案參見下文;由商戶按照規范簽名后傳入。 |
簽名說明
- 將 api_ticket（特別說明：api_ticket 相較 appsecret 安全性更高，同時兼容老版本文檔中使用的 appsecret 作為簽名憑證。）、timestamp、card_id、code、openid、nonce_str的value值進行字符串的字典序排序。
- 將所有參數字符串拼接成一個字符串進行sha1加密，得到signature。
- signature中的timestamp，nonce字段和card_ext中的timestamp，nonce_str字段必須保持一致。
- code=jonyqin_1434008071，timestamp=1404896688，card_id=pjZ8Yt1XGILfi-FUsewpnnolGgZk， api_ticket=ojZ8YtyVyr30HheH3CM73y7h4jJE ，nonce_str=jonyqin 則signature=sha1(1404896688jonyqinjonyqin_1434008071ojZ8YtyVyr30HheH3CM73y7h4jJE pjZ8Yt1XGILfi-FUsewpnnolGgZk)=6b81fbf6af16e856334153b39737556063c82689。
強烈建議開發者使用卡券資料包中的簽名工具SDK進行簽名或使用debug工具進行校驗：http://mp.weixin.qq.com/debug/cgi-bin/sandbox?t=cardsign
卡券簽名cardSign說明
- 將 api_ticket（特別說明：api_ticket 相較 appsecret 安全性更高，同時兼容老版本文檔中使用的 appsecret 作為簽名憑證。）、app_id、location_id、times_tamp、nonce_str、card_id、card_type的value值進行字符串的字典序排序。
- 將所有參數字符串拼接成一個字符串進行sha1加密，得到cardSign。
附錄6-常見錯誤及解決方法
調用config接的時候傳入參數debug: true 可以開啟debug模式，頁面會alert出錯誤信息。以下為常見錯誤及解決方法：
- invalid url domain：當前頁面所在域名與使用的corpid沒有綁定（可在該企業號的應用可信域名中配置域名）。
- invalid signature簽名錯誤：建議按如下順序檢查：
- 確認簽名算法正確，可用 http://mp.weixin.qq.com/debug/cgi-bin/sandbox?t=jsapisign 頁面工具進行校驗。
- 確認config中nonceStr（js中駝峰標准大寫S）, timestamp與用以簽名中的對應noncestr, timestamp一致。
- 確認url是頁面完整的url(請在當前頁面alert(location.href.split('#')[0])確認)，包括'http(s)://'部分，以及'？'后面的GET參數部分,但不包括'#'hash后面的部分。
- 確認config中的appid與用來獲取jsapi_ticket的corpid一致。
- 確保一定緩存access_token和jsapi_ticket。
- 確保你獲取用來簽名的url是動態獲取的，動態頁面可參見實例代碼中php的實現方式。如果是html的靜態頁面在前端通過ajax將url傳到后台簽名，前端需要用js獲取當前頁面除去'#'hash部分的鏈接（可用location.href.split('#')[0]獲取,而且需要encodeURIComponent），因為頁面一旦分享，微信客戶端會在你的鏈接末尾加入其它參數，如果不是動態獲取當前鏈接，將導致分享后的頁面簽名失敗。
- the permission value is offline verifying：這個錯誤是因為config沒有正確執行，或者是調用的JSAPI沒有傳入config的jsApiList參數中。建議按如下順序檢查：
- 確認config正確通過。
- 如果是在頁面加載好時就調用了JSAPI，則必須寫在wx.ready的回調中。
- 確認config的jsApiList參數包含了這個JSAPI。
- permission denied：該企業號沒有權限使用這個JSAPI（部分接口需要認證之后才能使用）。
- function not exist：當前客戶端版本不支持該接口，請升級到新版體驗。
- 為什么6.0.1版本config:ok，但是6.0.2版本之后不ok：因為6.0.2版本之前沒有做權限驗證，所以config都是ok，但這並不意味着你config中的簽名是ok的，請在6.0.2檢驗是否生成正確的簽名以保證config在高版本中也ok。
- 在iOS和Android都無法分享：請確認企業號已經認證，只有認證的企業號才具有分享相關接口權限，如果確實已經認證，則要檢查監聽接口是否在wx.ready回調函數中觸發）
- 服務上線之后無法獲取jsapi_ticket，自己測試時沒問題：因為access_token和jsapi_ticket必須要在自己的服務器緩存，否則上線后會觸發頻率限制。請確保一定對token和ticket做緩存以減少服務器請求，不僅可以避免觸發頻率限制，還加快你們自己的服務速度。目前為了方便測試提供了1w的獲取量，超過閥值后，服務將不再可用，請確保在服務上線前一定全局緩存access_token和jsapi_ticket，兩者有效期均為7200秒（以返回結果中的expires_in為准），否則一旦上線觸發頻率限制，服務將不再可用。
- uploadImage怎么傳多圖：目前只支持一次上傳一張，多張圖片需等前一張圖片上傳之后再調用該接口。
- 沒法對本地選擇的圖片進行預覽：chooseImage接口本身就支持預覽，不需要額外支持。
- 通過a鏈接(例如先通過微信授權登錄)跳轉到b鏈接，invalid signature簽名失敗：后台生成簽名的鏈接為使用jssdk的當前鏈接，也就是跳轉后的b鏈接，請不要用微信登錄的授權鏈接進行簽名計算，后台簽名的url一定是使用jssdk的當前頁面的完整url除去'#'部分。
- 出現config:fail錯誤：這是由於傳入的config參數不全導致，請確保傳入正確的appId、timestamp、nonceStr、signature和需要使用的jsApiList。
- 如何把jsapi上傳到微信的多媒體資源下載到自己的服務器：請參見文檔中uploadVoice和uploadImage接口的備注說明。
- Android通過jssdk上傳到微信服務器，第三方再從微信下載到自己的服務器，會出現雜音：微信團隊已經修復此問題，目前后台已優化上線。
- 綁定父級域名，是否其子域名也是可用的：是的，合法的子域名在綁定父域名之后是完全支持的。
- 在iOS微信6.1版本中，分享的圖片外鏈不顯示，只能顯示企業號頁面內鏈的圖片或者微信服務器的圖片：已在6.2中修復。
- 是否需要對低版本自己做兼容：jssdk都是兼容低版本的，不需要第三方自己額外做更多工作，但有的接口是6.0.2新引入的，只有新版才可調用。
- 使用pushState來實現web app的頁面會導致簽名失敗：此問題已在Android6.2中修復。
- uploadImage在chooseImage的回調中有時候Android會不執行，Android6.2會解決此問題，若需支持低版本可以把調用uploadImage放在setTimeout中延遲100ms解決。
- getLocation返回的坐標在openLocation有偏差，因為getLocation返回的是gps坐標，openLocation打開的騰訊地圖為火星坐標，需要第三方自己做轉換，6.2版本開始已經支持直接獲取火星坐標。
附錄7-DEMO頁面和示例代碼
DEMO頁面：
http://demo.open.weixin.qq.com/jssdk
示例代碼：
http://demo.open.weixin.qq.com/jssdk/sample.zip
備注：鏈接中包含php、java、nodejs以及python的示例代碼供第三方參考，第三方切記要對獲取的accesstoken以及jsapi_ticket進行緩存以確保不會觸發頻率限制。
附錄8-問題反饋
郵箱地址：weixin-open@qq.com
郵件主題：【微信JS-SDK反饋】
郵件內容說明：
用簡明的語言描述問題所在，並交代清楚遇到該問題的場景，可附上截屏圖片，微信團隊會盡快處理你的反饋。