微信JS-SDK說明文檔


微信JS-SDK說明文件

#

1474938226449452.jpg

「概述

#################微信JS-SDK是微信公眾平台提供給網頁開發者的以微信內為基礎的網頁開發工具包。 ############透過使用微信JS-SDK，網頁開發者可藉助微信高效地使用拍照、選圖、語音、位置等手機系統的能力，同時可以直接使用微信分享、掃一掃、卡券、付款等微信特有的能力，提供微信使用者更優質的網頁體驗。 ######

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

JSSDK使用步驟

##步驟一：綁定網域名稱

先登入微信公眾平台進入「公眾號設定」的「功能設定」裡填寫“ JS介面安全域名」。

備註：登入後可在「開發者中心」查看對應的介面權限。

步驟二：引入JS檔案

在需要呼叫JS介面的頁面引入如下JS文件，（支援https）：http://res.wx.qq.com/open/js/jweixin-1.0.0.js

#如需使用搖晃週邊功能，請引入http://res.wx.qq.com/open/js/jweixin-1.1.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: '', // 必填，公眾號的唯一識別

    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中的相關介面。

備註：不要嘗試在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來檢測。

#分享介​​面

請注意不要有誘導分享等違規行為，對於誘導分享行為將永久回收公眾號介面權限，詳細規則請查看：朋友圈管理常見問題 。

取得「分享到朋友圈」按鈕點擊狀態及自訂分享內容介面

#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，參考文件.目前多媒體檔案下載介面的頻率限制為10000次/天，如需要調高頻率，請登入微信公眾平台，在開發- 介面權限的清單中，申請提高臨時上限。

#下載語音介面

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.

#        var speed = res.

##        var speed = res.

##        var speed = res.

##        var speed = res.

##  中”下速度，速度下。米/每秒計

        var accuracy = res.accuracy; // 位置精確度
########    }#####################    }#####################    }######### ###});##########

搖晃週邊

##開啟尋找周邊ibeacon裝置介面

