開放接口

功能說明：此 API 需要和宿主客戶端聯調，在真機上傳回的內容是由宿主用戶端提供，可自訂回傳內容。 IDE 目前暫不支持，在 IDE 中可以使用 mock 面板進行傳回值的 mock。
檢查登入態是否過期。透過 wx.login 介面獲得的使用者登入態擁有一定的時效性。用戶越久未使用小遊戲，用戶登入態越有可能失效。反之如果使用者一直在使用小遊戲，使用者登入態一直保持有效。具體時效邏輯由官方維護，對開發者透明。開發者只需要呼叫 wx.checkSession 介面檢測目前使用者登入態是否有效。
登入態過期後開發者可以再呼叫 wx.login 取得新的使用者登入態。呼叫成功說明目前 session_key 未過期，呼叫失敗說明 session_key 已過期。
參數及說明： Object object。

内容	類型	預設值	必填	說明
success	Function	-	否	接口調用成功的回呼函數
fail	Function	-	否	接口調用失敗的回呼函數
complete	Function	-	否	接口調用結束的回呼函數（無論成功與否都執行）

示例代碼：

wx.checkSession({
  success() {
    // The session_key has not expired and remains valid for this lifecycle.
  },
  fail() {
    // The session_key has expired, and the login process needs to be executed again.
    wx.login(); // Log in again.
  },
});

帳號資訊

getAccountInfoSync

TIP

該API使用方法為： Object wx.getAccountInfoSync()

TIP

該API小程序支持，小遊戲暫不支持

功能說明：取得目前帳號資訊。線上小遊戲版本號僅支援在正式版小遊戲中獲取，開發版和體驗版中無法獲取。
返回值： Object 帳號資訊。

内容	類型	說明
miniProgram	Object	小遊戲帳號訊息

miniProgram結構内容

結構内容	類型	說明
appId	string	小程序appId
envVersion	string	小程序版本，合法值為： develop：開發版 trial：體驗版 release：正式版
version	string	線上小程序版本號

用戶資訊

getUserInfo

TIP

該API使用方法為： wx.getUserInfo(Object object)

功能說明：取得目前帳號資訊。線上小遊戲版本號僅支援在正式版小遊戲中獲取，開發版和體驗版中無法獲取。
獲取用戶資訊，在使用過程中需要用戶授權scope.userInfo。
參數及說明： Object object。

内容	類型	預設值	必填	說明
lang	string	en	否	顯示用戶資訊的語言，合法值為： en：英文 zh_TW: 繁體中文
success	Function	-	否	接口調用成功的回呼函數
fail	Function	-	否	接口調用失敗的回呼函數
complete	Function	-	否	接口調用結束的回呼函數（調用成功、失敗都會執行）

object.success回呼函數參數： Object res

内容	類型	說明
userInfo	UserInfo	用戶資訊對象

示例代碼：

// Must be called when the user has already authorized.
wx.getUserInfo({
  success: function (res) {
    var userInfo = res.userInfo;
    var nickName = userInfo.nickName;
    var avatarUrl = userInfo.avatarUrl;
  },
});

userInfo

功能說明： 用戶資訊
參數及說明：

内容	類型	說明
nickName	string	用戶昵稱
avatarUrl	string	用戶頭像圖片的URL。 URL最後一個數值代表正方形頭像大小（有0、46、64、96、132數值可選，0代表640x640的正方形頭像，46表示46x46的正方形頭像，剩餘數值以此類推。默認132），用戶沒有頭像時該項為空。若用戶更換頭像，原有頭像URL將失效
gender	number	用戶性別。不再返回，合法值為： 0：未知 1：男性 2：女性
country	string	用戶所在國家。不再返回
province	string	用戶所在地區。不再返回
city	string	用戶所在都市。不再返回
language	string	顯示country，province，city所用的語言。強制返回'zh_TW'，合法值為： en：英文 zh_TW: 繁體中文

設定

AuthSetting

功能說明： 用戶授權設定資訊。
參數及說明：

