Open Interface

Login

login

TIP

The API usage is as follows: wx.login(Object object)

• Functional description: This API needs to be debugged with the host client. The content returned on the real machine is provided by the host client, and the return content can be customized. IDE does not currently support it. In the IDE, you can use the mock panel to mock the return value.
• Parameters and descriptions: Object object。

Properties	Type	Default value	Required	Description
success	Function	-	No	Callback function for successful interface call
fail	Function	-	No	Callback function for failed interface call
complete	Function	-	No	Callback function for interface call completion (executed regardless of success or failure)

• Sample code:

wx.login({
  success(res) {
    console.log(res, "---------------info, host app return");
  },
});

checkSession

TIP

The API usage is as follows: wx.checkSession(Object object)

TIP

This API is supported by mini programs, but not by mini games.

• Functional description: This API needs to be debugged with the host client. The content returned on the real machine is provided by the host client, and the return content can be customized. IDE does not currently support it. In the IDE, you can use the mock panel to mock the return value.
• Check whether the login state is expired. The user login state obtained through the wx.login interface has a certain timeliness. The longer the user has not used the mini-game, the more likely the user login state is to expire. On the contrary, if the user has been using the mini-game, the user login state remains valid. The specific timeliness logic is maintained by the official and is transparent to developers. Developers only need to call the wx.checkSession interface to check whether the current user login state is valid.
• After the login state expires, developers can call wx.login again to obtain a new user login state. A successful call indicates that the current session_key has not expired, and a failed call indicates that the session_key has expired.
• Parameters and descriptions: Object object。

Properties	Type	Default value	Required	Description
success	Function	-	No	Callback function for successful interface call
fail	Function	-	No	Callback function for failed interface call
complete	Function	-	No	Callback function for interface call completion (executed regardless of success or failure)

• Sample code:

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.
  },
});

Account information

getAccountInfoSync

TIP

The API usage is as follows: Object wx.getAccountInfoSync()

TIP

This API is supported by mini programs, but not by mini games.

• Functional description: Get the current account information. The version number of online mini games can only be obtained in the official version of the mini game, and cannot be obtained in the development version and the trial version.
• Return value: Object Account information。

Properties	Type	Description
miniProgram	Object	Mini game account information

• miniProgram structure attribute

Structure properties	Type	Description
appId	string	Mini program appId
envVersion	string	Mini program version, legal value is: develop：Development version trial：Experience version release：Official version
version	string	Online mini program version number

User information

getUserInfo

TIP

The API usage is as follows: wx.getUserInfo(Object object)

• Functional description: Get the current account information. The version number of online mini games can only be obtained in the official version of the mini game, and cannot be obtained in the development version and the trial version.
• Obtain user information, user authorization scope.userInfo is required during use.
• Parameters and descriptions: Object object。

Properties	Type	Default value	Required	Description
lang	string	en	No	The language for displaying user information, legal value is: en：English zh_TW: Traditional Chinese
success	Function	-	No	Callback function for successful interface call
fail	Function	-	No	Callback function for failed interface call
complete	Function	-	No	Callback function for interface call end (will be executed for both successful and failed calls)

• object.success callback function parameters: Object res

Properties	Type	Description
userInfo	UserInfo	User information object

• Sample code:

// 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

• Functional description: User information
• Parameters and descriptions:

Properties	Type	Description
nickName	string	User nickname
avatarUrl	string	The URL of the user's avatar image. The last value of the URL represents the square avatar size (there are 0, 46, 64, 96, 132 values
gender	number	User gender. No longer returned, legal values 0: Unknown 1: Male 2: Female
country	string	User's country. No more returns
province	string	User's region. No more returns
city	string	User's city. No more returns
language	string	Display the language used by country, province, and city. Forced to return 'zh_TW', legal values en：English zh_TW: Traditional Chinese

Settings

AuthSetting

• Functional description: User authorization setting information.
• Parameters and descriptions:

