You need to enable JavaScript to run this app.
导航
回调服务接入指南
最近更新时间:2025.02.14 11:31:29首次发布时间:2022.06.02 15:26:29

更新说明

2024/03/18

新增了游戏运行异常回调的说明。

2023/08/02

新增了游戏预启动结果回调的说明。

2023/05/09

  • 新增了云端游戏截图结果回调的说明。

  • 当游戏启动模式为“挂机模式”时,在启动事件回调结果中增加了“游戏启动模式”(mode_type)字段。

2023/04/04

本次更新增加了游戏日志上传结果回调的说明。

2023/03/28

本次更新增加了 “基础型” 实例套餐信息。

2023/02/08

本次更新补充了游戏服务生命周期回调的消息内容。在 “启动事件回调”、“终止事件回调”、“服务时长定时回调” 中增加了客户端用户 ID、启动游戏场景、资源套餐、用户退出游戏后服务端保留游戏运行资源时长、自定义扩展参数等字段。

前提条件

接入方需要需要准备以下信息:

  • 回调地址:支持 HTTP 的回调地址 URL(参考 控制台指南 进行配置)。

  • 用于鉴权的 Access Key ID 和 Secret Access Key(AK、SK),请求时会通过AK、SK 计算出签名,接入方可以自行验证(可通过火山引擎 云游戏控制台 > 业务详情 > 业务信息 页面获取 AK、SK。详细步骤,可参考 控制台指南 进行配置)。

回调发起类型

请求格式

  • 接口协议:HTTP
  • 请求方式:POST
  • 字符编码格式:UTF-8
  • 传值方式:Body

Header 参数

字段
类型
说明
示例

SignKeyInfo

String

请求方的身份信息
{version}/{access_key}/{timestamp}/{expire_time}

  • version: 版本信息

  • access_key: 请求方身份密钥

  • timestamp: 请求时的时间戳,unix时间戳,秒级

  • expiration:过期时间,秒级

2022-02-10/ak_example/1648211879/180
被回调方应该使用这里的 access_key(这里是ak_example),去自己的数据库查找出对应的 secret_key
access_key是ak_example
timestamp是1648211879
expiration是1800

SignatureString根据 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

服务端收到请求后:

  1. 校验请求时效性,从 Header 的 SignKeyInfo 中解析出 {timestamp}{expire_time},通过当前时间是否处于 {timestamp} + {expire_time} 内来校验该请求的时效性,过期可直接忽略,以防重放攻击。

  2. 校验签名值,解析出 access_key,查找对应的 secret_key,然后通过上面的 sha256HMAC 算法计算出签名,和请求的 Signature 比较是否一致,如果不一致说明请求被篡改,应当拒绝。

安装包解析任务事件回调

调用服务端 CreateParseTask 接口后,游戏安装包解析任务的事件回调包括以下解析状态:

  • Init(解析任务初始化)
  • download(开始下载)
  • apk_parse(开始解析,解析进度变化)
  • md5(开始计算 MD5)
  • done(任务完成)

回调信息的详细说明如下:

字段
类型
说明
product_idString业务 ID

event_type

Int

回调事件类型:

  • 5(游戏安装包解析任务)
event_dataObject消息内容,JSON 格式,参考以下 消息内容

消息内容

字段
类型
说明
task_idString任务 ID

step

String

解析任务运行步骤:

  • Init(解析任务初始化)
  • download(开始下载)
  • apk_parse(开始解析)
  • md5(开始计算 MD5)
  • done(任务完成)
processFloat64解析任务运行步骤的进度百分比

err_code

Int32

解析任务运行状态:

  • 0(运行正常)
  • 2000000(任务解析异常)
  • 2000001(下载过程异常)
  • 2000002(打开文件异常)
  • 2000003(获取文件信息异常)
  • 2000004(解压文件异常)
  • 2000005(获取包名异常)
  • 2000006(获取包版本异常)
  • 2000007(解析结果是测试包)
  • 2000008(计算 MD5 异常)
package_nameString游戏包名称
version_codeInt32游戏版本号
version_nameString游戏版本名称
md5String游戏文件 MD5
file_sizeInt64文件大小,单位 byte

游戏注册结果回调

调用服务端 CreateGameCreateGameVersion 接口后,游戏注册(上架)状态和结果的回调说明如下:

字段
类型
说明
product_idString业务 ID
game_idString游戏 ID
custom_game_idString用户自定义游戏 ID

event_type

Int

回调事件类型:

  • 4(游戏上架)
event_dataObject消息内容,JSON 格式,参考以下 消息内容

消息内容

字段
类型
说明
game_nameString游戏名称

game_rotation

String

游戏的横竖屏:

  • landscape(横屏显示)
  • portrait(竖屏显示)

game_status

Int32

游戏上架状态:

  • 1(上架完成)
  • 2(首次适配中)
  • 3(新版本适配中)
  • 4(适配失败)