内容	說明
boolean scope.userInfo	是否授權使用者信息，對應介面 wx.getUserInfo
boolean scope.writePhotosAlbum	是否授權儲存到相簿 wx.saveImageToPhotosAlbum
boolean scope.userLocation	是否授權精確地理位置，對應介面 wx.getLocation
boolean scope.userFuzzyLocation	是否授權模糊地理位置，對應介面 wx.getFuzzyLocation

getSetting

TIP

該API使用方法為： wx.getSetting(Object object)

功能說明： 取得使用者目前的設置，返回值中只會出現小遊戲已經向使用者請求過的權限。
參數及說明： Object object。

内容	類型	預設值	必填	說明
success	Function	-	否	接口調用成功的回呼函數
fail	Function	-	否	接口調用失敗的回呼函數
complete	Function	-	否	接口調用結束的回呼函數（無論成功與否都執行）

object.success回呼函數參數： Object res

内容	類型	說明
authSetting	AuthSetting	用戶授權結果

示例代碼：

wx.getSetting({
  success(res) {
    console.log(res.authSetting);
    // res.authSetting = {
    //   "scope.userInfo": true,
    //   "scope.userLocation": true
    // }
  },
});

openSetting

TIP

該API使用方法為： wx.openSetting(Object object)

功能說明： 調起客戶端小遊戲設定介面，返回使用者設定的操作結果，使用者發生點選行為後，可以跳轉開啟設定頁，管理授權資訊。設定介面只會出現小遊戲已經向使用者請求過的權限。
參數及說明： Object object。

内容	類型	預設值	必填	說明
success	Function	-	否	接口調用成功的回呼函數
fail	Function	-	否	接口調用失敗的回呼函數
complete	Function	-	否	接口調用結束的回呼函數（無論成功與否都執行）

object.success回呼函數參數： Object res

内容	類型	說明
authSetting	AuthSetting	用戶授權結果

示例代碼：

wx.openSetting({
  success(res) {
    console.log(res.authSetting);
    // res.authSetting = {
    //   "scope.userInfo": true,
    //   "scope.userLocation": true
    // }
  },
});

授權

authorize

TIP

該API使用方法為：wx.authorize(Object object)

功能說明： 提前向使用者發起授權請求。呼叫後會立刻彈出視窗詢問使用者是否同意授權小遊戲使用某項功能或取得使用者的某些數據，但不會實際呼叫對應介面。如果使用者之前已經同意授權，則不會出現彈跳窗，直接返回成功。
參數及說明： Object object。

内容	類型	預設值	必填	說明
scope	string	-	是	需要獲取許可權的scope詳見scope
success	Function	-	否	接口調用成功的回呼函數
fail	Function	-	否	接口調用失敗的回呼函數
complete	Function	-	否	接口調用結束的回呼函數（無論成功與否都執行）

示例代碼：

// You can query whether the user has authorized the scope of "scope.userLocation" using wx.getSetting.
wx.getSetting({
  success(res) {
    if (!res.authSetting["scope.userLocation"]) {
      wx.authorize({
        scope: "scope.userLocation",
        success() {
          wx.getLocation();
        },
      });
    }
  },
});

隱私資訊授權

requirePrivacyAuthorize

TIP

該API使用方法為：wx.requirePrivacyAuthorize(Object object)

功能說明： 模擬隱私介面調用，並觸發隱私彈窗邏輯。
參數及說明： Object object。

内容	類型	預設值	必填	說明
success	Function	-	否	接口調用成功的回呼函數
fail	Function	-	否	接口調用失敗的回呼函數
complete	Function	-	否	接口調用結束的回呼函數（無論成功與否都執行）

