文档版本:20220218-100
变更历史:
API版本 | 发版日期 | 更新内容 |
---|---|---|
V1.0 | 2022/2/18 | 首次发版 |
1 简介
本文阅读对象:接入方集成海马云游戏服务系统涉及的开发、测试及运维等相关人员,以下统一称为“接入方”。
海马云游戏服务在游戏开始、游戏切换分辨率、游戏结束时,会通过回调接口将相关信息主动通知给接入方。在本接口中,海马云游戏服务为主动发起方,接入方为被动接收方,报文采用明文方式进行传输。若需使用本接口,接入方需:
- 提前准备一个能接受post请求的服务接口。
- 将服务的URL地址提供给海马云游戏。
- 保证所提供服务的可用性、稳定性和约定的服务能力。
⚠注意:
接入方收到海马云回调通知报文后,应先进行日志记录,再根据自身业务需要对报文做相应的处理。
2 云游戏服务端回调接口
2.1 请求信息
表2-1 请求消息头
URL | http://www.xyz.com/api/haima/notify |
---|---|
Method | POST |
Content-Type | application/json; charset=UTF-8 |
Accept | application/json |
表2-2 请求信息参数
参数 | 类型 | 必填项 | 说明 | 示例值 |
---|---|---|---|---|
bid | String | 是 | 接入方ID | c5d240c71fa |
cid | String | 是 | 本次用户使用云游戏服务的唯一标识 | 149811223 |
pkgName | String | 是 | 游戏包名称 | com.xx.yy |
pkgVersion | String | 是 | 游戏包版本 | 1.1.1 |
pkgChannel | String | 否 | 游戏包的渠道号,用于区分同一个游戏包名,不同的渠道包 | 1001 |
ip | String | 是 | 用户的IP地址 | 11.11.11.11 |
clientType | String | 是 | 客户端设备类型。 1:PC Native 2:Android 3:Web 4:iOS 5:MAC 6:iOS_H5 7:Android_H5 8:TV |
7 |
protoData | String | 否 | 用户申请云游戏时带入的透传参数,编码要求:base64长度限制:小于 2048 字符 | base64 |
type | String | 是 | 消息类型。 StreamingStarted:游戏开始 StreamingStopped:游戏结束 StreamingResolutionChanged:游戏切换分辨率 |
StreamingStarted |
event | NotifyEvent | 是 | 回调事件内容,具体定义参考下文NotifyEvent结构说明 |
表2-3 StreamingStarted:游戏开始事件
参数 | 类型 | 必填项 | 说明 | 示例值 |
---|---|---|---|---|
timestamp | Long | 是 | 事件发生时间戳(单位为ms) | 1575705973040 |
表2-4 StreamingStopped:游戏结束事件
参数 | 类型 | 必填项 | 说明 | 示例值 |
---|---|---|---|---|
timestamp | Long | 是 | 事件发生时间戳(单位为ms) | 1575705973040 |
playInterval | Long | 是 | 游戏过程时长(单位为s) | 60 |
stopCode | String | 是 | 游戏退出原因code,后期可能会扩展,建议接入时对非列表内的stopCode码做兼容 详见下文stopCode属性说明 | 0000 |
stopMessage | String | 是 | 游戏退出原因说明 | 用户正常退出 |
表2-5 StreamingResolutionChanged:游戏切换分辨率事件
参数 | 类型 | 必填项 | 说明 | 示例值 |
---|---|---|---|---|
from | String | 是 | 变更前分辨率ID | 2 |
to | String | 是 | 变更后分辨率ID | 3 |
result | Boolean | 是 | 变更结果。 成功:true 失败:false |
true |
表2-6 stopCode & stopMessage说明
stopCode | stopMessage | 描述 |
---|---|---|
0000 | 用户正常退出 | 用户正常退出 |
0001 | SDK和服务端长连接心跳超时 | SDK每20秒给服务端发送一个Heartbeat,如果服务端连续3次未收到 Heartbeat,则认为SDK已经发生异常,自动释放ARM实例。 |
0002 | SDK和服务端长连接断开超时 | 服务端检测到长连接断开后在1分钟内没有收到SDK的重新建立连接请求,则认为SDK发生异常,自动释放ARM实例。 |
0003 | 游戏长时间无操作超时 | 用户在操作游戏时,在指定时长内没有操作,主动释放ARM实例。 |
0004 | 流服务崩溃 | 流服务连续发生3次崩溃之后,服务端认为流服务发生异常,会主动释放ARM 实例,并通过长连接给SDK发送异常消息。 |
0005 | 游戏崩溃 | 游戏崩溃后,服务端会自动重新拉起游戏,但是如果游戏连续崩溃3次后,服务端认为游戏进入不可玩状态,会主动释放ARM实例,并通过长连接给SDK发送异常信息。 |
0006 | ARM实例异常 | ARM实例发生系统异常,不能正常提供服务。 |
0007 | 内部错误 | 后端服务内部错误导致的自动释放ARM实例,例如IO异常等。 |
0008 | 商户调用openapi主动退出 | 商户服务端主动调用释放实例接口,主动释放ARM实例。 |
StreamingStarted报文示例:
{
"bid": "455r66e7e3",
"cid": "5641105047",
"clientType": "2",
"event": {
"timestamp": 1575648241051
},
"ip": "11.11.11.11",
"pkgName": "com.xx.yy.zz",
"pkgVersion": "16.0.37060",
"protoData": "eyJhZGRyZXNzIjoiIiwiYXBwVHlwZSI6IjEiLCJicmFuZCI6Ikxlbm92
byIsImNhcnJpZXIiOiIiLCJjaGFubmVsSWQiOiI0MDI1Nzc0MzE1MyIsImNpdHkiOiIiLC
JjbGllbnRJcCI6IjE5sdfMi4xNjguMS4zIiwiZGV2aWNlSWQiOiJiNmVkOWE3NDZjODMyN
GRjIiwiZ2FtZUsdflkIjoiNjAwMDA0MTk0IiwiZ2FtZVNlc3Npb25JZCI6IjE1NzU2NDgy
MzE1MjE1NmRlODVlOC02M2ZmLTQxYjMtYjg5ZC00ODlhNWRmNTM0MGMiLCJnYW1lVHlwZS
I6IjEiLCJpbWVpIjoiMDAwMDAwMDAwMDAwIiwibW9kZWwiOiJMZW5vdm8gVEItODgwNEYi
LCJuZXR3bsdf3JrIjoiNCIsInBob25lIjoiIiwicmVhbEFwcFZlcnNpb24iOiIxLjEwLjE
uMSIsInJlc2U1IjoiMCIsInJlc2U2IjoiLTEiLCJyZXNlNyI6IjE1NzU2NDgyMzE1MjE1N
mRlODVlOC02M2ZmLTQxYjMtYjg5ZC00ODlhNWRmNTM0MGMiLCJzY3JlZW4iOiIxOTIwKjE
xMDQiLCJzeXN0ZW1WZXJzaW9uIjoiNy4xLjEiLCJ1aWQiOiIiLCJ1c2VySWRUeXBlIjoiM
CIsInZlcnNpb24iOiIxLjAuMS4zIn0=",
"type": "StreamingStarted"
}
StreamingStopped报文示例:
{
"bid": "1e2153666c3",
"cid": "5435074621",
"clientType": "2",
"event": {
"playInterval": 3821,
"timestamp": 1575648094342,
"stopCode": "0000",
"stopMessage": "用户正常退出"
},
"ip": "11.11.11.11",
"pkgName": "com.xx.yy.zz",
"pkgVersion": "1.1.62",
"protoData": "eyJhZGRyZXNzIjoiIiwiYXBwVHlwZSI6IjEiLCJicmFuZCI6IkhPTk9S
IiwiY2FycmllciI6IuS4reWbveenu+WKqCIsImNoYW5uZWxJZCI6IjQwsdfsMjk2NTM0Nj
gxIiwiY2l0eSI6IiIsImNsaWVudElwIjoiMTkyLjE2OC4wLjEwNCIsImRldmljZUlkIjoi
NGVlMDQ5NTk4YWYxMWVkYSIsImdhbWVJZCI6IjUwMDAwMDAzNSIsImdhbWVTZXNzaW9uSW
QiOiIxNTc1NjQ0MjYzMjg5NjM4MmNmMDgtYzZhOS00MjI4LWI2MmYtZTA1YjlmYTBkYzZj
IiwiZ2FtZVR5cGUiOiIxIiwiaW1laSI6Ijg2MTAxMjAzMzc0NjAxMCIsIm1vZGVsIjoiQ0
FNLUFMMDAiLCJuZXR3asdfb3JrIjoiNCIsInBob25lIjoiMTM5NzIxNjY3NjEiLCJyZWFs
QXBwVmVyc2lvbiI6IjEuMTEuMS4yIiwicmVzZTUiOiIwIiwicmVzZTYiOiIyOCIsInJlc2
U3IjoiMTU3NTY0NDI2MzI4OTYzODJjZjA4LWM2YTktNDIyOC1iNjJmLWUwNWI5ZmEwZGM2
YyIsInNjcmVlbiI6IjExOTYqNzIwIiwic3lzdGVtVmVyc2lvbiI6IjYuMCIsInVpZCI6Ij
E3NzQ2MzAxNjc5NyIsInVzZXJJZFR5cGUiOiIwIiwidmVyc2lvbiI6IjEuMC4xLjQifQ==",
"type": "StreamingStopped"
}
StreamingResolutionChanged报文示例:
{
"bid": "54136667ec3",
"cid": "985110081",
"clientType": "2",
"event": {
"from": "3",
"result": true,
"to": "6"
},
"ip": "11.11.11.11",
"pkgName": "com.xx.yy.zz",
"pkgVersion": "1.1.6",
"protoData": "adefaGRyZXNzIjoiIiwiYXBwVHlwZSI6IjEiLCJicmFuZCI6InhpYW9t
aSIsImNhcnJpZXIiOiLkuK3lm73np7vliqgiLCJjaGFubmVsSWQiOiI0MDI5NjUzNDY4NS
IsImNpdHkiOiIiLCJjbGllbnRJcCI6ImZlODA6OmYwODE6MjdmZjpmZTBhOjgzNDUiLCJk
ZXZpY2VJZCI6IjZlMjMyYjQxYzA2Yzc2NWMiLCJnYW1lSWQiOiI2MDAwMDE1ODUiLCJnYW
1lU2Vzc2lvbklkIjoiMTU3NTY0OTM0MDIwOTI3MzUxYzBiLTQ3ZGQtNDQ0Yi1iM2FlLTYy
ZmQ5OGY3NzhjYiIsImdhbWVUeXBlIjoiMSIsImltZWkiOiI4NjA5MjEwNDI3MjkxMDkiLC
Jtb2RlbCI6IlJlZG1pIE5vdGUgNyBQcm8iLCJuZXR3b3JrIjoiMSIsInBob25lIjoiMTgz
ODQyNTE2NjgiLsdfsWFsQXBwVmVyc2lvbiI6IjEuMTMuMS4yIiwicmVzZTUiOiIxIiwicm
VzZTYiOiIyOCwxNyIsInJlc2U3IjoiMTU3NTY0OTM0MDIwOTI3MzUxYzBiLTQ3ZGQtNDQ0
Yi1iM2FlLTYyZmQ5OGY3NzhjYiIsInNjcmVlbiI6IjIyNjEqMTA4MCIsInN5c3RlbVZlcn
Npb24iOiI5IiwidWlkIjoiMjI1NjYzODYzMDU2IiwidXNlcklkVHlwZSI6IjAiLCJ2ZXJz
aW9uIjoiMS4wLjEuNSJ9",
"type": "StreamingResolutionChanged"
}
2.2 响应信息
响应信息示例:
{
"code": 0
}
表2-7 参数说明
参数 | 类型 | 必填项 | 说明 |
---|---|---|---|
code | Integer | 是 | 请求处理结果。 0:请求成功 1:请求失败 |
errorCode | String | 否 | 具体错误码(接入方自定义) |
errorMsg | String | 否 | 错误码对应的错误描述信息 |