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)限描述）”信姓。如果用戶點(diǎ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)接口要求驗(yàn)證用戶登錄態(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ā)者需要計(jì)算出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 合法性校驗(yàn)

我們提供接口供開發(fā)者校驗(yàn)服務(wù)器所保存的登錄態(tài)session_key是否合法。 為了保持session_key私密性沼死，我們提供的校驗(yàn)接口本身不直接明文session_key着逐，而是通過校驗(yàn)登錄態(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ù)域 是一個封閉仿粹、獨(dú)立的 JavaScript 作用域。要讓代碼運(yùn)行在開放數(shù)據(jù)域原茅，需要在 game.json 中添加配置項(xiàng) openDataContext 指定開放數(shù)據(jù)域的代碼目錄吭历。添加該配置項(xiàng)表示小游戲啟用了開放數(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)用實(shí)例上的 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. 虛擬支付

小游戲?yàn)殚_發(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)
    }
})

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

6.獲取二維碼

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

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

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

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

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

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

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

wx.onShareAppMessage(function () {
  // 用戶點(diǎn)擊了“轉(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ù)的簽名驗(yàn)證和加解密

數(shù)據(jù)簽名校驗(yàn)

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

1. 簽名校驗(yàn)算法涉及用戶的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)行校驗(yàn)窍仰。服務(wù)器利用用戶對應(yīng)的 session_key 使用相同的算法計(jì)算出簽名 signature2 ，比對 signature 與 signature2 即可校驗(yàn)數(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)用能校驗(yàn)數(shù)據(jù)的有效性，我們會在敏感數(shù)據(jù)加上數(shù)據(jù)水印( watermark )

watermark參數(shù)說明：