current_versionString游戏当前全量的版本 ID
create_atInt64游戏创建时间

has_deploy_strategy

Boolean

是否有指定资源套餐可以启动游戏:

  • false(初始状态,游戏无部署策略,需要指定资源套餐)
  • true(已指定启动游戏的资源套餐,可以启动游戏)

当次游戏服务生命周期回调

当次游戏服务生命周期(启动、预启、终止)事件回调的详细说明如下:

字段
类型
说明
product_idString云游戏业务 ID
game_idInt64游戏 ID
custom_game_idString用户自定义游戏 ID
reserved_idString资源预锁定 ID

configuration_code

String

运行游戏的资源套餐 ID:

  • ARMSoC_Standard(基础型)

  • ARMSoC_General(通用型)

  • ARMSoC_Enhanced(加强型)

  • ARMSoC_Advanced(旗舰型)

event_type

Int

回调事件类型:

  • 0(测试验证)

  • 1(启动事件的回调)

  • 2(终止事件的回调)

  • 3(定时回调)

  • 10(游戏预启动)

  • 14(游戏运行异常)

event_dataString消息内容,JSON 格式,参考以下 消息内容

消息内容

说明:消息内容中的参数为非必填参数时,返回的消息内容如下:

  • 如果参数有默认值,则返回默认值;

  • 如果参数无默认值,则返回实际值,包括空值。

启动事件回调

字段
类型
说明
user_idString自定义客户端用户 ID,标识用户在游戏房间中的身份

round_id

String

当次游戏的生命周期标识,可以用该参数查询使用时长,链路日志等

room_type

Int

启动游戏的场景,即是否开启多人游戏及游戏控制权转移:

  • 0(单房间单用户)

  • 1(单房间多用户,不可转移游戏控制权)

  • 2(单房间多用户, 可转移游戏控制权)

role

Role

启动游戏时,游戏玩家的角色:

  • Role.PLAYER(操作者)

  • Role.VIEWER(观看者)

video_stream_profile_id

Int

游戏视频流清晰度 ID

说明:如未在申请云游戏服务时指定清晰度档位,则不返回该字段

user_tagString用户标签
reserved_idString资源预锁定 ID
auto_recycle_timeInt无操作自动回收服务时长
user_profile_pathString[]保存用户游戏配置文件的路径列表

mode_type

Int8

游戏启动模式(普通模式下,不返回此字段):

  • 1(挂机模式)

service_device_id

String

用户终端设备的唯一标识

说明:仅供参考使用,后续版本中预计会有变更

device_osString用户终端设备操作系统
sdk_versionString客户端 SDK 版本号
service_reserve_timeInt用户退出游戏后服务端保留游戏运行资源的时长
start_timeInt64启动事件回调的时间戳(秒级)
widthStringwmsize后的宽,与启动游戏返回的宽一致
heightStringwmsize后的高,与启动游戏返回的高一致
fpsString启动游戏下发的帧率
kbpsString启动游戏下发的码率
extraMap<String,String>调用客户端 start() 接口 或服务端 PreAllocateResource 接口时传入的自定义扩展参数内容

终止事件回调

字段
类型
说明
user_idString自定义客户端用户 ID,标识用户在游戏房间中的身份
user_tagString用户标签
reserved_idString资源预锁定 ID

service_device_id

String

用户终端设备的唯一标识

说明:仅供参考使用,后续版本中预计会有变更

device_osString用户终端设备操作系统
sdk_versionString客户端 SDK 版本号
service_reserve_timeInt用户退出游戏后服务端保留游戏运行资源的时长
start_timeInt64启动事件回调的时间戳(秒级)
stop_timeInt64终止事件回调的时间戳(秒级)
stop_codeInt32终止释放状态码,参看实例状态说明
stop_msgString终止释放原因,参看实例状态说明
extraMap<String,String>调用客户端 start() 接口 或服务端 PreAllocateResource 接口时传入的自定义扩展参数内容

实例状态说明

十进制状态码(stop_code)退出信息(stop_msg)说明
以下为会话正常退出状态码
784destroy客户端正常使用后,退出流程完成
785destroy_timeout客户端超时,指定时间内未启动游戏
786destroy_silence客户端超过指定时间无操作后退出
787destroy_lack_image会话启动失败,原因是服务内部问题,请联系火山引擎技术支持
788destroy_start_failed会话启动失败,原因是服务内部问题,请联系火山引擎技术支持
789destroy_rtc_error会话启动失败,原因是推流失败,请联系火山引擎技术支持
790destroy_app_framework_lack_image会话启动失败,原因是服务内部问题,请联系火山引擎技术支持
791destroy_begin_without_archive正常使用后正在退出,且无需存档
792destroy_begin_with_archive正常使用后正在退出,且需要存档
793destroy_archive_finished正常使用后正在退出,存档完成
794destroy_not_connected_after_switching_to_background超过指定的保活时间后退出
以下为会话中异常退出状态码
1025fault_app_fw_start_failed会话启动失败,原因是伴随程序启动失败
1027fault_crash会话启动失败,原因是游戏崩溃,无法启动
1028fault_stream_timeout会话启动失败,原因是推流失败,请联系火山引擎技术支持
1030fault_check_failed会话启动失败,启动参数错误
1031fault_instance_offline会话启动失败,原因是实例异常,请联系火山引擎技术支持
1032fault_game_exit会话结束,游戏内触发了结束程序,例如点击了“结束程序”等按钮
1033fault_archive_failed会话启动失败,原因是游戏内存档下载失败,请联系火山引擎技术支持

