1.用戶授權(quán)

部分接口需要經(jīng)過用戶授權(quán)同意才能調(diào)用。這些接口按使用范圍分成多個 scope ，用戶選擇對 scope 來進(jìn)行授權(quán)，當(dāng)授權(quán)給一個 scope 之后，其對應(yīng)的所有接口都可以直接使用。

調(diào)用接口發(fā)起授權(quán)

第一次使用某個 scope 下的接口時，會彈窗詢問用戶，“XXX申請獲得以下權(quán)限：（權(quán)限描述）”。如果用戶點擊允許，則可獲得此 scope 的接口權(quán)限。并且接口調(diào)用成功，否則接口調(diào)用失敗。

wx.login({
  success: function () {
    wx.getUserInfo()
  }
})

提前發(fā)起授權(quán)

如果需要提前發(fā)起授權(quán)獲得用戶同意，則可調(diào)用 [wx.authorize()] 來提前發(fā)起授權(quán)。

wx.authorize({
  scope: 'scope.record'
})

處理用戶拒絕授權(quán)

用戶有可能拒絕小程序發(fā)起的授權(quán)申請，需要處理這種情況。

wx.login({
  success: function () {
    wx.getUserInfo({
      fail: function (res) {
        // iOS 和 Android 對于拒絕授權(quán)的回調(diào) errMsg 沒有統(tǒng)一，需要做一下兼容處理
        if (res.errMsg.indexOf('auth deny') > -1 ||     res.errMsg.indexOf('auth denied') > -1 ) {
          // 處理用戶拒絕授權(quán)的情況
        }
      }
    })
  }
})

wx.authorize({
  scope: 'scope.record',
  fail: function (res) {
    // iOS 和 Android 對于拒絕授權(quán)的回調(diào) errMsg 沒有統(tǒng)一，需要做一下兼容處理
    if (res.errMsg.indexOf('auth deny') > -1 ||     res.errMsg.indexOf('auth denied') > -1 ) {
      // 處理用戶拒絕授權(quán)的情況
    }    
  }
})

獲取用戶授權(quán)設(shè)置

通過調(diào)用 [wx.getSetting()]接口可以獲取用戶當(dāng)前的授權(quán)處理信息。

wx.getSetting({
  success: function (res) {
    var authSetting = res.authSetting
    if (authSetting['scope.userInfo'] === true) {
      // 用戶已授權(quán)，可以直接調(diào)用相關(guān) API
    } else if (authSetting['scope.userInfo'] === false){
      // 用戶已拒絕授權(quán)，再調(diào)用相關(guān) API 或者 wx.authorize 會失敗，需要引導(dǎo)用戶到設(shè)置頁面打開授權(quán)開關(guān)
    } else {
      // 未詢問過用戶授權(quán)，調(diào)用相關(guān) API 或者 wx.authorize 會彈窗詢問用戶
    }
  }
})

引導(dǎo)用戶重新授權(quán)

如果用戶拒絕過某個 scope 的授權(quán)申請，則后續(xù)這個 scope 下的相關(guān) API 調(diào)用都會直接失敗，用 [wx.authorize()]申請此 scope 也會直接失敗，而不會彈窗詢問用戶。這種情況下，需要引導(dǎo)用戶主動到設(shè)置頁面打開相應(yīng)的 scope 權(quán)限。

授權(quán)頁面的進(jìn)入路徑為：右上角菜單->關(guān)于（小程序名字）->右上角菜單->設(shè)置

Scope 列表

2.用戶登錄態(tài)簽名

小程序的一部分后臺(HTTP)接口要求驗證用戶登錄態(tài)。開發(fā)者在調(diào)用時需提供以session_key為密鑰生成的簽名。其中session_key是指通過wx.login 獲得的登錄態(tài)。

簽名算法

目前支持的簽名算法是 hmac_sha256。 對于POST請求，開發(fā)者生成簽名的算法是：

signature = hmac_sha256( post_data, session_key )

其中post_data為本次POST請求的數(shù)據(jù)包。特別地，對于GET請求，post_data等于長度為0的字符串。

signature = hmac_sha256( "", session_key )

簽名示例

例如開發(fā)者需要請求的HTTP（POST）接口，其中請求包為一個json字符串。

