Login
login
This API is called using wx.login(Object object).
Feature description: This API needs to be jointly tested with the host client. The content return value on the device is provided by the host client, and can be customized. This API is currently not supported in the IDE, and you can mock the return value on the mock panel.
Parameter and description:Object object.
|
success | function | - | False | Callback function for successful API calls. |
fail | function | - | False | Callback function for failed API calls. |
complete | function | - | False | Callback function executed after API call ends (regardless of success or failure). |
Example:
wx.login({
success(res) {
console.log(res ,"---------------info, host app return");
}
})
checkSession
This API is called using wx.checkSession(Object object).
Notes:
This API is not supported in mini games.
Feature description: This API needs to be jointly tested with the host client. The content return value on the device is provided by the host client, and can be customized.
This API is currently not supported in the IDE, and you can mock the return value on the mock panel.
Checks if the login session has expired. The login session obtained through the wx.login API has a certain validity period. The longer the user does not use the mini game, the more likely the login session will expire. On the contrary, if the user continuously uses the mini game, the login session remains valid. The specific validity logic is maintained by the platform and is open to developers. Developers only need to call the wx.checkSession API to check whether the current login is valid.
If the login session expires, the developer can call wx.login again to obtain a new login session. A successful call indicates that the current session_key has not expired, while a failed call indicates that the session_key has expired.
Parameter and description:Object object.
|
success | function | - | False | Callback function for successful API calls. |
fail | function | - | False | Callback function for failed API calls. |
complete | function | - | False | Callback function executed after API call ends (regardless of success or failure). |
Example:
wx.checkSession({
success () {
},
fail () {
wx.login()
}
})
Account information
getAccountInfoSync
This API is called using Object wx.getAccountInfoSync().
Notes:
This API is not supported in mini games.
Feature description:Retrieves current account information. The online mini game version number can only be obtained in the released version, not the development version or the Preview.
Return value:Object. Account information.
|
miniProgram | Object | Mini game account information. |
miniProgram structural property
|
appId | string | Mini game appId. |
envVersion | string | Mini game version. Valid values: develop: The development version trial: The Preview release: The released version |
version | string | Online mini game version number. |
User information
getUserInfo
This API is called using wx.getUserInfo(Object object).
Feature description: This API is currently not supported in IDE and needs to be jointly tested with the host client. The content return value on the device is provided by the host client, and can be customized.
In the IDE, you can mock the return value on the mock panel.
To retrieve the user information, the user authorization for scope.userInfo. is required.
Parameter and description:Object object.
|
lang | string | en | False | The language used to display the user information. Valid values: en: English zh_CN: Simplified Chinese zh_TW: Traditional Chinese |
success | function | - | False | Callback function for successful API calls. |
fail | function | - | False | Callback function for failed API calls. |
complete | function | - | False | Callback function executed after API call ends (regardless of success or failure). |
object.success callback function parameter: Object res
|
userInfo | UserInfo | User information object. |
Example:
wx.getUserInfo({
success: function(res) {
var userInfo = res.userInfo
var nickName = userInfo.nickName
var avatarUrl = userInfo.avatarUrl
}
})
userInfo
Feature description:User information.
Parameter and description:
|
nickName | string | User’s nickname. |
avatarUrl | string | The URL of the user's profile photo. The last number in the URL represents the size of the square profile photo (options are 0, 46, 64, 96, 132; 0 represents a 640x640 square profile photo, 46 represents a 46x46 square profile photo, and so on. The default value is 132.) This field is left blank if the user has no profile photo. If the user changes the profile photo, the original profile photo URL will become invalid. |
gender | number | User's gender. No longer returned. Valid values are: 0: Unknown 1: Male 2: Female |
country | string | The user’s country. No longer returned. |
province | string | The user's province. No longer returned. |
city | string | The user's city. No longer returned. |
language | string | The language used to display the country, province, and city. Always returns "zh_CN". Valid values: en: English zh_CN: Simplified Chinese zh_TW: Traditional Chinese |
Settings
AuthSetting
Feature description:User’s authorization settings information.
Parameter and description:
|
boolean scope.userInfo | Whether the user has authorized access to their information. Corresponds to wx.getUserInfo. |
boolean scope.writePhotosAlbum | Whether the user has authorized saving images to their photo album. Corresponds to wx.saveImageToPhotosAlbum. |
boolean scope.userLocation | Whether the user has authorized access to their precise location. Corresponds to wx.getLocation. |
boolean scope.userFuzzyLocation | Whether the user has authorized access to their approximate location. Corresponds to wx.getFuzzyLocation. |
getSetting
This API is called using wx.getSetting(Object object).
Feature description:Gets the user's current settings. The return values will only include permissions that the mini game has previously requested from the user.
Parameter and description:Object object.
|
success | function | - | False | Callback function for successful API calls. |
fail | function | - | False | Callback function for failed API calls. |
complete | function | - | False | Callback function executed after API call ends (regardless of success or failure). |
object.success callback function parameter:Object res.
|
authSetting | | User authorization result. |
Example:
wx.getSetting({
success(res) {
console.log(res.authSetting)
}
})
openSetting
This API is called using wx.openSetting(Object object).
Feature description:This API opens the mini game settings page in the client, returning the user's settings operation results. After the user taps, they can navigate to the settings page to manage authorization information. Only the permissions that the mini game has requested from the user are shown on the settings page.
Parameter and description: Object object.
|
success | function | - | False | Callback function for successful API calls. |
fail | function | - | False | Callback function for failed API calls. |
complete | function | - | False | Callback function executed after API call ends (regardless of success or failure). |
object.success callback function parameter:Object res.
|
authSetting | AuthSetting | User authorization result. |
Example:
wx.openSetting({
success(res) {
console.log(res.authSetting)
}
})
Authorization
authorize
This API is called using wx.authorize(Object object).
Feature description:This API initiates an authorization request to the user in advance. After this API is called, a window will pop up, asking the user whether they agree to authorize the mini game to use a certain feature or access certain user data. However, the corresponding APIs are not actually called. If the user has previously agreed to the authorization, no pop-up window will appear and it will return success directly.
Parameter and description:Object object.
|
scope | string | - | True | Scope of the required permissions. For more information, see Scope list. |
success | function | - | False | Callback function for successful API calls. |
fail | function | - | False | Callback function for failed API calls. |
complete | function | - | False | Callback function executed after API call ends (regardless of success or failure). |
Example:
wx.getSetting({
success(res) {
if (!res.authSetting['scope.userLocation']) {
wx.authorize({
scope: 'scope.userLocation',
success() {
wx.getLocation()
}
})
}
}
})
Privacy information authorization
requirePrivacyAuthorize
This API is called using wx.requirePrivacyAuthorize(Object object).
Feature description: Simulates a privacy API call and triggers the privacy popup logic.
Parameter and description:Object object.
|
success | function | - | False | Callback function for successful API calls. |
fail | function | - | False | Callback function for failed API calls. |
complete | function | - | False | Callback function executed after API call ends (regardless of success or failure). |
Description:
1.1 When the wx.requirePrivacyAuthorize() is called:
If the user has previously allowed the privacy authorization, the success callback will be returned immediately, and the wx.onNeedPrivacyAuthorization event will not be triggered.
If the user has not provided authorization before and the developer has registered to listen for the wx.onNeedPrivacyAuthorization() event, the wx.onNeedPrivacyAuthorization event will be triggered immediately, and a custom privacy authorization pop-up window will appear in the onNeedPrivacyAuthorization callback. If the user agrees, the developer should call the resolve({ event: 'agree' }) callback, which will trigger the requirePrivacyAuthorize success callback. If the user disagrees, the developer should call the resolve({ event: 'disagree' }) callback, which will trigger the requirePrivacyAuthorize fail callback. If the user hasn't provided authorization before and the developer hasn't registered to listen for the wx.onNeedPrivacyAuthorization() event, the platform’s default privacy authorization pop-up window will immediately appear. If the user agrees, the requirePrivacyAuthorize success callback will be triggered. If the user disagrees, the requirePrivacyAuthorize fail callback will be triggered. The wx.requirePrivacyAuthorize is designed to help developers manage privacy authorization more effectively by simulating a privacy API call and triggering the appropriate authorization popup.
1.2 Is it required to call the wx.requirePrivacyAuthorize?
No. wx.requirePrivacyAuthorize is just an auxiliary API, and you can choose to call it as needed. It is useful when the developer wants to proactively display a privacy authorization popup before calling any real privacy-related API.
Example:
wx.requirePrivacyAuthorize({
success: () => {
},
fail: () => {},
complete: () => {}
})
onNeedPrivacyAuthorization
This API is called using wx.onNeedPrivacyAuthorization(function listener).
Feature description:Listens for the event where the privacy API requires user authorization. When a mini program registers this event listener, it enables a custom privacy authorization popup mode. When user authorization is needed, this event is triggered. The developer must display a privacy agreement explanation and call the resolve callback API after the user agrees or disagrees to the authorization to continue the execution of the original privacy API.
Parameter and description: function listenerThe listener for the privacy API authorization event.
Callback parameters:
function resolve
The resolve is an API function, which is the first callback parameter of the onNeedPrivacyAuthorization.
When the onNeedPrivacyAuthorization event is triggered, the privacy API that triggered the event will be in a pending state.
If resolve ({event: 'agree'}) is called, the original privacy API that triggered the current onNeedPrivacyAuthorization event will continue to execute.
If resolve ({event: 'disagree'}) is called, the original privacy API that triggered the current onNeedPrivacyAuthorization event will fail and return the error message “API:file privacy permission is not authorized”.
Before calling resolve ({event: 'agree'/'disagree' }), the developer can call resolve ({event: 'exposureAuthorization' }) to notify the platform that the privacy popup has been exposed.
Object eventInfo
The eventInfo is the second callback parameter of onNeedPrivacyAuthorization and represents the associated information that triggered this onNeedPrivacyAuthorization event.
|
referrer | string | The name of the API or component that triggered this onNeedPrivacyAuthorization event (e.g. “getUserInfo”). |
resolve API parameter:
|
event | string | The type of user operation. |
Valid values of event:
|
exposureAuthorization | Exposure of custom privacy pop-up window. |
agree | User agrees to privacy authorization. |
disagree | The user denies the privacy authorization. |
Description:
1. When the mini game does not register to listen for the wx.onNeedPrivacyAuthorization event, the platform's default privacy pop-up window will be used.
2. When the mini game registers to listen for the wx.onNeedPrivacyAuthorization event, a custom privacy pop-up window will be used, and the developer needs to render the privacy pop-up window.
3. When will the onNeedPrivacyAuthorization event be triggered?
When a privacy-related API (such as wx.getUserInfo and wx.getClipboardData) is called, and the user has not agreed to the privacy agreement.
When the wx.requirePrivacyAuthorize API is called to simulate a privacy API 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.
4. When the onNeedPrivacyAuthorization event is triggered, the privacy API that triggered the event will be in a pending state, waiting for user authorization to continue execution. At this point, the developer needs to use a custom privacy pop-up window and call the callback API resolve after the user has tapped Agree/Disagree to continue the execution of the privacy API.
5. Developers must call the resolve API in response to user tap actions.
6. The wx.onNeedPrivacyAuthorization allows multiple registrations, but only the last one takes effect.
7. Is it required to register wx.onNeedPrivacyAuthorization and to call resolve?
No, if you use the mini game’s default pop-up window rather than a custom pop-up window, wx.onNeedPrivacyAuthorization is not required.
However, if the wx.onNeedPrivacyAuthorization listener is registered, the resolve API must be called.
Example:
wx.onNeedPrivacyAuthorization((resolve, eventInfo) => {
console.log('The API that triggered this event is ' + eventInfo.referrer)
showCustomPopup()
resolve({ event: 'exposureAuthorization' })
resolve({ event: 'agree' })
resolve({ event: 'disagree' })
})
