虎牙小游戏 - JS API
功能接口
登录
hy.login(Object object)
调用接口获取登录凭证（code），通过凭证进而换取用户登录态信息。
虎牙小游戏登录流程
参数
请求参数
参数类型：object
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| timeout | number | 否 | 超时时间，默认为 0 |
| success | function | 否 | 接口调用成功的回调函数 |
| fail | function | 否 | 接口调用失败的回调函数 |
| complete | function | 否 | 接口调用结束的回调函数（调用成功、失败都会执行） |
success 回调函数参数
参数类型：object
| 参数 | 类型 | 说明 |
|---|---|---|
| code | string | 临时登录凭证 |
fail 回调函数参数
参数类型：object
| 参数 | 类型 | 说明 |
|---|---|---|
| errMsg | string | 错误信息 |
示例
hy.login({
success(res) {
if(res.code) {
console.log('code:' res.code)
}
},
fail(res) {
console.log('未登录或登录失效！' + res.errMsg)
}
})
检查登录态
hy.checkSession(Object object)
检查登录态是否过期。
参数
请求参数
参数类型：object
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| success | function | 否 | 接口调用成功的回调函数 |
| fail | function | 否 | 接口调用失败的回调函数 |
| complete | function | 否 | 接口调用结束的回调函数（调用成功、失败都会执行） |
示例
hy.checkSession({
success() {
// 未过期
},
fail() {
// 已过期
}
})
获取用户信息
hy.getUserInfo(Object object)
获取用户昵称和头像
参数
请求参数
参数类型：object
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| success | function | 否 | 接口调用成功的回调函数 |
| fail | function | 否 | 接口调用失败的回调函数 |
| complete | function | 否 | 接口调用结束的回调函数（调用成功、失败都会执行） |
success 回调函数参数
参数类型：object
| 参数 | 类型 | 说明 |
|---|---|---|
| nickName | string | 用户昵称 |
| userAvatarUrl | string | 用户头像地址 |
| userLevel | number | 用户等级 |
| userUnionId | string | 用户的unionId |
示例
hy.getUserInfo({
success(res) {
console.log('用户昵称', res.nickName)
},
fail(res) {
console.log(res.errMsg)
}
})
获取主播信息
hy.getStreamerInfo(Object object)
获取主播昵称和头像
参数
请求参数
参数类型：object
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| success | function | 否 | 接口调用成功的回调函数 |
| fail | function | 否 | 接口调用失败的回调函数 |
| complete | function | 否 | 接口调用结束的回调函数（调用成功、失败都会执行） |
success 回调函数参数
参数类型：object
| 参数 | 类型 | 说明 |
|---|---|---|
| streamerNick | string | 主播昵称 |
| streamerAvatarUrl | string | 主播头像地址 |
| streamerSex | number | 主播性别；取值说明: 1 表示男; 2 表示女 |
| streamerLevel | number | 主播等级 |
| streamerRoomId | number | 房间Id |
| streamerUnionId | string | 主播unionId，没有则为空 |
示例
hy.getStreamerInfo({
success(res) {
console.log('主播昵称', res.userNick)
},
fail(res) {
console.log(res.errMsg)
}
})
支付
hy.requestPayment(Object object)
支付有可能存在延迟到账问题，建议游戏在收到回调后，向游戏服务端轮询发货结果，间隔 3 秒，持续约 1 ～ 2 分钟。 同时也存在一些异常情况，导致充值成功后结果回调失败，因此建议游戏在启用游戏时主动查询余额，并且提供给用户主动刷新的功能。
参数
请求参数
参数类型：object
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| timeStamp | number | 是 | 时间戳 |
| nonceStr | string | 是 | 随机字符串，长度为32个字符以下 |
| package | string | 是 | 下单接口返回 |
| signType | string | 是 | 签名算法类型，默认值：'MD5' |
| paySign | string | 是 | 签名 - 签名需使用开发者密钥，为了密钥安全，建议在请求服务端预下单时，由服务端返回相关的请求参数，具体签名规则请查看服务端接入文档 |
| success | function | 否 | 接口调用成功的回调函数 |
| fail | function | 否 | 接口调用失败的回调函数 |
| complete | function | 否 | 接口调用结束的回调函数（调用成功、失败都会执行） |
示例
hy.requestPayment({
timeStamp: '',
package: '',
nonceStr: '',
signType: 'MD5',
paySign: '',
success() {
// 调用成功
},
fail(res) {
// 调用失败
console.log(res.errMsg)
}
});
发起网络请求
hy.request(Object object)
发起网络请求，底层基于 window.fetch 实现，因此服务端接口需要支持跨域请求。
小游戏前端域名：*.vip.hyext.com
参数
请求参数
参数类型：object
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| url | string | 是 | 请求地址 |
| method | 'GET'|'POST'|'PUT'|'DELETE'|'HEAD'|'OPTIONS'|'PATCH' | 否 | 请求方法 |
| headers | object | 否 | 请求头 |
| data | string/Object/Arraybuffer | 否 | 请求的参数 |
| timeout | number | 否 | 超时时间，单位为毫秒。默认值为 60000 |
| mode | "cors"|"navigate"|"no-cors"|"same-origin" | 否 | 请求模式 |
| credentials | "include"|"omit"|"same-origin" | 否 | 凭证 |
| cache | "default"|"force-cache"|"no-cache"|"no-store"|"only-if-cached"|"reload" | 否 | 缓存模式 |
| referrer | string | 否 | 请求来源 |
| referrerPolicy | ""|"no-referrer"|"no-referrer-when-downgrade"|"origin"|"origin-when-cross-origin"|"same-origin"|"strict-origin"|"strict-origin-when-cross-origin"|"unsafe-url" | 否 | 请求来源策略 |
| keepalive | boolean | 否 | 保持连接 |
| success | function | 否 | 接口调用成功的回调函数 |
| fail | function | 否 | 接口调用失败的回调函数 |
| complete | function | 否 | 接口调用结束的回调函数（调用成功、失败都会执行） |
success 回调函数参数
参数类型：object
| 参数 | 类型 | 说明 |
|---|---|---|
| data | string/Object/Arraybuffer | 开发者服务器返回的数据 |
| statusCode | number | 开发者服务器返回的 HTTP 状态码 |
| header | Object | 开发者服务器返回的 HTTP Response Header |
fail 回调函数参数
参数类型：object
| 参数 | 类型 | 说明 |
|---|---|---|
| errMsg | string | 错误信息 |
| errCode | number | 错误码：1-请求失败，2-请求超时 |
示例
hy.request({
url: 'https://example.com/api',
data: {
id: 123
},
header: {
'content-type': 'application/json' // 默认值
},
success(res) {
console.log(res.data)
},
fail(res) {
console.log(res.errMsg)
}
})
获取窗口信息
hy.getWindowInfo()
获取窗口信息
返回值
返回值类型：object
| 参数 | 类型 | 说明 |
|---|---|---|
| screenWidth | number | 屏幕宽度 |
| screenHeight | number | 屏幕高度 |
| isLandscape | boolean | 屏幕是否是横屏 |
| windowWidth | number | 可使用窗口宽度，单位 px |
| windowHeight | number | 可使用窗口高度，单位 px |
| pixelRatio | number | 设备像素比 |
| statusBarHeight | number | 状态栏的高度，单位 px |
| screenTop | number | 窗口上边缘的 y 值 |
| safeArea | object | 在竖屏正方向下的安全区域。部分机型没有安全区域概念，则不返回 safeArea 字段 |
| safeArea.left | number | 安全区域左上角横坐标 |
| safeArea.right | number | 安全区域右下角横坐标 |
| safeArea.top | number | 安全区域左上角纵坐标 |
| safeArea.bottom | number | 安全区域右下角纵坐标 |
| safeArea.width | number | 安全区域的宽度，单位逻辑像素 |
| safeArea.height | number | 安全区域的高度，单位逻辑像素 |
示例
const windowInfo = hy.getWindowInfo();
console.log('屏幕宽度:', windowInfo.screenWidth);
获取系统信息（deprecated）
hy.getSystemInfoAsync(Object object)
获取系统信息（已抛弃），请使用hy.getSystemInfo接口。
参数
请求参数
参数类型：object
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| success | function | 否 | 接口调用成功的回调函数 |
| fail | function | 否 | 接口调用失败的回调函数 |
| complete | function | 否 | 接口调用结束的回调函数（调用成功、失败都会执行） |
success 回调函数参数
参数类型：object
| 参数 | 类型 | 说明 |
|---|---|---|
| platform | string | 示例："android"，"ios" |
| version | string | 虎牙直播app版本 |
| baseVersion | string | 虎牙直播app基础包版本 |
| screenWidth | number | 屏幕宽度 |
| screenHeight | number | 屏幕高度 |
| isLandscape | boolean | 屏幕是否是横屏 |
| windowWidth | number | 可使用窗口宽度，单位 px |
| windowHeight | number | 可使用窗口高度，单位 px |
| pixelRatio | number | 设备像素比 |
| statusBarHeight | number | 状态栏的高度，单位 px |
| screenTop | number | 窗口上边缘的 y 值 |
| safeArea | object | 在竖屏正方向下的安全区域。部分机型没有安全区域概念，则不返回 safeArea 字段 |
| safeArea.left | number | 安全区域左上角横坐标 |
| safeArea.right | number | 安全区域右下角横坐标 |
| safeArea.top | number | 安全区域左上角纵坐标 |
| safeArea.bottom | number | 安全区域右下角纵坐标 |
| safeArea.width | number | 安全区域的宽度，单位逻辑像素 |
| safeArea.height | number | 安全区域的高度，单位逻辑像素 |
示例
hy.getSystemInfoAsync({
success(res) {
console.log(res.screenWidth)
}
})
获取系统信息
hy.getSystemInfo(Object object)
获取系统信息。
参数
请求参数
参数类型：object
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| success | function | 否 | 接口调用成功的回调函数 |
| fail | function | 否 | 接口调用失败的回调函数 |
| complete | function | 否 | 接口调用结束的回调函数（调用成功、失败都会执行） |
success 回调函数参数
参数类型：object
| 字段 | 类型 | 说明 |
|---|---|---|
brand | string | 设备品牌 |
model | string | 设备型号 |
pixelRatio | number | 设备像素比 |
screenWidth | number | 屏幕宽度，单位px |
screenHeight | number | 屏幕高度，单位px |
windowWidth | number | 可使用窗口宽度，单位px |
windowHeight | number | 可使用窗口高度，单位px |
statusBarHeight | number | 状态栏的高度，单位px |
language | string | 设置的语言 |
version | string | 虎牙版本号 |
system | string | 操作系统及版本 |
platform | string | 客户端平台枚举 |
fontSizeSetting | number | 用户字体大小（单位px） |
SDKVersion | string | 客户端基础库版本 |
safeArea | Object | 在竖屏正方向下的安全区域。部分机型没有安全区域概念，也不会返回 safeArea 字段，开发者需自行兼容。 |
deviceOrientation | string | 设备方向 |
host | Object | 当前小程序运行的宿主环境 |
其中客户端平台枚举的取值范围为
| 值 | 说明 |
|---|---|
ios | iOS，iPadOS |
android | Android |
ohos | HarmonyOS |
windows | Windows |
mac | macOS |
其中safeArea数据结构为：
| 参数 | 类型 | 说明 |
|---|---|---|
| left | number | 安全区域左上角横坐标 |
| right | number | 安全区域右下角横坐标 |
| top | number | 安全区域左上角纵坐标 |
| bottom | number | 安全区域右下角纵坐标 |
| width | number | 安全区域的宽度，单位逻辑像素 |
| height | number | 安全区域的高度，单位逻辑像素 |
其中deviceOrientation数据结构为：
| 参数 | 类型 | 说明 |
|---|---|---|
| portrait | string | 竖屏 |
| landscape | string | 横屏 |
其中host数据结构为：
| 参数 | 类型 | 说明 |
|---|---|---|
| appId | string | 虎牙小程序id |
示例
hy.getSystemInfo({
success(res) {
console.log(res.screenWidth)
}
})
同步获取冷启动时的参数
hy.getLaunchOptionsSync()
参数
请求参数
参数类型：object
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| success | function | 否 | 接口调用成功的回调函数 |
| fail | function | 否 | 接口调用失败的回调函数 |
| complete | function | 否 | 接口调用结束的回调函数（调用成功、失败都会执行） |
success 回调函数参数
| 字段 | 类型 | 说明 |
|---|---|---|
scene | number | 启动小游戏的场景值 |
query | Map | 启动小游戏的 query 参数 |
referrerInfo | Object | 来源信息。从另一个小程序 或 App 进入小程序时返回。否则返回 {}。 |
其中scene的数据结构为：
| 字段 | 类型 | 说明 |
|---|---|---|
1000 | number | 其他 |
其中referrerInfo的数据结构为：
| 字段 | 类型 | 说明 |
|---|---|---|
appId | number | 来源小程序或 App 的 appId |
extraData | Map | 来源小程序传过来的数据 |
示例
const res = hy.getLaunchOptionsSync()
获取网络类型
hy.getNetworkType(Object object)
参数
请求参数
参数类型：object
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| success | function | 否 | 接口调用成功的回调函数 |
| fail | function | 否 | 接口调用失败的回调函数 |
| complete | function | 否 | 接口调用结束的回调函数（调用成功、失败都会执行） |
success 回调函数参数
| 字段 | 类型 | 说明 |
|---|---|---|
networkType | string | 网络类型枚举 |
hasSystemProxy | boolean | 设备是否使用了网络代理 |
其中的networkType取值范围为
| 值 | 说明 |
|---|---|
wifi | wifi 网络 |
2g | 2g 网络 |
3g | 3g 网络 |
4g | 4g 网络 |
5g | 5g 网络 |
unknown | Android 下不常见的网络类型 |
none | 无网络 |
示例
const res = hy.getNetworkType({
success(rsp) {
console.log(rsp.networkType)
}
})
将数据存储在本地缓存指定的 key 中。
会覆盖掉原来该 key 对应的内容.
hy.setStorage(Object object)
请求参数
参数类型：object
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| success | function | 否 | 接口调用成功的回调函数 |
| fail | function | 否 | 接口调用失败的回调函数 |
| complete | function | 否 | 接口调用结束的回调函数（调用成功、失败都会执行） |
key | string | 本地缓存中指定的 key | |
data | any | 需要存储的内容。只支持原生类型、Date、及能够通过JSON.stringify序列化的对象 | |
encrypt | boolean | 是否开启加密存储，默认为false |
success 回调函数参数
无
示例
hy.setStorage({
key: 'foo',
data: '1',
success() {
console.log('设置缓存功')
}
})
从本地缓存中异步获取指定 key 的内容
hy.getStorage(Object object)
请求参数
参数类型：object
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| success | function | 否 | 接口调用成功的回调函数 |
| fail | function | 否 | 接口调用失败的回调函数 |
| complete | function | 否 | 接口调用结束的回调函数（调用成功、失败都会执行） |
key | string | 本地缓存中指定的 key | |
encrypt | boolean | 是否开启加密存储，默认为false |
success 回调函数参数
| 字段 | 类型 | 说明 |
|---|---|---|
data | any | key对应的内容 |
示例
hy.getStorage({
key: 'foo',
success(rsp) {
console.log(rsp.data)
}
})
从本地缓存中移除指定 key
hy.removeStorage(Object object)
请求参数
参数类型：object
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| success | function | 否 | 接口调用成功的回调函数 |
| fail | function | 否 | 接口调用失败的回调函数 |
| complete | function | 否 | 接口调用结束的回调函数（调用成功、失败都会执行） |
key | string | 本地缓存中指定的 key |
success 回调函数参数
无
示例
hy.removeStorage({
key: 'foo',
success() {
console.log('删除缓存成功')
}
})
清理本地所有数据缓存
hy.clearStorage(Object object)
参数
请求参数
参数类型：object
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| success | function | 否 | 接口调用成功的回调函数 |
| fail | function | 否 | 接口调用失败的回调函数 |
| complete | function | 否 | 接口调用结束的回调函数（调用成功、失败都会执行） |
success 回调函数参数
无
示例
hy.clearStorage()
异步获取当前storage的相关信息
hy.getStorageInfo(Object object)
请求参数
参数类型：object
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| success | function | 否 | 接口调用成功的回调函数 |
| fail | function | 否 | 接口调用失败的回调函数 |
| complete | function | 否 | 接口调用结束的回调函数（调用成功、失败都会执行） |
success 回调函数参数
| 字段 | 类型 | 说明 |
|---|---|---|
keys | Array.<string> | 当前 storage 中所有的 key |
currentSize | number | 当前占用的空间大小, 单位 KB |
limitSize | number | 限制的空间大小，单位 KB |
示例
hy.getStorageInfo({
success(rsp) {
console.log(rsp.keys)
}
})
联运运营接口
以下接口为虎牙小游戏联运接口，接口入参请根据游戏实际存在的字段值提供
开始游戏
hy.startGame()
开始游戏的上报时机可以厂商自行决定，建议进入区服或者开始游戏进度时上报，虎牙侧会在厂商上报该事件之后统计游戏时长。 上架联运游戏必须接入hy.statrGame接口。
参数
请求参数
无
示例
hy.startGame();