服务时长定时回调

字段
类型
说明
user_idString自定义客户端用户 ID,标识用户在游戏房间中的身份
user_tagString用户标签
reserved_idString资源预锁定 ID

service_device_id

String

用户终端设备的唯一标识

说明:仅供参考使用,后续版本中预计会有变更

device_osString用户终端设备操作系统
sdk_versionString客户端 SDK 版本号
service_reserve_timeInt用户退出游戏后服务端保留游戏运行资源的时长
start_timeInt64启动事件的时间戳(秒级)
durationInt32当次游戏服务时长(终止事件回调时间戳 - 启动事件回调时间戳,秒级)
extraMap<String,String>调用客户端 start() 接口 或服务端 PreAllocateResource 接口时传入的自定义扩展参数内容

预启游戏结果回调

调用服务端 GamePreStart 接口预启动游戏时,启动云端游戏服务结果的回调说明如下:

字段
类型
说明
user_idString自定义用户 ID
reserved_idString资源预锁定 ID
pre_launch_timeInt64游戏预启动时间
extraMap<String,String>自定义附加参数

游戏运行异常回调

字段
类型
说明
package_nameString当前运营异常的游戏包包名
versionInt64当前运营异常的游戏包版本号

reason

Int32

游戏运行异常原因:

  • 1(游戏内正常退出)

  • 2(游戏运行发生崩溃)

  • 3(游戏因为内存过低导致被终止运行)

  • 4(游戏 ANR )

游戏热更结果回调

调用服务端 HotUpdateGame 接口对游戏执行热更操作后,游戏热更结果的回调说明如下:

字段
类型
说明
product_idString业务 ID
game_idString游戏 ID
custom_game_idString用户自定义游戏 ID

event_type

Int

回调事件类型:

  • 6(游戏热更)
event_dataObject消息内容,JSON 格式,参考以下 消息内容

消息内容

字段
类型
说明
game_nameString游戏名称

game_hot_update_status

Int8

游戏热更状态:

  • 1(热更执行中)

  • 2(热更完成)

  • 3(热更失败)

current_versionString游戏当前上架完成的版本 ID
create_atInt64游戏创建时间

游戏日志上传结果回调

开启游戏日志上传功能后,游戏日志上传结果的回调说明如下:

字段
类型
说明
product_idString业务 ID
game_idString游戏 ID
client_user_idString自定义客户端用户 ID
reserved_idString资源预锁定 ID

event_type

Int

回调事件类型:

  • 7(游戏日志上传)

debug_info_uploaded

Int

游戏日志是否上传:

  • 1(上传成功)

  • 0(上传失败)

游戏截图结果回调

调用服务端 CaptureScreen 接口对云端游戏发起截图请求后,截图结果的回调说明如下:

字段
类型
说明
product_idString业务 ID
game_idInt64游戏 ID
reserved_idString资源预锁定 ID

event_type

Int

回调事件类型:

  • 8(游戏截图)
event_dataObject消息内容,JSON 格式,参考以下 消息内容

消息内容

字段
类型
说明
task_idString用户自定义截图任务 ID

code

Int32

截图结果状态:

  • 0(截图完成且上传成功)
  • 1(无内存)
  • 2(截图失败)
  • 3(截图上传失败)
urlString截图文件下载链接,有效期为1小时

丢弃排队用户事件回调

用户已经排队成功,但是一直未申请游戏服务,导致超过服务等待时间的回调说明如下:

字段
类型
说明
product_idString业务 ID

configuration_code

String

运行游戏的资源套餐 ID:

  • ARMSoC_Standard(基础型)

  • ARMSoC_General(通用型)

  • ARMSoC_Enhanced(加强型)

  • ARMSoC_Advanced(旗舰型)

client_user_idString自定义客户端用户 ID

event_type

Int

回调事件类型:

  • 9(丢弃排队用户)

返回格式

字段
类型
说明

code

Int32

返回码:

  • 0(成功)
  • 其它(失败)
messageString错误信息

错误码

回调服务可能返回的错误码和说明如下:

Code
说明
操作建议
1000请求参数错误检查请求参数是否正确
2000鉴权失败检查鉴权参数是否有效