tencent cloud

开放接口
最后更新时间:2025-04-29 18:40:53
开放接口
最后更新时间: 2025-04-29 18:40:53

登录

login

该 API 使用方法为 wx.login(Object object)
功能说明:该 API 需要和 superapp 联调,在真机上返回的内容是由 superapp 提供,可以自定义返回内容。
参数及说明:Object object。
属性
类型
默认值
必填
说明
success
function
-
接口调用成功的回调函数
fail
function
-
接口调用失败的回调函数
complete
function
-
接口调用结束的回调函数(调用成功、失败都会执行)
示例代码:
wx.login({
success(res) {
console.log(res ,"---------------info, host app return");
}
})

checkSession

该 API 使用方法为 wx.checkSession(Object object)
说明:
该API 小游戏暂未支持。
功能说明:该 API 需要和 superapp 联调,在真机上返回的内容是由 superapp 提供,可以自定义返回内容。
检查登录态是否过期。通过 wx.login 接口获得的用户登录态拥有一定的时效性。用户越久未使用小游戏,用户登录态越有可能失效。反之如果用户一直在使用小游戏,则用户登录态一直保持有效。具体时效逻辑由官方维护,对开发者透明。开发者只需要调用 wx.checkSession 接口检测当前用户登录态是否有效。
登录态过期后开发者可以再调用 wx.login 获取新的用户登录态。调用成功说明当前 session_key 未过期,调用失败说明 session_key 已过期。
参数及说明:Object object。
属性
类型
默认值
必填
说明
success
function
-
接口调用成功的回调函数
fail
function
-
接口调用失败的回调函数
complete
function
-
接口调用结束的回调函数(调用成功、失败都会执行)
示例代码:
wx.checkSession({
success () {
//session_key 未过期,并且在本生命周期一直有效
},
fail () {
// session_key 已经失效,需要重新执行登录流程
wx.login() //重新登录
}
})

账号信息

getAccountInfoSync

该 API 使用方法为 Object wx.getAccountInfoSync()
说明:
该 API 小游戏暂未支持。
功能说明:获取当前账号信息。线上小游戏版本号仅支持在正式版小游戏中获取,开发版和体验版中无法获取。
返回值:Object,账号信息。
属性
类型
说明
miniProgram
Object
小游戏账号信息
miniProgram 结构属性
结构属性
类型
说明
appId
string
小游戏 appid
envVersion
string
小游戏版本,合法值为:
develop:开发版
trial:体验版
release:正式版
version
string
线上小游戏版本号

用户信息

getUserInfo

该 API 使用方法为 wx.getUserInfo(Object object)
功能说明:IDE 目前暂不支持,该 API 需要和 superapp 联调,在真机上返回的内容是由 superapp 提供,可以自定义返回内容
在 IDE 中可以使用 mock 面板进行返回值的 mock。
获取用户信息,在使用过程中需要用户授权 scope.userInfo。
参数及说明:Object object。
属性
类型
默认值
必填
说明
lang
string
en
显示用户信息的语言,合法值为:
en:英文
zh_CN:简体中文
zh_TW:繁体中文
success
function
-
接口调用成功的回调函数
fail
function
-
接口调用失败的回调函数
complete
function
-
接口调用结束的回调函数(调用成功、失败都会执行)
object.success 回调函数参数:Object res
属性
类型
说明
userInfo
UserInfo
用户信息对象
示例代码:
// 必须是在用户已经授权的情况下调用
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_CN”,合法值为:
en:英文
zh_CN:简体中文
zh_TW:繁体中文

设置

AuthSetting

功能说明:用户授权设置信息。
参数及说明:
属性
说明
boolean scope.userInfo
是否授权用户信息,对应接口 wx.getUserInfo
boolean scope.writePhotosAlbum
是否授权保存到相册 wx.saveImageToPhotosAlbum
boolean scope.userLocation
是否授权精确地理位置,对应接口 wx.getLocation
boolean scope.userFuzzyLocation
是否授权模糊地理位置,对应接口 wx.getFuzzyLocation

getSetting

该 API 使用方法为 wx.getSetting(Object object)
功能说明:获取用户的当前设置,返回值中只会出现小游戏已经向用户请求过的权限。
参数及说明:Object object。
属性
类型
默认值
必填
说明
success
function
-
接口调用成功的回调函数
fail
function
-
接口调用失败的回调函数
complete
function
-
接口调用结束的回调函数(调用成功、失败都会执行)
object.success 回调函数参数:Object res。
属性
类型
说明
authSetting
用户授权结果
示例代码:
wx.getSetting({
success(res) {
console.log(res.authSetting)
// res.authSetting = {
// "scope.userInfo": true,
// "scope.userLocation": true
// }
}
})

openSetting