curl -d '{"foo":"bar"}' 'https://api.weixin.qq.com/some_api?access_token=xxx&openid=xxx&signature=???&sig_method=hmac_sha256'

開發(fā)者需要計算出signature參數(shù)。假設(shè)用戶當(dāng)前有效的session_key 為 ：

'o0q0otL8aEzpcZL/FT9WsQ=='

則開發(fā)者生成簽名應(yīng)該是

hmac_sha256('{"foo":"bar"}', 'o0q0otL8aEzpcZL/FT9WsQ==') = 654571f79995b2ce1e149e53c0a33dc39c0a74090db514261454e8dbe432aa0b

開發(fā)者服務(wù)器發(fā)起的HTTP請求

curl -d '{"foo":"bar"}' 'https://api.weixin.qq.com/some_api?access_token=xxx&openid=xxx&signature=654571f79995b2ce1e149e53c0a33dc39c0a74090db514261454e8dbe432aa0b&sig_method=hmac_sha256'

session_key 合法性校驗

我們提供接口供開發(fā)者校驗服務(wù)器所保存的登錄態(tài)session_key是否合法。 為了保持session_key私密性，我們提供的校驗接口本身不直接明文session_key，而是通過校驗登錄態(tài)簽名完成。

接口地址
請求方法：GET

https://api.weixin.qq.com/wxa/checksession?access\_token=ACCESS\_TOKEN&signature=SIGNATURE&openid=OPENID&sig\_method=SIG\_METHOD

調(diào)用示例

curl -G 'https://api.weixin.qq.com/wxa/checksession?access_token=OsAoOMw4niuuVbfSxxxxxxxxxxxxxxxxxxx&signature=fefce01bfba4670c85b228e6ca2b493c90971e7c442f54fc448662eb7cd72509&openid=oGZUI0egBJY1zhBYw2KhdUfwVJJE&sig_method=hmac_sha256'

參數(shù)說明

返回結(jié)果

//正確時的返回JSON數(shù)據(jù)包如下：
{"errcode":0,"errmsg":"ok"}
//錯誤時的返回JSON數(shù)據(jù)包如下（示例為簽名錯誤）：
{"errcode":87009,"errmsg":"invalid signature"}

3.米大師支付簽名

以查詢余額的接口為例，原始請求信息：
米大師密鑰：zNLgAGgqsEWJOg1nFVaO5r7fAlIQxr1u
HTTP請求方式: POST
請求的URI：/cgi-bin/midas/getbalance

sig簽名
參與米大師簽名請求參數(shù)

"openid":"odkx20ENSNa2w5y3g_qOkOvBNM1g",
"appid":"wx1234567",
"offer_id":"12345678",
"ts":1507530737,
"zone_id":"1",
"pf":"iap"

對參與米大師簽名的參數(shù)按照key=value的格式，并按照參數(shù)名ASCII字典序升序排序如下：

stringA="appid=wx1234567&offer_id=12345678&openid=odkx20ENSNa2w5y3g_qOkOvBNM1g&pf=iap&ts=1507530737&zone_id=1"

拼接uri、method和米大師密鑰：

stringSignTemp=stringA+"&org_loc=/cgi-bin/midas/getbalance&method=POST&secret=zNLgAGgqsEWJOg1nFVaO5r7fAlIQxr1u"

把米大師密鑰作為key，使用HMAC-SHA256得到簽名。

sig=hmac_sha256(key,stringSignTemp)
   ="d1f0a41272f9b85618361323e1b19cd8cb0213f21b935aeaa39c160892031e97"

mp_sig簽名

1 參與開平簽名請求參數(shù)

"access_token":"ACCESSTOKEN",
"openid":"odkx20ENSNa2w5y3g_qOkOvBNM1g",
"appid":"wx1234567",
"offer_id":"12345678",
"ts":1507530737,
"zone_id":"1",
"pf":"iap",
"sig":"d1f0a41272f9b85618361323e1b19cd8cb0213f21b935aeaa39c160892031e97"

2 對參與開平簽名的參數(shù)按照key=value的格式，并按照參數(shù)名ASCII字典序升序排序如下：

stringA="access_token=ACCESSTOKEN&appid=wx1234567&offer_id=12345678&openid=odkx20ENSNa2w5y3g_qOkOvBNM1g&pf=iap&sig=d1f0a41272f9b85618361323e1b19cd8cb0213f21b935aeaa39c160892031e97&ts=1507530737&zone_id=1"

