对局状态
前言
对接本文功能时请严格按照说明和时序图指引进行对接，对接方式不正确可能会导致礼物面板唤起失败
1、平台对局与业务对局需要一一对应，禁止开启一场平台对局后，启动多场业务对局。
2、业务对局开始前必要严格判断startBattle接口返回的状态码，为0才进入业务对局，其它情况则为开局失败，并对主播进行相应提示。
4.1.1、介绍
对局是指弹幕玩法真正的战斗开始到结束的过程，过程中能支持唤醒对应弹幕礼物，让观众能使用弹幕礼物参与到互动中来。
对局阶段：
- 开始：弹幕玩法真正进入玩法对抗的开始节点（组队装备界面不算对局过程）；
- 心跳：玩法对抗过程中定时上报的心跳（注意心跳上报间隔为：2秒-3秒）；
- 结束：弹幕玩法对抗结束的节点（结算界面的展示不算对局过程）；
4.1.2、接入流程
4.1.2.1、时序图
4.1.3、接口
4.1.3.1、 查询主播对局状态接口
接口调用说明
http请求方式：POST
https://apiext.huya.com/interactive/queryBattleState
get参数
| 参数名称 | 类型 | 备注 |
|---|
| appId | string | 必填，开发者appId 如何查找 |
| extUuid | string | 必填，小程序id 如何查找 |
post参数，是用json格式提交
| 参数名称 | 类型 | 备注 |
|---|
| roomId | int | 必填，主播房间号 |
HTTP响应
| 参数名称 | 类型 | 备注 |
|---|
| code | int | 业务状态码 通用业务状态码说明 |
| msg | string | 响应描述 |
| response | string | json格式，响应数据 |
response数据说明
{
"battling" : 1, // 0: 不在对战状态 1: 正在对战中
"extUuid" : "abcdefg" // 主播当前对战中的小程序uuid
}
4.1.3.2、开始对局接口
接口调用说明
http请求方式：POST
https://apiext.huya.com/interactive/startBattle
注意：实现时必须严格判断，只有在状态码返回0的时候，业务才进入对局
get参数
| 参数名称 | 类型 | 备注 |
|---|
| appId | string | 必填，开发者appId 如何查找 |
| extUuid | string | 必填，小程序id 如何查找 |
post参数，是用json格式提交
| 参数名称 | 类型 | 备注 |
|---|
| battleId | string | 必填，对局ID，每场对局唯一，最长64位 |
| commandUuid | string | 选填，指令ID，在开发者中心配置后生成，对接互动指令面板时需传入 |
| gameMode | string | 选填，对局模式。业务自定义，标注本对局是什么类型的对局，比如：单人对局（single）、PK对局（1pk）等。 该字段会用于平台主播任务中区分不同对局类型 |
HTTP响应
4.1.3.3、对局心跳接口
接口调用说明
http请求方式：POST
https://apiext.huya.com/interactive/battleHeartbeat
注意：上报心跳的间隔为2秒-3秒
get参数
| 参数名称 | 类型 | 备注 |
|---|
| appId | string | 必填，开发者appId 如何查找 |
| extUuid | string | 必填，小程序id 如何查找 |
post参数，是用json格式提交
| 参数名称 | 类型 | 备注 |
|---|
| battleId | string | 必填，开局使用的对局ID |
HTTP响应
4.1.3.4、结束对局接口
接口调用说明
http请求方式：POST
https://apiext.huya.com/interactive/endBattle
注意：业务对局结束时调用
get参数
| 参数名称 | 类型 | 备注 |
|---|
| appId | string | 必填，开发者appId 如何查找 |
| extUuid | string | 必填，小程序id 如何查找 |
post参数，是用json格式提交
| 参数名称 | 类型 | 备注 |
|---|
| battleId | string | 必填，开局使用的对局ID |
HTTP响应
| 参数名称 | 类型 | 备注 |
|---|
| status | int | 业务状态码 通用业务状态码说明 |
| msg | string | 响应描述 |
4.1.4、通用业务状态码说明
| 参数名称 | 备注 |
|---|
| 0 | 成功 |
| 1 | 参数错误 |
| 2 | 调用失败 |
| 3 | 服务器异常 |
| 4 | 未登录 |
| 5 | 没有权限 |
| 6 | 操作对象不存在 |
| 7 | 重复操作 |
| 4001 | 已有其他进行中的对局 |
| 4002 | 对局已结束 |
4.1.5、接口鉴权
小程序API是为开发者提供的面向小程序应用场景的API，由开发者的小程序后台服务发起调用。小程序API的通信方式为HTTPS。
4.1.5.1、域名
正式环境域名：https://apiext.huya.com
4.1.5.2、生成签名
按照统一鉴权说明生成对应的鉴权sToken（即JWT token）
注意：其中Payload需要做以下调整：
payload参数：
| 参数名称 | 类型 | 备注 |
|---|
| iat | number | token生成时间戳（秒） |
| exp | number | 过期时间戳（秒） |
| appId | string | 开发者appid 如何查找 |
| extUuid | string | 小程序id 如何查找 |
| profileId | string | 主播unionId 如何获取 |
| roomId | string | 主播房间号 如何获取 |
payload样例
{
"iat": 1555921691,
"exp": 1555928891,
"appId": "appId",
"extUuid": "extUuid",
"profileId": "unImSOHlQBsY",
"roomId": "1134"
}
4.1.5.3、发送请求
- 通过https方式发送请求
- 上面生成的签名通过设置http Header参数authorization进行传输
| 参数名称 | 类型 | 备注 |
|---|
| authorization | string | 请求的签名凭证 |