Properties	Description
boolean scope.userInfo	Whether to authorize user information, corresponding interface wx.getUserInfo
boolean scope.writePhotosAlbum	Whether to authorize saving to the album wx.saveImageToPhotosAlbum
boolean scope.userLocation	Whether to authorize precise geographic location, corresponding interface wx.getLocation
boolean scope.userFuzzyLocation	Whether to authorize fuzzy geographic location, corresponding interface wx.getFuzzyLocation

getSetting

TIP

The API usage is as follows: wx.getSetting(Object object)

• Functional description: Get the user's current settings, and the return value will only show the permissions that the mini game has requested from the user.
• Parameters and descriptions: Object object。

Properties	Type	Default value	Required	Description
success	Function	-	No	Callback function for successful interface call
fail	Function	-	No	Callback function for failed interface call
complete	Function	-	No	Callback function for interface call completion (executed regardless of success or failure)

• object.success callback function parameters: Object res

Properties	Type	Description
authSetting	AuthSetting	User authorization result

• Sample code:

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

openSetting

TIP

The API usage is as follows: wx.openSetting(Object object)

• Functional description: Call up the client mini game settings interface and return the operation results set by the user. After the user clicks, he can jump to open the settings page and manage the authorization information. The settings interface will only show the permissions that the mini game has requested from the user.
• Parameters and descriptions: Object object。

Properties	Type	Default value	Required	Description
success	Function	-	No	Callback function for successful interface call
fail	Function	-	No	Callback function for failed interface call
complete	Function	-	No	Callback function for interface call completion (executed regardless of success or failure)

• object.success callback function parameters: Object res

Properties	Type	Description
authSetting	AuthSetting	User authorization result

• Sample code:

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

Authorization

authorize

TIP

The API usage is as follows:wx.authorize(Object object)

• Functional description: Initiate an authorization request to the user in advance. After the call, a pop-up window will immediately appear to ask the user whether to authorize the mini-game to use a certain function or obtain certain user data, but the corresponding interface will not be actually called. If the user has already agreed to the authorization, no pop-up window will appear and success will be returned directly.
• Parameters and descriptions: Object object。

Properties	Type	Default value	Required	Description
scope	string	-	Yes	Scopes that need to obtain permissionsSee scope for details
success	Function	-	No	Callback function for successful interface call
fail	Function	-	No	Callback function for failed interface call
complete	Function	-	No	Callback function for interface call completion (executed regardless of success or failure)

• Sample code:

// 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();
        },
      });
    }
  },
});

Privacy information authorization

requirePrivacyAuthorize

TIP

The API usage is as follows:wx.requirePrivacyAuthorize(Object object)

• Functional description: Simulate the call of the privacy interface and trigger the privacy pop-up window logic.
• Parameters and descriptions: Object object。

Properties	Type	Default value	Required	Description
success	Function	-	No	Callback function for successful interface call
fail	Function	-	No	Callback function for failed interface call
complete	Function	-	No	Callback function for interface call completion (executed regardless of success or failure)

• Specific instructions:

  • When calling wx.requirePrivacyAuthorize():
    • If the user has previously agreed to privacy authorization, the success callback will be returned immediately, and the wx.onNeedPrivacyAuthorization event will not be triggered.
    • If the user has not authorized before, and the developer has registered the wx.onNeedPrivacyAuthorization() event listener, the wx.onNeedPrivacyAuthorization event will be triggered immediately, and then the developer will pop up a custom privacy authorization pop-up window in the onNeedPrivacyAuthorization callback. After the user clicks to agree, the developer calls the callback interface resolve({ event: 'agree' }) of wx.onNeedPrivacyAuthorization, which will trigger the success callback of requirePrivacyAuthorize. If the user clicks to reject the authorization and the developer calls the callback interface resolve({ event: 'disagree' }) of wx.onNeedPrivacyAuthorization, the fail callback of requirePrivacyAuthorize will be triggered.
    • If the user has not authorized before and the developer has not registered the wx.onNeedPrivacyAuthorization() event listener, the unified privacy authorization pop-up window provided by the platform will pop up immediately. After the user clicks "Agree", the success callback of requirePrivacyAuthorize will be triggered. After the user clicks "Reject", the fail callback of requirePrivacyAuthorize will be triggered.
    • Based on the above features, developers can call the wx.requirePrivacyAuthorize interface to simulate the privacy interface call before calling any real privacy interface, and trigger the privacy pop-up window (including custom pop-up windows or platform pop-up windows) logic.
  • Is it necessary to call the wx.requirePrivacyAuthorize interface?
    • No, wx.requirePrivacyAuthorize is just an auxiliary interface that can be used according to actual conditions. When developers want to actively pop up a privacy pop-up window before calling the privacy interface, they can use this interface.