3 拼接uri、method和session_key：

stringSignTemp=stringA+"&org_loc=/cgi-bin/midas/getbalance&method=POST&session_key=V7Q38/i2KXaqrQyl2Yx9Hg=="

4 把session_key作為key，使用HMAC-SHA256得到簽名。

mp_sig=hmac_sha256(key,stringSignTemp)   ="f7fc0198b1bf795892bed804d145206105eb5835d6ac53fd745834b4a1236c78"

4.關(guān)系鏈數(shù)據(jù)使用指南

一個微信用戶的關(guān)系鏈數(shù)據(jù)包括兩部分：

• 該用戶好友的用戶數(shù)據(jù)
• 該用戶所在的某個群的群成員的用戶數(shù)據(jù)。

獲取關(guān)系鏈數(shù)據(jù)的 API：

• [wx.getFriendCloudStorage()]獲取當(dāng)前用戶也玩該小游戲的好友的用戶數(shù)據(jù)
• [wx.getGroupCloudStorage()]獲取當(dāng)前用戶在某個群中也玩該小游戲的成員的用戶數(shù)據(jù)

這兩個 API 的返回結(jié)果都是一個對象數(shù)組，數(shù)組的每一個元素都是一個表示用戶數(shù)據(jù)的對象，其結(jié)構(gòu)如下：

用戶的 游戲數(shù)據(jù) 指的是用戶的段位、戰(zhàn)績等游戲業(yè)務(wù)特有的數(shù)據(jù)，通過調(diào)用 [wx.setUserCloudStorage()]可以將當(dāng)前用戶的游戲數(shù)據(jù)托管在微信后臺。只有被托管過數(shù)據(jù)的用戶，才會被視為 玩過 該小游戲的用戶，才會出現(xiàn)在 [wx.getFriendCloudStorage()] 和 [wx.getGroupCloudStorage()] 返回的對象數(shù)組中。

還提供了以下 API：

• [wx.removeUserCloudStorage()] 刪除用戶托管數(shù)據(jù)中指定字段的數(shù)據(jù)
• [wx.getUserCloudStorage()]獲取當(dāng)前用戶的托管數(shù)據(jù)

[wx.getUserCloudStorage]、[wx.getFriendCloudStorage()]和 [wx.getGroupCloudStorage()] 只能在 開放數(shù)據(jù)域 中調(diào)用。
[wx.setUserCloudStorage()]和 [wx.removeUserCloudStorage()]可以同時在 主域 和開放數(shù)據(jù)域中調(diào)用。

開放數(shù)據(jù)域

開放數(shù)據(jù)域 是一個封閉、獨立的 JavaScript 作用域。要讓代碼運(yùn)行在開放數(shù)據(jù)域，需要在 game.json 中添加配置項 openDataContext 指定開放數(shù)據(jù)域的代碼目錄。添加該配置項表示小游戲啟用了開放數(shù)據(jù)域，這將會導(dǎo)致一些 [限制]。

{
  "deviceOrientation": "portrait",
  "openDataContext": "src/myOpenDataContext"
}

同時還需要在該目錄下創(chuàng)建 index.js 作為開放數(shù)據(jù)域的入口文件，其代碼運(yùn)行在開放數(shù)據(jù)域。game.js 是整個游戲的入口文件，其代碼運(yùn)行在 主域。
主域和開放數(shù)據(jù)域中的代碼不能相互 require。

主域和開放數(shù)據(jù)域的通信

開放數(shù)據(jù)域不能向主域發(fā)送消息。

主域可以向開放數(shù)據(jù)域發(fā)送消息。調(diào)用 wx.getOpenDataContext()方法可以獲取開放數(shù)據(jù)域?qū)嵗{(diào)用實例上的 OpenDataContext.postMessage()]方法可以向開放數(shù)據(jù)域發(fā)送消息。

// game.js
let openDataContext = wx.getOpenDataContext()
openDataContext.postMessage({
  text: 'hello',
  year: (new Date()).getFullYear()
})

在開放數(shù)據(jù)域中通過 wx.onMessage()方法可以監(jiān)聽從主域發(fā)來的消息。

// src/myOpenDataContext/index.js
wx.onMessage(data => {
  console.log(data)
  /* {
    text: 'hello',
    year: 2018
  } */
})

