新增了游戏运行异常回调的说明。
新增了游戏预启动结果回调的说明。
新增了云端游戏截图结果回调的说明。
当游戏启动模式为“挂机模式”时,在启动事件回调结果中增加了“游戏启动模式”(mode_type
)字段。
本次更新增加了游戏日志上传结果回调的说明。
本次更新增加了 “基础型” 实例套餐信息。
本次更新补充了游戏服务生命周期回调的消息内容。在 “启动事件回调”、“终止事件回调”、“服务时长定时回调” 中增加了客户端用户 ID、启动游戏场景、资源套餐、用户退出游戏后服务端保留游戏运行资源时长、自定义扩展参数等字段。
接入方需要需要准备以下信息:
回调地址:支持 HTTP 的回调地址 URL(参考 控制台指南 进行配置)。
用于鉴权的 Access Key ID 和 Secret Access Key(AK、SK),请求时会通过AK、SK 计算出签名,接入方可以自行验证(可通过火山引擎 云游戏控制台 > 业务详情 > 业务信息 页面获取 AK、SK。详细步骤,可参考 控制台指南 进行配置)。
字段 | 类型 | 说明 | 示例 |
---|---|---|---|
SignKeyInfo | String | 请求方的身份信息
| 2022-02-10/ak_example/1648211879/180 |
Signature | String | 根据 SignKeyInfo 和储存在用户的 SecretKey 计算出的签名 | ea4349f93a9f37a960f562ef55bf180419cac83ff302479d416503082d4f0dac |
package main import ( "crypto/hmac" "crypto/sha256" "encoding/json" "fmt" "time" ) func sha256HMAC(key []byte, data []byte) []byte { mac := hmac.New(sha256.New, key) mac.Write(data) return []byte(fmt.Sprintf("%x", mac.Sum(nil))) } func Sign(ver string, ak string, sk string, body []byte) (string, string) { expiration := 1800 signKeyInfo := fmt.Sprintf("%s/%s/%d/%d", ver, ak, time.Now().Unix(), expiration) signKey := sha256HMAC([]byte(sk), []byte(signKeyInfo)) signResult := sha256HMAC(signKey, body) return signKeyInfo, string(signResult) } type Body struct { A int B string } func main() { ak := "ak" sk := "sk" body := &Body{ A: 10, B: "demo", } payload, err := json.Marshal(body) if err != nil { panic(err) } signKeyInfo, signature := Sign("2022-02-10", ak, sk, payload) fmt.Printf("SignKeyInfo:%s ", signKeyInfo) fmt.Printf("Signature:%s ", signature) }
SignKeyInfo 示例:2022-02-10/ak_example/1648212589/1800
Signature 示例:571453384e0eb46a743d46b5c5f6bca5d7b6e097f336734e069c38368a4e5661
服务端收到请求后:
校验请求时效性,从 Header 的 SignKeyInfo 中解析出 {timestamp}
和 {expire_time}
,通过当前时间是否处于 {timestamp} + {expire_time}
内来校验该请求的时效性,过期可直接忽略,以防重放攻击。
校验签名值,解析出 access_key
,查找对应的 secret_key
,然后通过上面的 sha256HMAC 算法计算出签名,和请求的 Signature 比较是否一致,如果不一致说明请求被篡改,应当拒绝。
调用服务端 CreateParseTask 接口后,游戏安装包解析任务的事件回调包括以下解析状态:
回调信息的详细说明如下:
字段 | 类型 | 说明 |
---|---|---|
product_id | String | 业务 ID |
event_type | Int | 回调事件类型:
|
event_data | Object | 消息内容,JSON 格式,参考以下 消息内容 |
字段 | 类型 | 说明 |
---|---|---|
task_id | String | 任务 ID |
step | String | 解析任务运行步骤:
|
process | Float64 | 解析任务运行步骤的进度百分比 |
err_code | Int32 | 解析任务运行状态:
|
package_name | String | 游戏包名称 |
version_code | Int32 | 游戏版本号 |
version_name | String | 游戏版本名称 |
md5 | String | 游戏文件 MD5 |
file_size | Int64 | 文件大小,单位 byte |
调用服务端 CreateGame 或 CreateGameVersion 接口后,游戏注册(上架)状态和结果的回调说明如下:
字段 | 类型 | 说明 |
---|---|---|
product_id | String | 业务 ID |
game_id | String | 游戏 ID |
custom_game_id | String | 用户自定义游戏 ID |
event_type | Int | 回调事件类型:
|
event_data | Object | 消息内容,JSON 格式,参考以下 消息内容 |
字段 | 类型 | 说明 |
---|---|---|
game_name | String | 游戏名称 |
game_rotation | String | 游戏的横竖屏:
|
game_status | Int32 | 游戏上架状态:
|
current_version | String | 游戏当前全量的版本 ID |
create_at | Int64 | 游戏创建时间 |
has_deploy_strategy | Boolean | 是否有指定资源套餐可以启动游戏:
|
当次游戏服务生命周期(启动、预启、终止)事件回调的详细说明如下:
字段 | 类型 | 说明 |
---|---|---|
product_id | String | 云游戏业务 ID |
game_id | Int64 | 游戏 ID |
custom_game_id | String | 用户自定义游戏 ID |
reserved_id | String | 资源预锁定 ID |
configuration_code | String | 运行游戏的资源套餐 ID:
|
event_type | Int | 回调事件类型:
|
event_data | String | 消息内容,JSON 格式,参考以下 消息内容 |
说明:消息内容中的参数为非必填参数时,返回的消息内容如下:
如果参数有默认值,则返回默认值;
如果参数无默认值,则返回实际值,包括空值。
字段 | 类型 | 说明 |
---|---|---|
user_id | String | 自定义客户端用户 ID,标识用户在游戏房间中的身份 |
round_id | String | 当次游戏的生命周期标识,可以用该参数查询使用时长,链路日志等 |
room_type | Int | 启动游戏的场景,即是否开启多人游戏及游戏控制权转移:
|
role | Role | 启动游戏时,游戏玩家的角色:
|
video_stream_profile_id | Int | 游戏视频流清晰度 ID
|
user_tag | String | 用户标签 |
reserved_id | String | 资源预锁定 ID |
auto_recycle_time | Int | 无操作自动回收服务时长 |
user_profile_path | String[] | 保存用户游戏配置文件的路径列表 |
mode_type | Int8 | 游戏启动模式(普通模式下,不返回此字段):
|
service_device_id | String | 用户终端设备的唯一标识
|
device_os | String | 用户终端设备操作系统 |
sdk_version | String | 客户端 SDK 版本号 |
service_reserve_time | Int | 用户退出游戏后服务端保留游戏运行资源的时长 |
start_time | Int64 | 启动事件回调的时间戳(秒级) |
width | String | wmsize后的宽,与启动游戏返回的宽一致 |
height | String | wmsize后的高,与启动游戏返回的高一致 |
fps | String | 启动游戏下发的帧率 |
kbps | String | 启动游戏下发的码率 |
extra | Map<String,String> | 调用客户端 start() 接口 或服务端 PreAllocateResource 接口时传入的自定义扩展参数内容 |
字段 | 类型 | 说明 |
---|---|---|
user_id | String | 自定义客户端用户 ID,标识用户在游戏房间中的身份 |
user_tag | String | 用户标签 |
reserved_id | String | 资源预锁定 ID |
service_device_id | String | 用户终端设备的唯一标识
|
device_os | String | 用户终端设备操作系统 |
sdk_version | String | 客户端 SDK 版本号 |
service_reserve_time | Int | 用户退出游戏后服务端保留游戏运行资源的时长 |
start_time | Int64 | 启动事件回调的时间戳(秒级) |
stop_time | Int64 | 终止事件回调的时间戳(秒级) |
stop_code | Int32 | 终止释放状态码,参看实例状态说明 |
stop_msg | String | 终止释放原因,参看实例状态说明 |
extra | Map<String,String> | 调用客户端 start() 接口 或服务端 PreAllocateResource 接口时传入的自定义扩展参数内容 |
实例状态说明
十进制状态码(stop_code) | 退出信息(stop_msg) | 说明 |
---|---|---|
以下为会话正常退出状态码 | ||
784 | destroy | 客户端正常使用后,退出流程完成 |
785 | destroy_timeout | 客户端超时,指定时间内未启动游戏 |
786 | destroy_silence | 客户端超过指定时间无操作后退出 |
787 | destroy_lack_image | 会话启动失败,原因是服务内部问题,请联系火山引擎技术支持 |
788 | destroy_start_failed | 会话启动失败,原因是服务内部问题,请联系火山引擎技术支持 |
789 | destroy_rtc_error | 会话启动失败,原因是推流失败,请联系火山引擎技术支持 |
790 | destroy_app_framework_lack_image | 会话启动失败,原因是服务内部问题,请联系火山引擎技术支持 |
791 | destroy_begin_without_archive | 正常使用后正在退出,且无需存档 |
792 | destroy_begin_with_archive | 正常使用后正在退出,且需要存档 |
793 | destroy_archive_finished | 正常使用后正在退出,存档完成 |
794 | destroy_not_connected_after_switching_to_background | 超过指定的保活时间后退出 |
以下为会话中异常退出状态码 | ||
1025 | fault_app_fw_start_failed | 会话启动失败,原因是伴随程序启动失败 |
1027 | fault_crash | 会话启动失败,原因是游戏崩溃,无法启动 |
1028 | fault_stream_timeout | 会话启动失败,原因是推流失败,请联系火山引擎技术支持 |
1030 | fault_check_failed | 会话启动失败,启动参数错误 |
1031 | fault_instance_offline | 会话启动失败,原因是实例异常,请联系火山引擎技术支持 |
1032 | fault_game_exit | 会话结束,游戏内触发了结束程序,例如点击了“结束程序”等按钮 |
1033 | fault_archive_failed | 会话启动失败,原因是游戏内存档下载失败,请联系火山引擎技术支持 |
字段 | 类型 | 说明 |
---|---|---|
user_id | String | 自定义客户端用户 ID,标识用户在游戏房间中的身份 |
user_tag | String | 用户标签 |
reserved_id | String | 资源预锁定 ID |
service_device_id | String | 用户终端设备的唯一标识
|
device_os | String | 用户终端设备操作系统 |
sdk_version | String | 客户端 SDK 版本号 |
service_reserve_time | Int | 用户退出游戏后服务端保留游戏运行资源的时长 |
start_time | Int64 | 启动事件的时间戳(秒级) |
duration | Int32 | 当次游戏服务时长(终止事件回调时间戳 - 启动事件回调时间戳,秒级) |
extra | Map<String,String> | 调用客户端 start() 接口 或服务端 PreAllocateResource 接口时传入的自定义扩展参数内容 |
调用服务端 GamePreStart 接口预启动游戏时,启动云端游戏服务结果的回调说明如下:
字段 | 类型 | 说明 |
---|---|---|
user_id | String | 自定义用户 ID |
reserved_id | String | 资源预锁定 ID |
pre_launch_time | Int64 | 游戏预启动时间 |
extra | Map<String,String> | 自定义附加参数 |
字段 | 类型 | 说明 |
---|---|---|
package_name | String | 当前运营异常的游戏包包名 |
version | Int64 | 当前运营异常的游戏包版本号 |
reason | Int32 | 游戏运行异常原因:
|
调用服务端 HotUpdateGame 接口对游戏执行热更操作后,游戏热更结果的回调说明如下:
字段 | 类型 | 说明 |
---|---|---|
product_id | String | 业务 ID |
game_id | String | 游戏 ID |
custom_game_id | String | 用户自定义游戏 ID |
event_type | Int | 回调事件类型:
|
event_data | Object | 消息内容,JSON 格式,参考以下 消息内容 |
字段 | 类型 | 说明 |
---|---|---|
game_name | String | 游戏名称 |
game_hot_update_status | Int8 | 游戏热更状态:
|
current_version | String | 游戏当前上架完成的版本 ID |
create_at | Int64 | 游戏创建时间 |
开启游戏日志上传功能后,游戏日志上传结果的回调说明如下:
字段 | 类型 | 说明 |
---|---|---|
product_id | String | 业务 ID |
game_id | String | 游戏 ID |
client_user_id | String | 自定义客户端用户 ID |
reserved_id | String | 资源预锁定 ID |
event_type | Int | 回调事件类型:
|
debug_info_uploaded | Int | 游戏日志是否上传:
|
调用服务端 CaptureScreen 接口对云端游戏发起截图请求后,截图结果的回调说明如下:
字段 | 类型 | 说明 |
---|---|---|
product_id | String | 业务 ID |
game_id | Int64 | 游戏 ID |
reserved_id | String | 资源预锁定 ID |
event_type | Int | 回调事件类型:
|
event_data | Object | 消息内容,JSON 格式,参考以下 消息内容 |
字段 | 类型 | 说明 |
---|---|---|
task_id | String | 用户自定义截图任务 ID |
code | Int32 | 截图结果状态:
|
url | String | 截图文件下载链接,有效期为1小时 |
用户已经排队成功,但是一直未申请游戏服务,导致超过服务等待时间的回调说明如下:
字段 | 类型 | 说明 |
---|---|---|
product_id | String | 业务 ID |
configuration_code | String | 运行游戏的资源套餐 ID:
|
client_user_id | String | 自定义客户端用户 ID |
event_type | Int | 回调事件类型:
|
字段 | 类型 | 说明 |
---|---|---|
code | Int32 | 返回码:
|
message | String | 错误信息 |
回调服务可能返回的错误码和说明如下:
Code | 说明 | 操作建议 |
---|---|---|
1000 | 请求参数错误 | 检查请求参数是否正确 |
2000 | 鉴权失败 | 检查鉴权参数是否有效 |