该 API 使用方法为 wx.openSetting(Object object)
功能说明:调起 superapp 小游戏设置界面,返回用户设置的操作结果,用户发生单击行为后,可以跳转打开设置页,管理授权信息。设置界面只会出现小游戏已经向用户请求过的权限。
参数及说明: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

该 API 使用方法为 wx.authorize(Object object)
功能说明:提前向用户发起授权请求。调用后会立刻弹窗询问用户是否同意授权小游戏使用某项功能或获取用户的某些数据,但不会实际调用对应接口。如果用户之前已经同意授权,则不会出现弹窗,直接返回成功。
参数及说明:Object object。
属性
类型
默认值
必填
说明
scope
string
-
需要获取权限的 scope ,详情请参见 scope
success
function
-
接口调用成功的回调函数
fail
function
-
接口调用失败的回调函数
complete
function
-
接口调用结束的回调函数(调用成功、失败都会执行)
示例代码:
// 可以通过 wx.getSetting 先查询一下用户是否授权了 "scope.userLocation" 这个 scope
wx.getSetting({
success(res) {
if (!res.authSetting['scope.userLocation']) {
wx.authorize({
scope: 'scope.userLocation',
success() {
wx.getLocation()
}
})
}
}
})

隐私信息授权

requirePrivacyAuthorize

该 API 使用方法为 wx.requirePrivacyAuthorize(Object object)
功能说明:模拟隐私接口调用,并触发隐私弹窗逻辑。
参数及说明:Object object。
属性
类型
默认值
必填
说明
success
function
-
接口调用成功的回调函数
fail
function
-
接口调用失败的回调函数
complete
function
-
接口调用结束的回调函数(调用成功、失败都会执行)
具体说明:
调用 wx.requirePrivacyAuthorize() 时:
如果用户之前已经同意过隐私授权,会立即返回 success 回调,不会触发 wx.onNeedPrivacyAuthorization 事件。
如果用户之前没有授权过,并且开发者注册了 wx.onNeedPrivacyAuthorization() 事件监听,就会立即触发 wx.onNeedPrivacyAuthorization 事件,然后开发者在 onNeedPrivacyAuthorization 回调中弹出自定义隐私授权弹窗,用户点了同意后开发者调用 wx.onNeedPrivacyAuthorization 的回调接口 resolve({ event: 'agree' }),会触发 requirePrivacyAuthorize 的 success 回调。用户点击拒绝授权后开发者调用 wx.onNeedPrivacyAuthorization 的回调接口 resolve({ event: 'disagree' }) 的话,会触发 requirePrivacyAuthorize 的 fail 回调。
如果用户之前没有授权过,并且开发者没有注册 wx.onNeedPrivacyAuthorization() 事件监听,就会立即弹出由 superapp 提供的统一隐私授权弹窗,用户点了同意之后,会触发 requirePrivacyAuthorize 的 success 回调,用户点了拒绝后会触发 requirePrivacyAuthorize 的 fail 回调。
基于上述特性,开发者可以在调用任何真实隐私接口之前调用 wx.requirePrivacyAuthorize 接口来模拟隐私接口调用,并触发隐私弹窗(包括自定义弹窗或 superapp 统一隐私弹窗)逻辑。
一定要调用 wx.requirePrivacyAuthorize 接口吗?
不是,wx.requirePrivacyAuthorize 只是一个辅助接口,可以根据实际情况选择使用。当开发者希望在调用隐私接口之前就主动弹出隐私弹窗时,就可以使用这个接口。
示例代码:
wx.requirePrivacyAuthorize({
success: () => {
// 用户同意授权
// runGame() 继续游戏逻辑
},
fail: () => {}, // 用户拒绝授权
complete: () => {}
})

onNeedPrivacyAuthorization