展示關(guān)系鏈數(shù)據(jù)

如果想要展示通過關(guān)系鏈 API 獲取到的用戶數(shù)據(jù)，如繪制排行榜等業(yè)務(wù)場景，需要將排行榜繪制到 sharedCanvas 上，再在主域?qū)?sharedCanvas 渲染上屏。

// src/myOpenDataContext/index.js
let sharedCanvas = wx.getSharedCanvas()

function drawRankList (data) {
  data.forEach((item, index) => {
    // ...
  })
}

wx.getFriendUserGameData({
  success: res => {
    let data = res.data
    drawRankList(data)
  }
})

sharedCanvas 是主域和開放數(shù)據(jù)域都可以訪問的一個離屏畫布。在開放數(shù)據(jù)域調(diào)用 wx.getSharedCanvas() 將返回 sharedCanvas。

// src/myOpenDataContext/index.js
let sharedCanvas = wx.getSharedCanvas()
let context = sharedCanvas.getContext('2d')
context.fillStyle = 'red'
context.fillRect(0, 0, 100, 100)

在主域中可以通過開放數(shù)據(jù)域?qū)嵗L問 sharedCanvas，通過 drawImage() 方法可以將 sharedCanvas 繪制到上屏畫布。

// game.js
let openDataContext = wx.getOpenDataContext()
let sharedCanvas = openDataContext.canvas

let canvas = wx.createCanvas()
let context = canvas.getContext('2d')
context.drawImage(sharedCanvas, 0, 0)

5. 虛擬支付

小游戲為開發(fā)者提供游戲內(nèi)虛擬物品的購買服務(wù)。

注：目前小游戲虛擬支付能力只支持在安卓Android系統(tǒng)內(nèi)使用，暫不開放蘋果iOS系統(tǒng)內(nèi)虛擬支付功能。

在開通虛擬支付功能前，開發(fā)者需完成：

1. 開通小程序微信支付
2. 申請開通小游戲虛擬支付

wx.requestMidasPayment()是我們提供購買游戲幣的API：

wx.requestMidasPayment(Object options)

示例代碼

// 游戲幣
wx.requestMidasPayment({
    mode: 'game',
    offerId: '',
    buyQuantity: 10,
    zoneId: 1,
    success() {
        // 支付成功
    },
    fail({ errMsg, errCode }) {
        // 支付失敗
        console.log(errMsg, errCode)
    }
})

提供用于測試驗證與調(diào)試的沙箱測試環(huán)境，并相應(yīng)提供以下API：

6.獲取二維碼

小游戲的二維碼與小程序有著相同的樣式和獲取方式。通過后臺接口可以獲取小游戲的二維碼，掃描該二維碼可以直接進(jìn)入小游戲。目前微信支持兩種二維碼;

7. 轉(zhuǎn)發(fā)

用戶在使用小游戲過程中，可轉(zhuǎn)發(fā)消息給其他用戶或群聊。

轉(zhuǎn)發(fā)菜單

點擊右上角按鈕，會彈出菜單，菜單中的“轉(zhuǎn)發(fā)”選項默認(rèn)不展示。通過 [wx.showShareMenu()] 和 [wx.hideShareMenu()]可動態(tài)顯示、隱藏這個選項。

被動轉(zhuǎn)發(fā)

用戶點擊右上角菜單中的“轉(zhuǎn)發(fā)”選項后，會觸發(fā)轉(zhuǎn)發(fā)事件，如果小游戲通過 [wx.onShareAppMessage()] 監(jiān)聽了這個事件，可通過返回自定義轉(zhuǎn)發(fā)參數(shù)來修改轉(zhuǎn)發(fā)卡片的內(nèi)容，否則使用默認(rèn)內(nèi)容。

wx.onShareAppMessage(function () {
  // 用戶點擊了“轉(zhuǎn)發(fā)”按鈕
  return {
    title: '轉(zhuǎn)發(fā)標(biāo)題'
  }
})

主動轉(zhuǎn)發(fā)

游戲內(nèi)可通過 [wx.shareAppMessage()]接口直接調(diào)起轉(zhuǎn)發(fā)界面，與被動轉(zhuǎn)發(fā)類似，可以自定義轉(zhuǎn)發(fā)卡片內(nèi)容。

