tencent cloud

Open APIs
Last updated: 2025-04-29 18:40:52
Open APIs
Last updated: 2025-04-29 18:40:52

Login

login

This API is called using wx.login(Object object).
Feature description: This API needs to be jointly tested with the superapp. The content returned on a real device is provided by the superapp, and you can customize the returned content.
Parameter and description: Object object.
Property
Type
Default value
‍Required
Description
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).
Note:
This API is not supported in mini games.
Feature description: This API needs to be jointly tested with the superapp. The content returned on a real device is provided by the superapp, and you can customize the returned content.
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 SAS 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.
Property
Type
Default value
‍Required
Description
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 () {
// 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

This API is called using Object wx.getAccountInfoSync().
Note:
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.
Property
Type
Description
miniProgram
Object
Mini game account information.
miniProgram structural property
Structural property
Type
Description
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 superapp. The content returned on a real device is provided by the superapp, and you can customize the returned content.
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.
Property
Type
Default value
‍Required
Description
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
Property
Type
Description
userInfo
UserInfo
User information object.
Example:
// This must be called only after the user has granted authorization
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:
Property
Type
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 (0, 46, 64, 96, 132 are available to choose from. 0 represents a 640 × 640 profile photo, 46 represents a 46 × 46 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. This will no longer be returned. Valid values:
0: Unknown
1: Male
2: Female
country
string
The user’s country. This will no longer be returned.
province
string
The user's province. This will no longer be returned.
city
string
The user's city. This will no longer be returned.
language
string
The language used to display the country, province, and city. It will always return "zh_CN". Valid values are:
en: English
zh_CN: Simplified Chinese
zh_TW: Traditional Chinese

Settings

AuthSetting

Feature description: User’s authorization settings information.
Parameter and description:
Property
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.
Property
Type
Default value
‍Required
Description
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.
Property
Type
Description
authSetting
User authorization result.
Example:
wx.getSetting({
success(res) {
console.log(res.authSetting)
// res.authSetting = {
// "scope.userInfo": true,
// "scope.userLocation": true
// }
}
})

openSetting

This API is called using wx.openSetting(Object object).
Feature description: This API opens the mini game settings page in the superapp, 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.
Property
Type
Default value
‍Required
Description
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.
Property
Type
Description
authSetting
AuthSetting
User authorization result.
Example:
wx.openSetting({
success(res) {
console.log(res.authSetting)
// res.authSetting = {
// "scope.userInfo": true,
// "scope.userLocation": true
// }
}
})

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 calling it, a pop-up will immediately ask the user whether they agree to grant the mini game permission to use a specific feature or access certain user data, but it will not actually call the corresponding API. If the user has previously granted authorization, the pop-up will not appear, and it will directly return a success response.
Parameter and description: Object object.
Property
Type
Default value
‍Required
Description
scope
string
-
True
Scopes requiring authorization. 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:
// You can use wx.getSetting to check if the user has authorized the "scope.userLocation" scope
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.
Property
Type
Default value
‍Required
Description
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:
When calling wx.requirePrivacyAuthorize():
If the user has previously granted 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 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 authorized before and the developer hasn't registered to listen for the wx.onNeedPrivacyAuthorization() event listener, a unified privacy authorization pop-up provided by the superapp will appear immediately. If the user agrees, the success callback of requirePrivacyAuthorize will be triggered; if the user denies, the fail callback will be triggered.
Based on the above features, developers can call the wx.requirePrivacyAuthorize before invoking any real privacy APIs to simulate a privacy API call and trigger the privacy pop-up logic (including custom pop-ups or the superapp's unified privacy pop-up).
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. Developers can choose to use this API when they want to proactively display the privacy pop-up before calling a privacy API.
Example:
wx.requirePrivacyAuthorize({
success: () => {
// The user agrees to the authorization
// runGame() continues the game logic
},
fail: () => {}, // The user disagrees to the authorization
complete: () => {}
})

onNeedPrivacyAuthorization

This API is called using wx.onNeedPrivacyAuthorization(function listener).
Feature description:Listens for the event where user authorization is required for privacy APIs. 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 listener. The listener for the privacy API authorization event.
Callback parameters:
function resolve
resolve is the first callback parameter of onNeedPrivacyAuthorization and is an API function.
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 executing.
If resolve ({event: 'disagree'}) is called, the original privacy interface 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 superapp about the exposure of the privacy pop-up.
Object eventInfo
eventInfo is the second callback parameter of onNeedPrivacyAuthorization and represents the associated information that triggered this onNeedPrivacyAuthorization event.
Property
Type
Description
referrer
string
The name of the API or component that triggered this onNeedPrivacyAuthorization event (e.g. “getUserInfo”).
resolve API parameter:
Property
Type
Description
event
string
The type of user actions.
Valid values of event:
event
Description
exposureAuthorization
Exposure of custom privacy pop-up window.
agree
User agrees to privacy authorization.
disagree
The user denies the privacy authorization.
Description:
When a mini game has not registered the wx.onNeedPrivacyAuthorization event listener, it will default to using the superapp's unified privacy pop-up.
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.
When will the onNeedPrivacyAuthorization event be triggered?
When calling privacy-related APIs (such as wx.getUserInfo, wx.getClipboardData) and the user has not previously agreed to the privacy policy.
When calling the wx.requirePrivacyAuthorize API to simulate a privacy API call, and the user has not previously agreed to the privacy policy.
If the user has already agreed to the privacy policy, the onNeedPrivacyAuthorization event will not be triggered again.
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 executing. At this point, developers need to display a custom privacy pop-up and call the resolve callback after the user taps Agree/Deny for the triggering privacy API to continue executing.
Developers must call the resolve API in response to user tap actions.
The wx.onNeedPrivacyAuthorization is an overriding registration listener; if registered multiple times, only the last registration will take effect.
Is it required to register wx.onNeedPrivacyAuthorization listener 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 you register the wx.onNeedPrivacyAuthorization listener, you must call the resolve API.
Example:
wx.onNeedPrivacyAuthorization((resolve, eventInfo) => {
console.log('The API that triggered this event is ' + eventInfo.referrer)
// ------ Custom pop-up logic ------ //
showCustomPopup()
// -------After the pop-up, based on user actions, execute the following logic ------- //
// Developers display a custom privacy pop-up and call resolve to inform the superapp that the pop-up has been shown
resolve({ event: 'exposureAuthorization' })
// After the user taps Agree, the developer calls resolve to inform the superapp about the user’s authorization.
resolve({ event: 'agree' })
// After the user taps Deny, the developer calls resolve to inform the superapp that the user has denied the authorization.
resolve({ event: 'disagree' })
})

Message subscription

requestSubscribeMessage

This API is called using wx.requestSubscribeMessage(Object object).
Note:
Supported only on public cloud.
In a single authorization call, each tmplId corresponding to a template title must be unique; if duplicates are found, only one will be retained.
Feature description: This API triggers the subscription message page of the mini game in the superapp and returns the user's subscription message operation results.
Parameter and description: Object object.
Property
Type
‍Required
Description
tmplIds
Array<string>
True
Array of message template IDs to subscribe to. A maximum of 3 messages can be subscribed to in one call. Each tmplId must correspond to a unique template title, otherwise duplicates will be filtered out. The message template ID is configured under Mini game management - Message subscription.
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.
Property
Type
Description
errMsg
string
The value of errMsg is 'requestSubscribeMessage:ok' when the API is called successfully.
[TEMPLATE_ID: string]
string
[TEMPLATE_ID] is a dynamic key representing the template ID. The value can be 'accept', 'reject', 'ban', or 'filter'.
'accept': The user agreed to subscribe to the message corresponding to this template ID.
'reject': The user refused to subscribe to the message corresponding to this template ID.
'ban': The template has been banned by SAS.
'filter': The template was filtered out by SAS due to duplicate titles.
For example, { errMsg: "requestSubscribeMessage:ok", zun-LzcQyW-edafCVvzPkK4de2Rllr1fFpw2A_x0oXE: "accept"} indicates that the user has agreed to subscribe to the message zun-LzcQyW-edafCVvzPkK4de2Rllr1fFpw2A_x0oXE.
object.fail callback function parameter: Object res.
Property
Type
Description
errMsg
string
Error message when the API call fails.
errno
Number
Error code when the API call fails.
Error code
errCode
errMsg
Description
10001
TmplIds can't be empty
The tmplIds parameter is empty.
10002
Request list fail
Network error. Failed to request the message list.
10003
Request subscribe fail
Network error. Failed to send the subscription request.
20001
No template data return, verify the template id exist
No template data, usually because the template ID does not exist or does not match the template type.
20002
Templates type must be same
The template messages include both temporary and permanent types.
20003
Templates count out of max bounds
The number of template messages exceeds the limit.
20004
The main switch is switched off
The user has turned off the main switch, preventing subscriptions.
20005
This mini program was banned from subscribing messages
The mini program is banned from subscribing to messages.
20013
Reject DeviceMsg Template
Subscription to device messages using this API is not allowed.
Example:
wx.requestSubscribeMessage({
tmplIds: [''],
success: (res) => {
console.log('requestSubscribeMessage===success', res)
res === {
errMsg: "requestSubscribeMessage:ok",
"zun-LzcQyW-edafCVvzPkK4de2Rllr1fFpw2A_x0oXE": "accept"
}
}
})



Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No

Feedback