具體說明：
- 呼叫 wx.requirePrivacyAuthorize() 時：
  - 如果使用者之前已經同意過隱私授權，會立即返回 success 回調，不會觸發 wx.onNeedPrivacyAuthorization 事件。
  - 如果使用者之前沒有授權過，並且開發者註冊了 wx.onNeedPrivacyAuthorization() 事件監聽，就會立即觸發 wx.onNeedPrivacyAuthorization 事件，然後開發者在 onNeedPrivacyAuthorization 回調中彈出自定義隱私授權彈窗，用戶點了同意後開發者對Pox ，會觸發 requirePrivacyAuthorize 的 success 回呼。使用者點選拒絕授權後開發者呼叫 wx.onNeedPrivacyAuthorization 的回呼介面 resolve({ event: 'disagree' }) 的話，會觸發 requirePrivacyAuthorize 的 fail 回呼。
  - 如果使用者之前沒有授權過，且開發者沒有註冊 wx.onNeedPrivacyAuthorization() 事件監聽，就會立即彈出平台提供的統一隱私授權彈窗，使用者點了同意之後，會觸發 requirePrivacyAuthorize 的 success 回呼，使用者點了拒絕後會觸發 requirePrivacyAuthorPrivacyAuthorize 的 fail 迴調。
  - 基於上述特性，開發者可以在調用任何真實隱私介面之前調用 wx.requirePrivacyAuthorize 介面來模擬隱私介面調用，並觸發隱私彈窗（包括自訂彈窗或平台彈窗）邏輯。
- 一定要呼叫 wx.requirePrivacyAuthorize 介面嗎？
  - 不是，wx.requirePrivacyAuthorize 只是一個輔助接口，可以根據實際情況選擇使用。當開發者希望在呼叫隱私介面之前就主動彈出隱私彈跳窗時，就可以使用這個介面。
示例代碼：

wx.requirePrivacyAuthorize({
  success: () => {
    // The user agrees to the authorization.
    // runGame () Continue the game logic.
  },
  fail: () => {}, // The user desagrees to the authorization.
  complete: () => {},
});

onNeedPrivacyAuthorization

TIP

該API使用方法為：wx.onNeedPrivacyAuthorization(function listener)

功能說明： 監聽隱私介面需要使用者授權事件。小遊戲註冊此事件監聽後，會啟用自訂隱私授權彈跳窗模式，當需要使用者進行隱私授權時會觸發此事件。觸發事件時，開發者需要彈出隱私協定說明，並在使用者同意或拒絕授權後呼叫回調介面 resolve 觸發原隱私介面繼續執行。
參數及說明： function listener, 隱私介面需要使用者授權事件的監聽函數。
回調參數：
- function resolve
  - resolve 是 onNeedPrivacyAuthorization 的首個回呼參數，是一個介面函數。
  - 當觸發 onNeedPrivacyAuthorization 事件時，觸發該事件的隱私介面會處於 pending 狀態。
  - 如果呼叫 resolve({ event:'agree' })，則觸發目前 onNeedPrivacyAuthorization 事件的原隱私介面會繼續執行。
  - 如果呼叫 resolve({ event: 'disagree' })，則觸發目前 onNeedPrivacyAuthorization 事件的原隱私介面會失敗並傳回 API:fail privacy permission is not authorized 的錯誤訊息。
  - 在呼叫 resolve({ event: 'agree'/'disagree' }) 之前，開發者可以呼叫 resolve({ event: 'exposureAuthorization' }) 把隱私彈跳窗曝光告知平台。
- Object eventInfo
  eventInfo 是 onNeedPrivacyAuthorization 的第二個回呼參數，表示觸發本次 onNeedPrivacyAuthorization 事件的關聯資訊。
  内容類型說明
  referrer string 觸發本次 onNeedPrivacyAuthorization 事件的介面或元件名（例如："getUserInfo"）
- resolve 介面參數：
  内容類型說明
  event string 使用者操作類型
- event 合法值：
  event 說明
  exposureAuthorization 自訂隱私彈跳窗曝光
  agree 使用者同意隱私授權
  disagree 用戶拒絕隱私授權