wx.shareAppMessage({
  title: '轉(zhuǎn)發(fā)標(biāo)題'
})

使用 Canvas 內(nèi)容作為轉(zhuǎn)發(fā)圖片

如果不指定轉(zhuǎn)發(fā)圖片，默認(rèn)會顯示一個小程序的 logo。如果希望轉(zhuǎn)發(fā)的時候顯示 Canvas 的內(nèi)容，可以使用 [Canvas.toTempFilePath()]或 [Canvas.toTempFilePathSync()]來生成一張本地圖片，然后把圖片路徑傳給 imageUrl 參數(shù)。

轉(zhuǎn)發(fā)出來的消息卡片中，圖片的最佳顯示比例是 5：4。

wx.onShareAppMessage(function () {
  return {
    title: '轉(zhuǎn)發(fā)標(biāo)題',
    imageUrl: canvas.toTempFilePathSync({
      destWidth: 500,
      destHeight: 400
    })
  }
})

withShareTicket 模式

通過 [wx.updateShareMenu] 接口可修改轉(zhuǎn)發(fā)屬性。如果設(shè)置 withShareTicket 為 true ，會有以下效果

1. 選擇聯(lián)系人的時候只能選擇一個目標(biāo)，不能多選
2. 消息被轉(zhuǎn)發(fā)出去之后，在會話窗口中無法被長按二次轉(zhuǎn)發(fā)
3. 消息轉(zhuǎn)發(fā)的目標(biāo)如果是一個群聊，則
   • 會在轉(zhuǎn)發(fā)成功的時候獲得一個 shareTicket
   • 每次用戶從這個消息卡片進(jìn)入的時候，也會獲得一個 shareTicket，通過調(diào)用 [wx.getShareInfo()] 接口傳入 shareTicket 可以獲取群相關(guān)信息

修改這個屬性后，同時對主動轉(zhuǎn)發(fā)和被動轉(zhuǎn)發(fā)生效。

// 設(shè)置 withShareTicket: true
wx.updateShareMenu({
  withShareTicket: true
})

8.用戶數(shù)據(jù)的簽名驗證和加解密

數(shù)據(jù)簽名校驗

為了確保開放接口返回用戶數(shù)據(jù)的安全性，微信會對明文數(shù)據(jù)進(jìn)行簽名。開發(fā)者可以根據(jù)業(yè)務(wù)需要對數(shù)據(jù)包進(jìn)行簽名校驗，確保數(shù)據(jù)的完整性。

1. 簽名校驗算法涉及用戶的session_key，通過 [wx.login] 登錄流程獲取用戶session_key，并自行維護(hù)與應(yīng)用自身登錄態(tài)的對應(yīng)關(guān)系。
2. 通過調(diào)用接口（如 wx.getUserInfo]獲取數(shù)據(jù)時，接口會同時返回 rawData、signature，其中 signature = sha1( rawData + session_key )
3. 開發(fā)者將 signature、rawData 發(fā)送到開發(fā)者服務(wù)器進(jìn)行校驗。服務(wù)器利用用戶對應(yīng)的 session_key 使用相同的算法計算出簽名 signature2 ，比對 signature 與 signature2 即可校驗數(shù)據(jù)的完整性。

加密數(shù)據(jù)解密算法

接口如果涉及敏感數(shù)據(jù)（如[wx.getUserInfo]當(dāng)中的 openId 和unionId ），接口的明文內(nèi)容將不包含這些敏感數(shù)據(jù)。開發(fā)者如需要獲取敏感數(shù)據(jù)，需要對接口返回的加密數(shù)據(jù)( encryptedData )進(jìn)行對稱解密。 解密算法如下：

1. 對稱解密使用的算法為 AES-128-CBC，數(shù)據(jù)采用PKCS#7填充。
2. 對稱解密的目標(biāo)密文為 Base64_Decode(encryptedData)。
3. 對稱解密秘鑰 aeskey = Base64_Decode(session_key), aeskey 是16字節(jié)。
4. 對稱解密算法初始向量 為Base64_Decode(iv)，其中iv由數(shù)據(jù)接口返回。

另外，為了應(yīng)用能校驗數(shù)據(jù)的有效性，我們會在敏感數(shù)據(jù)加上數(shù)據(jù)水印( watermark )

watermark參數(shù)說明：