• Sample code:

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

onNeedPrivacyAuthorization

TIP

The API usage is as follows:wx.onNeedPrivacyAuthorization(function listener)

• Functional description: Listening to the privacy interface requires user authorization events. After the mini game registers the event listener, the custom privacy authorization pop-up window mode will be enabled, and the event will be triggered when the user needs to perform privacy authorization. When this event is triggered, the developer needs to pop up the privacy agreement description and call the callback interface resolve to trigger the original privacy interface to continue execution after the user agrees or refuses authorization.

• Parameters and descriptions: function listener, The privacy interface requires a listening function for the user authorization event.

• Callback parameters:

  • function resolve

    • resolve is the first callback parameter of onNeedPrivacyAuthorization and is an interface function.
    • When the onNeedPrivacyAuthorization event is triggered, the privacy interface that triggered the event will be in pending state.
    • If resolve({ event:'agree' }) is called, the original privacy interface that triggered the current onNeedPrivacyAuthorization event will continue to execute.
    • If resolve({ event: 'disagree' }) is called, the original privacy interface that triggered the current onNeedPrivacyAuthorization event will fail and return the error message API:fail privacy permission is not authorized.
    • Before calling resolve({ event: 'agree'/'disagree' }), developers can call resolve({ event: 'exposureAuthorization' }) to inform the platform of the privacy pop-up window exposure.

  • Object eventInfo

    eventInfo is the second callback parameter of onNeedPrivacyAuthorization, which indicates the associated information that triggered this onNeedPrivacyAuthorization event.

    Properties	Type	Description
    referrer	string	The name of the interface or component that triggered the onNeedPrivacyAuthorization event (for example: "getUserInfo")

  • resolve interface parameter:

    Properties	Type	Description
    event	string	user operation type

  • event legal value:

    event	Description
    exposureAuthorization	custom privacy pop-up window exposure
    agree	user agrees to privacy authorization
    disagree	user refuses privacy authorization

• Specific instructions:

  • when the mini game does not register the wx.onNeedPrivacyAuthorization event listener, the platform unified privacy pop-up window will be used by default.
  • After the mini game registers wx.onNeedPrivacyAuthorization, it will switch to the custom privacy pop-up window, and the developer needs to render the privacy pop-up window by himself.
  • When will the onNeedPrivacyAuthorization event be triggered?
    • When the privacy-related interface (such as wx.getUserInfo, wx.getClipboardData) is called, and the user has not agreed to the privacy agreement.
    • When the wx.requirePrivacyAuthorize interface is called to simulate the privacy interface call, and the user has not agreed to the privacy agreement.
    • If the user has agreed to the privacy agreement, the onNeedPrivacyAuthorization event will no longer be triggered.
  • When the onNeedPrivacyAuthorization event is triggered, the privacy interface that triggers the event will be in pending state and will continue to execute after waiting for user authorization. At this time, the developer needs to pop up a custom privacy pop-up window and call the callback interface resolve after the user clicks to agree/reject. The privacy interface that triggers the event will continue to execute.
  • The developer must call the resolve interface when the user generates a click operation
  • wx.onNeedPrivacyAuthorization is an overlay registration listener. If the listener is registered repeatedly, only the last registration will take effect.
  • Is it necessary to register the wx.onNeedPrivacyAuthorization listener and call resolve?
    • No, if you use the official pop-up window of the mini game and do not use a custom pop-up window, then wx.onNeedPrivacyAuthorization is not needed.
    • But if you register the wx.onNeedPrivacyAuthorization listener, you must call the resolve interface.

• Sample code:

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" });
});