该 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' }) 把隐私弹窗曝光告知 superapp。
Object eventInfo
eventInfo 是 onNeedPrivacyAuthorization 的第二个回调参数,表示触发本次 onNeedPrivacyAuthorization 事件的关联信息。
属性
类型
说明
referrer
string
触发本次 onNeedPrivacyAuthorization 事件的接口或组件名(例如:"getUserInfo")
resolve 接口参数:
属性
类型
说明
event
string
用户操作类型
event 合法值:
event
说明
exposureAuthorization
自定义隐私弹窗曝光
agree
用户同意隐私授权
disagree
用户拒绝隐私授权
具体说明:
小游戏未注册 wx.onNeedPrivacyAuthorization 事件监听时,会默认使用 superapp 统一隐私弹窗。
小游戏注册 wx.onNeedPrivacyAuthorization 后,会切换至自定义隐私弹窗,此时需要开发者自行渲染隐私弹窗。
什么时候会触发 onNeedPrivacyAuthorization 事件?
调用隐私相关接口(比如 wx.getUserInfo、wx.getClipboardData),并且用户还未同意过隐私协议时。
调用 wx.requirePrivacyAuthorize 接口来模拟隐私接口调用,并且用户还未同意过隐私协议时。
如果用户已经同意过隐私协议,则不会再触发 onNeedPrivacyAuthorization 事件。
当触发 onNeedPrivacyAuthorization 事件时,触发该事件的隐私接口会处于 pending 状态,等待用户授权后才会继续执行,此时开发者需要弹出自定义隐私弹窗,并在用户点击同意/拒绝后调用回调接口 resolve,触发该事件的隐私接口才会继续执行。
开发者必须在用户产生点击操作时调用 resolve 接口
wx.onNeedPrivacyAuthorization 是覆盖式注册监听,若重复注册监听,则只有最后一次注册会生效。
一定要注册 wx.onNeedPrivacyAuthorization 监听以及调用 resolve 吗?
不是的,如果使用小游戏官方弹窗,不使用自定义弹窗,那就不需要 wx.onNeedPrivacyAuthorization。
但如果注册了 wx.onNeedPrivacyAuthorization 监听,则一定要调用 resolve 接口。
示例代码:
wx.onNeedPrivacyAuthorization((resolve, eventInfo) => {
console.log('触发本次事件的接口是:' + eventInfo.referrer)
// ------ 自定义弹窗逻辑 ------ //
showCustomPopup()
// -------弹窗后根据用户操作,进行以下逻辑逻辑 ------- //
// 开发者弹出自定义的隐私弹窗,并调用 resolve 告知 superapp 已经弹窗
resolve({ event: 'exposureAuthorization' })
// 用户点击同意后,开发者调用 resolve 告知 superapp 用户已经同意
resolve({ event: 'agree' })
// 用户点击拒绝后,开发者调用 resolve 告知 superapp 用户已经拒绝
resolve({ event: 'disagree' })
})

订阅消息

requestSubscribeMessage

该 API 使用方法为 wx.requestSubscribeMessage(Object object)
注意:
仅公有云支持。
一次授权调用里,每个 tmplId 对应的模板标题不能存在相同的,若出现相同的,只保留一个。
功能说明:调起 superapp 小游戏订阅消息界面,返回用户订阅消息的操作结果。
参数及说明:Object object。
属性
类型
必填
说明
tmplIds
Array<string>
需要订阅的消息模板的 id 的集合,一次调用最多可订阅 3 条消息。每个 tmplId 对应的模板标题需要不相同,否则会被过滤。消息模版 id 在 小游戏管理-订阅消息 中进行配置。
success
function
接口调用成功的回调函数
fail
function
接口调用失败的回调函数
complete
function
接口调用结束的回调函数(调用成功、失败都会执行)
object.success 回调函数参数:Object res。
属性
类型
说明
errMsg
string
接口调用成功时 errMsg 值为 "requestSubscribeMessage:ok"
[TEMPLATE_ID: string]
string
[TEMPLATE_ID] 是动态的键,即模板 id,值包括 'accept'、'reject'、'ban'、'filter'。
'accept' 表示用户同意订阅该条 id 对应的模板消息。
'reject' 表示用户拒绝订阅该条 id 对应的模板消息。
'ban' 表示已被 SAS 封禁。
'filter' 表示该模板因为模板标题同名被 SAS 过滤。
例如 { errMsg: "requestSubscribeMessage:ok", zun-LzcQyW-edafCVvzPkK4de2Rllr1fFpw2A_x0oXE: "accept"} 表示用户同意订阅 zun-LzcQyW-edafCVvzPkK4de2Rllr1fFpw2A_x0oXE 这条消息
object.fail 回调函数参数:Object res。
属性
类型
说明
errMsg
string
接口调用失败错误信息
errno
Number
接口调用失败错误码
错误码
errCode
errMsg
说明
10001
TmplIds can't be empty
参数传空了
10002
Request list fail
网络问题,请求消息列表失败
10003
Request subscribe fail
网络问题,订阅请求发送失败
20001
No template data return, verify the template id exist
没有模板数据,一般是模板 ID 不存在或者和模板类型不对应导致的
20002
Templates type must be same
模板消息类型 既有一次性的又有永久的
20003
Templates count out of max bounds
模板消息数量超过上限
20004
The main switch is switched off
用户关闭了主开关,无法进行订阅
20005
This mini program was banned from subscribing messages
小程序被禁封
20013
Reject DeviceMsg Template
不允许通过该接口订阅设备消息
示例代码:
wx.requestSubscribeMessage({
tmplIds: [''],
success: (res) => {
console.log('requestSubscribeMessage===success', res)
res === {
errMsg: "requestSubscribeMessage:ok",
"zun-LzcQyW-edafCVvzPkK4de2Rllr1fFpw2A_x0oXE": "accept"
}
}
})


本页内容是否解决了您的问题?
您也可以 联系销售 提交工单 以寻求帮助。

文档反馈