wx.startSearchBeacons({

#ticket:"",  //搖週邊的業務ticket, 系統自動加入在搖出來的頁面連結後面

complete:function(argv){

//開啟尋找完成後的回呼函數

###}#### ########});#########

備註：如需存取搖一搖週邊功能，請參考：申請開通搖一搖週邊

關閉查找週邊ibeacon設備介面

wx.stopSearchBeacons({

#complete:function(res){

//關閉查找完成後的回呼函數

##}

});

監聽週邊ibeacon裝置介面

wx.onSearchBeacons({

complete:function(argv){

//回呼函數，可以陣列形式取得該商家註冊的在周邊的相關裝置清單

}

##});

備註：上述搖一搖週邊介面使用注意事項及更多返回結果說明，請參考：搖一搖週邊獲取設備資訊

介面操作

#隱藏右上角選單介面

################# ################wx.hideOptionMenu();###########################顯示右上角選單介面#####################wx.showOptionMenu();#########

關閉目前網頁視窗介面

#wx.closeWindow();

「批次隱藏功能按鈕介面

## ######wx.hideMenuItems({############    menuList: [] // 要隱藏的選單項目，只能隱藏「傳播類別」和「保護類別」按鈕，所有menu項見附錄3############});##########

批次顯示功能按鈕介面

#wx.showMenuItems({

    menuList: [] // 要顯示的選單項，所有menu項見附錄3

});

#隱藏所有非基礎按鈕介面

wx. hideAllNonBaseMenuItem();

// 「基本類別」按鈕詳見附錄3

顯示所有功能按鈕介面

#wx.showAllNonBaseMenuItem();

微信掃一掃描

調起微信掃一掃介面

wx.scanQRCode({

    needResult: 0 , // 預設為0，掃描結果由微信處理，1則直接回傳掃描結果，

    scanType: ["qrCode","barCode"], // 可以指定掃二維碼還是一維碼，預設二者都有

    success: function (res) {

    var result = res.resultStr; // 當needResult 為1 時，掃碼回傳的結果############}###########});########

微信小店

跳轉微信商品頁介面

wx.openProductSpecificView({

    productId: '', // 商品id

    viewType: '' // 0.預設值，一般商品詳情頁1.掃一掃商品詳情頁2.小店商品詳情頁

});

微信卡券

#微信卡券介面中使用的簽章憑證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。

介面呼叫請求說明

#http請求方式: GET

https://api.weixin.qq.com/cgi-bin/ticket/getticket?access_token=ACCESS_TOKEN&type=wx_card

#

參數說明

參數
 		#是否必須
##access_token是介面呼叫憑證
##################### ##

傳回資料

#資料範例：

# {

##"errcode":0,

"errmsg":"ok" ,

"ticket":"bxLdikRXVbTPdHSM05e5u5sUoXNKdvsdshFKA",

"expires_in":7200

## }

參數名稱描述
errcode#錯誤碼
errmsg錯誤訊息
ticketapi_ticket，卡券介面中簽署所需憑證
#expires_in
##################### ############有效時間###############

拉取適用卡券清單並取得使用者選擇資訊

wx.chooseCard({

    shopId: '', // 門市Id

##    cardType: '', // 卡券類型

    cardId: '', // 卡券Id

#    timestamp: 0, // 卡券簽章時間戳

    nonceStr: '', // 卡券簽署隨機串

#    signType: '', // 簽章方式，預設'SHA1'

    cardSign: '', // 卡券簽章

    success: function (res) {

#        var cardList= resr#        var cardList= res .cardList; // 使用者選取的卡券清單資訊

    }

###

});

參數名稱必填類型範例值描述
shopId 否string(24)1234門市ID。 shopID用於篩選出拉起帶有指定location_list(shopID)的卡券列表，非必填。
cardType##string(24)GROUPON卡券類型，用於拉起指定卡券類型的卡券清單。當cardType為空時，預設拉起所有卡券的列表，非必填。
cardId##string(32 )p1Pj9jr90_SQRaVqYI239Ka1erk卡券ID，用於拉起指定cardId的卡券列表，當cardId為空時，預設拉起所有卡券的列表，非必填。
timestamp#是string(32)14300000000時間戳。
nonceStr#是string(32)sduhi123隨機字串。
signType#是string(32)SHA1簽署方式，目前僅支援SHA1
cardSign是string(64)abcsdijcous123#簽名。
#

開發者特別注意：簽章錯誤會導致拉取卡券清單異常為空，請仔細檢查參與簽章的參數有效性。

特別提醒

#拉取清單僅與使用者本地卡券有關，拉起清單異常為空的情況通常有三種：簽章錯誤、時間戳無效、篩選機制有誤。請開發者依序排查定位原因。

#批次新增卡券介面

wx.addCard({

    cardList: [{

        cardId: '',

# cardExt: ''

    }], // 需要新增的卡券清單

    success: function (res) {

#        var cardList = res.cardList; // 新增的卡券清單資訊

    }

});

值得注意的是，這裡的card_ext參數必須與參與簽章的參數一致，格式為字串而不是Object，否則會報章錯誤。

建議開發者一次加入的卡券不超過5張，否則會遇到逾時報錯。

查看微信卡包中的卡券介面

wx.openCard({

    cardList: [{

        cardId: '',

        code: ''

    }]// 需要開啟的卡片清單

});

#############});###### ####

微信支付

發起一個微信支付請求

wx.chooseWXPay({

    timestamp: 0, // 支付簽章時間戳，注意微信jssdk中的所有使用timestamp欄位均為小寫。但最新版的付款後台產生簽章使用的timeStamp欄位名需大寫其中的S字

    nonceStr: '', // 支付簽章隨機字串，不長於32 位元

    package: '', // 統一支付介面傳回的prepay_id參數值，提交格式如：prepay_id=** *）

###    signType: '', // 簽章方式，預設為'SHA1'，使用新版付款需傳入'MD5'########### #    paySign: '', // 支付簽章############    success: function (res) {#######

        // 付款成功後的回呼函數

    }

});

#

備註：prepay_id 透過微信支付統一下單介面拿到，paySign 採用統一的微信支付Sign 簽名產生方法，注意這裡appId 也要參與簽名，appId 與config 中傳入的appId 一致，即最後參與簽章的參數有appId, timeStamp, nonceStr, package, signType。

微信支付開發文件：https://pay.weixin.qq.com/wiki/doc/api/index.html

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

jsapi_ticket

#在產生簽章之前必須先了解一下jsapi_ticket，jsapi_ticket是公眾號碼用於呼叫微信JS介面的暫存票據。正常情況下，jsapi_ticket的有效期限為7200秒，透過access_token來取得。由於取得jsapi_ticket的api呼叫次數非常有限，頻繁刷新jsapi_ticket會導致api呼叫受限，影響自身業務，開發者必須在自己的服務全域快取jsapi_ticket 。

#

1.參考以下文件取得access_token（有效期7200秒，開發者必須在自己的服務全域快取access_token）：../15/54ce45d8d30b6bf6758f68d2e95bc627.html

##########################################1 ######2.用第一步拿到的access_token 採用http GET方式請求取得jsapi_ticket（###有效期限7200秒，開發者必須在自己的服務全域快取jsapi_ticket###）：https:// api.weixin.qq.com/cgi-bin/ticket/getticket?access_token=ACCESS_TOKEN&type=jsapi###########成功返回如下JSON：####################成功返回如下JSON：############ ###{############"errcode":0,#############"errmsg":"ok",######## ####"ticket":"bxLdikRXVbTPdHSM05e5u5sUoXNKd8-41ZO3MhKoyN5OfkWITDGgnr2fwJ0m9E8NYzWKVZvdVtaUgWv#shFKA",##0FKA",##005"##2##00,#,#0FKA",##00],##005",##00],##00],##00],##00],##009,##00],##0FKA」,##00],##005",##00],##00],##0FKA」,##20 ### ###

取得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=sM4AOVdWfPE4DxkXGEs8VMCPGGVi4C3VM0P37wVUCF P7qg

#timestamp=1414587457

url=http://mp.weixin.qq.com?params=value

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

jsapi_ticket =sM4AOVdWfPE4DxkXGEs8VMCPGGVi4C3VM0P37wVUCFvkVAy_90u5h9nbSlYy3-Sl-HhTdfl2fzFy1AOcHKP7qg&noncestr=Wm3WZ params=value

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

0f9de62fce790f9a083d5c99e95740ceb90c27ed

#

注意事項

1.簽名用的noncestr和timestamp必須與wx.config中的nonceStr和timestamp相同。

2.簽名用的url必須是呼叫JS介面頁面的完整URL。

3.出於安全性考慮，開發者必須在伺服器端實作簽章的邏輯。

如出現invalid signature 等錯誤詳見附錄5常見錯誤及解決方法。

附錄2-所有JS介面清單

版本1.0.0介面

#

onMenuShareTimeline

##onMenuShareAppMessage

onMenuShareQQ

#onMenuShareWeibo

##onMenuShareQZone

startRecord

stopRecord

# onVoiceRecordEnd

playVoice

pauseVoice

stopVoice

onVoicePlayEnd

uploadVoice

下載語音

選擇圖片

#預覽圖片

上傳圖片

下載圖片

#

translateVoice

getNetworkType

#openLocation

getLocation

hideOptionMenu

showOptionMenu

hideMenuItems

showMenuItems

隱藏所有非基礎選單項目

#

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"

分享到QQ 空間/menuItem:share:QZone

#保護類別

編輯標籤: " menuItem:editTag"

刪除: "menuItem:delete"

複製連結: "menuItem:copyUrl"

原網頁: "menuItem:originPage"

#

閱讀模式: "menuItem:readMode"

在QQ瀏覽器中開啟: "menuItem:openWithQQBrowser"

#在Safari中開啟: "menuItem:openWithSafari"

#郵件: "menuItem:share:email"

一些特殊公眾號: "menuItem :share:brand"

#附錄4-卡券擴充字段及簽名產生演算法

#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 。

1.參考以下文件取得access_token（有效期限7200秒，開發者必須在自己的服務全域快取access_token）：../15/54ce45d8d30b6bf6758f68d2e95bc627.html

2.用第一步拿到的access_token 採用http GET方式請求取得卡券api_ticket（有效期限7200秒，開發者必須在自己的服務全域快取卡券api_ticket）： https://api.weixin.qq.com/cgi-bin/ticket/getticket?access_token=ACCESS_TOKEN&type=wx_card


# ##卡券擴充字段cardExt說明##################cardExt本身是一個JSON字串，是商家為該張卡券分配的唯一性訊息，包含以下字段：#######

簽章說明

#1.將api_ticket（特別說明：api_ticket 相較appsecret 安全性更高，同時相容於舊版文件中使用的appsecret 作為簽章憑證。）、timestamp、card_id、code、openid、nonce_str的value值進行字串的字典序排序。

2.將所有參數字串拼接成一個字串進行sha1加密，得到signature。

3.signature中的timestamp，nonce欄位和card_ext中的timestamp，nonce_str欄位必須保持一致。

4.code=jonyqin_1434008071，timestamp=1404896688，card_id=pjZ8Yt1XGILfi-FUsewpnnolGgZk， api_ticket=ojZ8YtyVyr30Hhej3000 04896688jonyqinjonyqin_1434008071ojZ8YtyVyr30HheH3CM73y7h4jJE pjZ8Yt1XGILfi-FUsewpnnolGgZk)=6b81fbf6af16e8563416e8563415756857568585683875683875683875。

強烈建議開發者使用卡券資料包中的簽章工具SDK進行簽章或使用debug工具進行校驗：http://mp .weixin.qq.com/debug/cgi-bin/sandbox?t=cardsign


#卡券簽章cardSign說明

1.將api_ticket（特別說明：api_ticket 相較appsecret 安全性更高，同時相容於舊版文件中使用的appsecret 作為簽章憑證。）、app_id、location_id、times_tamp、nonce_str、card_id、card_type的value值進行字串的字典序排序。

2.將所有參數字串拼接成一個字串進行sha1加密，得到cardSign。


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

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

1.invalid url domain目前頁面所在域名與使用的appid沒有綁定，請確認正確填入綁定的域名，僅支援80（ http）和443（https）兩個端口，因此不需要填寫端口號（一個appid可以綁定三個有效域名）。

2.invalid signature簽章錯誤。建議依下列順序檢查：

   1.確認簽章演算法正確，可用 http://mp.weixin.qq.com/debug/cgi-bin/sandbox?t=jsapisign 頁面工具進行校驗。

   2.確認config中nonceStr（js中駝峰標準大寫S）, timestamp與使用以簽名中的對應noncestr, timestamp一致。

   3.確認url是頁面完整的url(請在目前頁面alert(location.href.split('#')[0])確認)，包括'http(s)://'部分，以及'？ '後面的GET參數部分,但不包括'#'hash後面的部分。

   4.確認 config 中的 appid 與用來取得 jsapi_ticket 的 appid 一致。

   5.確保一定快取access_token和jsapi_ticket。

   6.確保你取得用來簽署的url是動態取得的，動態頁面可參考實例程式碼中php的實作方式。如果是html的靜態頁面在前端透過ajax將url傳到後台簽名，前端需要用js獲取當前頁面除去'#'hash部分的連結（可用location.href.split('#')[0]獲取,而且需要encodeURIComponent），因為頁面一旦分享，微信客戶端會在你的鏈接末尾加入其它參數，如果不是動態獲取當前鏈接，將導致分享後的頁面簽名失敗。

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，或是呼叫的JSAPI沒有傳入config的jsApiList參數中（部分介面需要認證之後才能使用）。

5.function not exist目前客戶端版本不支援該接口，請升級至新版體驗。

6.為什麼6.0.1版config:ok，但6.0.2版之後不ok（因為6.0.2版之前沒有做權限驗證，所以config都是ok，但這並不表示你config中的簽章是OK的，請在6.0.2檢驗是否產生正確的簽章以確保config在高版中也ok。）

#

7.在iOS和Android都無法分享（請確認公眾號已經認證，只有認證的公眾號才具有分享相關介面權限，如果確實已經認證，則要檢查監聽介面是否在wx.ready回呼函數中觸發）

8.服務上線之後無法取得jsapi_ticket，自己測試時沒問題。 （因為access_token和jsapi_ticket必須要在自己的伺服器緩存，否則上線後會觸發頻率限制。請確保一定對token和ticket做緩存以減少2次伺服器請求，不僅可以避免觸發頻率限制，還加快你們自己的服務速度。目前為了方便測試提供了1w的獲取量，超過閥值後，服務將不再可用，請確保在服務上線前一定全局緩存access_token和jsapi_ticket，兩者有效期均為7200秒，否則一旦上線觸發頻率限制，服務將不再可用）。

9.uploadImage怎麼傳多圖（目前只支援一次上傳一張，多張圖片需等前一張圖片上傳之後再呼叫該介面）

10.沒辦法對本地選擇的圖片進行預覽（chooseImage介面本身就支援預覽，不需要額外支援）

#

11.透過a連結(例如先透過微信授權登入)跳到b鏈接，invalid signature簽名失敗（後台產生簽名的連結為使用jssdk的目前鏈接，也就是跳轉後的b鏈接，請不要用微信登入的授權連結進行簽章計算，後台簽章的url一定是使用jssdk的目前頁面的完整url除去'#'部分）

12.出現config: fail錯誤（這是因為傳入的config參數不全導致，請確保傳入正確的appId、timestamp、nonceStr、signature和需要使用的jsApiList）

13.如何把jsapi上傳到微信的多媒體資源下載到自己的伺服器（請參閱文件中uploadVoice和uploadImage介面的備註說明）

14.Android透過jssdk上傳到微信伺服器，第三方再從微信下載到自己的伺服器，會出現雜音（微信團隊已經修復此問題，目前後台已優化上線）

15.綁定父級域名，是否其子域名也是可用的（是的，合法的子網域在綁定父網域之後是完全支援的）

16.在iOS微信6.1版本中，分享的圖片外鏈不顯示，只能顯示公眾號頁面內鏈的​​圖片或微信伺服器的圖片，已在6.2中修復

#17.是否需要對低版本自己做兼容（jssdk都是兼容低版本的，不需要第三方自己額外做更多工作，但有的接口是6.0.2新引入的，只有新版才可調用）

18.該公眾號支付簽名無效，無法發起該筆交易（請確保你使用的jweixin.js是官方線上版本，不僅可以減少用戶流量，還有可能對某些bug進行修復，拷貝到第三方伺服器中使用，官方將不對其出現的任何問題提供保障）

19.目前Android微信客戶端不支援pushState的H5新特性，所以使用pushState來實作web app的頁面會導致簽章失敗，此問題已在Android6.2中修正

20.uploadImage在chooseImage的回呼中有時候Android會不執行，Android6.2會解決這個問題，若需支援低版本可以把呼叫uploadImage放在setTimeout中延遲100ms解決

21.require subscribe錯誤說明你沒有訂閱該測試號，該錯誤只會測試號會出現

22.getLocation傳回的座標在openLocation有偏差，因為getLocation回傳的是gps座標，openLocation開啟的騰訊地圖為火星座標，需要第三方自己做轉換，6.2版本開始已經支援直接取得火星座標

23.查看公眾號（未新增）: "menuItem:addContact"不顯示，目前僅有從公眾號傳播出去的連結才能顯示，來源必須是公眾號

24.ICP備案資料同步有一天延遲，所以請在第二日綁定

附錄6-DEMO頁面與範例程式碼

#DEMO頁面：

http://demo.open.weixin.qq.com/jssdk

1475985030261979.jpg

範例程式碼：

#http://demo.open.weixin.qq .com/jssdk/sample.zip

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

附錄7-問題回饋

信箱位址： weixin-open@qq.com

#

郵件主題：【微信JS-SDK回饋】

郵件內容說明：

用簡潔的語言描述問題所在，並交代清楚遇到該問題的場景，可附上截圖圖片，微信團隊會盡快處理你的回饋。


#
←
→

PHP中文網

首頁首頁課程課程文章文章問答問答詞典詞典手册手册下載下載搜尋搜尋APP下載 APP下載
欄位#是否必填#是否參與簽章說明
code否是#指定的卡券code碼，只能領一次。自訂code模式的卡券必須填寫，非自訂code和預存code模式的卡券不必填寫。詳情請見：是否自訂code碼
openid否是指定領取者的openid，只有該使用者能領取。 bind_openid欄位為true的卡券必須填寫，bind_openid欄位為false不必填寫。
timestamp#是是時間戳，商家產生從1970年1月1日00:00:00至今的秒數,即當前的時間,且最終需要轉換為字串形式;由商家產生後傳入,不同添加請求的時間戳鬚動態生成，若重複將會導致領取失敗！ 。
nonce_str#是############是##### #######隨機字串，由開發者設定傳入，###加強安全性（若不填寫可能被重播要求）###。隨機字串，不長於32位。建議使用大小寫字母和數字，不同添加請求的nonce須動態生成，若重複將會導致領取失敗。
fixed_begintimestamp#否##否
############################################ #######卡券的領取時間，為10位時間戳記。當卡券的有效期限類型為###DAT###E_TYPE_FIX_TERM時專用，標示卡券的實際生效時間，用於解決商家系統內起始時間和領取時間不同步的問題。 ########################outer_id#########################否############領取頻道參數，用於識別本次領取的頻道值。
signature#是##-簽名，商家將介面清單中的參數依照指定方式進行簽名,簽名方式使用SHA1,具體簽章方案參考下文;由商家依照規範簽署後傳入。