具體說明：
- 小遊戲未註冊 wx.onNeedPrivacyAuthorization 事件監聽時，會預設使用平台統一隱私彈跳窗。
- 小遊戲註冊 wx.onNeedPrivacyAuthorization 後，會切換至自訂隱私彈跳窗，此時需要開發者自行渲染隱私彈跳窗。
- 什麼時候會觸發 onNeedPrivacyAuthorization 事件？
  - 呼叫隱私相關介面（例如 wx.getUserInfo、wx.getClipboardData），且使用者尚未同意過隱私協定時。
  - 呼叫 wx.requirePrivacyAuthorize 介面來模擬隱私介面調用，且使用者尚未同意過隱私協定時。
  - 如果使用者已經同意過隱私協議，則不會再觸發 onNeedPrivacyAuthorization 事件。
- 當觸發 onNeedPrivacyAuthorization 事件時，觸發該事件的隱私介面會處於 pending 狀態，等待使用者授權後才會繼續執行，此時開發者需要彈出自訂隱私彈窗，並在使用者點擊同意/拒絕後呼叫回調介面 resolve，觸發該事件的隱私介面才會繼續執行。
- 開發者必須在使用者產生點擊操作時呼叫 resolve 介面
- wx.onNeedPrivacyAuthorization 是覆蓋式註冊監聽，若重複註冊監聽，則只有最後一次註冊會生效。
- 一定要註冊 wx.onNeedPrivacyAuthorization 監聽以及呼叫 resolve 嗎？
  - 不是的，如果使用小遊戲官方彈跳窗，不使用自訂彈跳窗，那就不需要 wx.onNeedPrivacyAuthorization。
  - 但如果註冊了 wx.onNeedPrivacyAuthorization 監聽，則一定要呼叫 resolve 介面。
示例代碼：

内容	類型	說明
referrer	string	觸發本次 onNeedPrivacyAuthorization 事件的介面或元件名（例如："getUserInfo"）

内容	類型	說明
event	string	使用者操作類型

event	說明
exposureAuthorization	自訂隱私彈跳窗曝光
agree	使用者同意隱私授權
disagree	用戶拒絕隱私授權

wx.onNeedPrivacyAuthorization((resolve, eventInfo) => {
  console.log("The API that triggered this event is " + eventInfo.referrer);
  // ------ Custom pop-up logic ------ //
  showCustomPopup();
  // -------After the pop-up window appears, the following logical is implemented based on user operations    After the popup, handle user actions ------- //
  // Developer displays the custom privacy popup and calls resolve to notify the platform that the popup has been shown.
  resolve({ event: "exposureAuthorization" });
  // After the user taps Agree, the developer calls resolve to inform the platform about the user’s authorization.
  resolve({ event: "agree" });
  // After the user taps Disagree the developer calls resolve to inform the platform that the user has denied the authorization.
  resolve({ event: "disagree" });
});

了解小程序

配置小程序

小程序框架

基礎能力

小程序配置

框架接口

wxml語法參考

wxs語法參考

界面

網絡

畫布

媒體

設備

遊戲引擎

運行時

基礎能力

渲染

設備

開放接口

登入

checkSession

帳號資訊

getAccountInfoSync

用戶資訊

getUserInfo

userInfo

設定

AuthSetting

getSetting

openSetting

授權

authorize

隱私資訊授權

requirePrivacyAuthorize

onNeedPrivacyAuthorization

開放接口 ​

登入 ​

login ​

checkSession ​

帳號資訊 ​

getAccountInfoSync ​

用戶資訊 ​

getUserInfo ​

userInfo ​

設定 ​

AuthSetting ​

getSetting ​

openSetting ​

授權 ​

authorize ​

隱私資訊授權 ​

requirePrivacyAuthorize ​

onNeedPrivacyAuthorization ​

開放接口

登入

login

checkSession

帳號資訊

getAccountInfoSync

用戶資訊

getUserInfo

userInfo

設定

AuthSetting

getSetting

openSetting

授權

authorize

隱私資訊授權

requirePrivacyAuthorize

onNeedPrivacyAuthorization