从API版本26.0.0开始,游戏场景感知服务支持实况窗后台保活能力;从API版本26.0.1开始,游戏场景感知实况窗后台保活能力支持本地调试。当游戏切换到后台时,游戏继续运行并上报当前游戏场景信息,通过对应场景ID配置的实况窗内容展示当前游戏状态。

游戏启动后调用gamePerformance.init()接口对游戏场景感知进行初始化。
初始化成功后,游戏调用gamePerformance.updateGameInfo()接口向游戏场景感知上报游戏场景信息。
游戏切换到后台时根据上报的游戏场景ID展示对应实况窗保活模板。
具体API说明详见接口文档。
| 接口名 | 描述 |
|---|---|
| init(gamePackageInfo: GamePackageInfo): Promise<void> | 游戏初始化接口,对游戏场景感知进行初始化,通过Promise对象获取返回值。 |
| updateGameInfo<T extends BaseGameInfo>(gameInfo: T): Promise<void> | 更新游戏信息接口,主要用于上报游戏信息(包信息、配置信息、场景信息、网络信息和游戏触控信息等),通过Promise对象获取返回值。 |
导入Game Service Kit及公共模块。
import { gamePerformance } from '@kit.GameServiceKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit'; 导入相关模块后,需先调用init()接口对游戏场景感知进行初始化。如果未初始化或初始化失败,将无法调用其他接口。
let gamePackageInfo: gamePerformance.GamePackageInfo = {
messageType: 0,
bundleName: 'com.example.demo', // 仅示例,请替换为实际的游戏包名
appVersion: '1.0'
};
try {
gamePerformance.init(gamePackageInfo).then(() => {
// 初始化成功
hilog.info(0x0001, 'demo', `Succeeded in initializing.`);
});
} catch (error) {
// 初始化失败
let err = error as BusinessError;
hilog.error(0x0001, 'demo', `Failed to initialize. Code: ${err.code}, message: ${err.message}`);
} 初始化成功后,可以通过调用updateGameInfo()接口上报游戏场景信息。当游戏切换至后台时,游戏场景感知服务将根据上报的场景ID展示对应ID下配置的实况窗内容,实况窗配置内容请参考实况窗配置模板。
let gameSceneInfo: gamePerformance.GameSceneInfo = {
messageType: 2,
sceneID: 7,
importanceLevel: 4
};
try {
gamePerformance.updateGameInfo(gameSceneInfo).then(() => {
// 更新游戏场景信息成功
hilog.info(0x0001, 'demo', `Succeeded in updating.`);
});
} catch (error) {
// 更新游戏场景信息失败
let err = error as BusinessError;
hilog.error(0x0001, 'demo', `Failed to update. Code: ${err.code}, message: ${err.message}`);
} 游戏场景感知服务接入hidumper,支持通过hidumper命令设置本地保活模板,方便开发进行本地调试。游戏场景同时存在本地模板和云侧模板时,将优先使用本地模板的样式展示实况窗,当游戏服务重启后,本地模板将自动清除。
本地调试时所使用的hidumper命令基本格式如下:
hdc shell hidumper -s 66006 -a "<命令参数>"
“-a”后的命令参数需要用引号包裹。
本地调试步骤如下:
在设备的“/data/local/tmp/”目录下准备一个JSON配置文件,使用本地保活配置时会读取该文件。文件所需的内容如下所示,更多场景配置模板请参见实况窗配置模板。
[
{
"enterSceneId": 1,
"templateId": 0,
"maxKeepAliveTime": 300,
"keys": ["key1", "key2"],
"enterTitle": {"zh": "游戏运行中", "en": "Game Running"},
"enterDesc": {"zh": "正在%key1%", "en": "%key1% in progress"},
"exitTitle": {"zh": "游戏已退出", "en": "Game Exited"},
"exitDesc": {"zh": "已退出游戏", "en": "Game exited"},
"exitExtendData": {"zh": "扩展数据", "en": "Extend data"},
"isAlarmOnExit": false
}
] | 字段名称 | 类型 | 可选 | 说明 |
|---|---|---|---|
| enterSceneId | int64 | 否 | 进入场景的场景ID。 |
| templateId | int32 | 否 | 使用的实况窗模板类型,取值如下: 0:普通实况窗,场景切换更新时自动停止,依靠游戏上报更新进行场景内容更新,可用于游戏匹配场景。 1:倒计时实况窗,场景切换或倒计时结束时自动停止,倒计时由系统更新,可用于角色复活倒计时场景。 2:正计时实况窗,场景切换时自动停止,计时由系统更新,可用于游戏匹配场景。 3:进度实况窗,进度为从0到100,到达100或场景切换时自动停止,可用于游戏资源更新场景。 |
| maxKeepAliveTime | int32 | 否 | 最大保活时间,单位:min。 |
| keys | string[] | 是 | 从BaseGameInfo的extra字段获取到的key,用于替换enterDesc字段中的占位符“%key%”。 |
| enterTitle | map | 否 | 进入场景的实况窗标题,以key:value的格式传入,其中key为语言代码,如“zh”、“en”等。 |
| enterDesc | map | 是 | 进入场景的实况窗内容,以key:value的格式传入,其中key为语言代码,如“zh”、“en”等。 |
| exitTitle | map | 否 | 退出场景的实况窗标题,以key:value的格式传入,其中key为语言代码,如“zh”、“en”等。 |
| exitDesc | map | 是 | 退出场景的实况窗内容,以key:value的格式传入,其中key为语言代码,如“zh”、“en”等。 |
| exitExtendData | map | 是 | 退出场景的辅助区内容,以key:value的格式传入,其中key为语言代码,如“zh”、“en”等。 |
| isAlarmOnExit | boolean | 否 | 游戏退出场景时是否提醒玩家,取值如下: - true:提醒。 - false:不提醒。 |
将本地设置的JSON配置文件推送到设备。
hdc file send config.json /data/local/tmp/config.json
使能本地保活模板,将使用的配置从云侧配置切换为本地配置。
hdc shell hidumper -s 66006 -a "-se keepLiveTemplate <bundleName> -f <fileName>"
使用样例如下:
# 使能com.game.test的本地保活模板,配置文件为config.json hdc shell hidumper -s 66006 -a "-se keepLiveTemplate com.game.test -f config.json"
返回结果说明如下:
| 结果 | 说明 |
|---|---|
| Enable local template success for com.game.test | 本地保活模板使能成功。 |
| bundleName invalid | bundleName格式不合法。 |
| fileName invalid | 文件名含“/”、“\”和“..”,不合法。 |
| Failed to read or parse config file | 本地保活模板文件不存在或JSON格式错误。 |
配置文件大小不能超过512KB。
使能后会优先使用本地配置,去使能后将恢复使用云侧配置。
使能操作会覆盖同一包名的已有本地配置。
将游戏切到后台,通过观察设备上是否展示对应场景的实况窗以确认保活是否生效。
您可以选择将当前包内生效的保活模板导出到指定的JSON文件内用于检查。
hdc shell hidumper -s 66006 -a "-xp keepLiveTemplate <bundleName> -f <fileName>"
使用样例如下:
# 导出com.game.test内当前生效的保活模板到output.json hdc shell hidumper -s 66006 -a "-xp keepLiveTemplate com.game.test -f output.json"
返回结果说明如下:
| 结果 | 说明 |
|---|---|
| Export keepalive template success to /data/local/tmp/output.json | 保活模板导出成功。 |
| bundleName invalid | bundleName格式不合法。 |
| fileName invalid | 文件名含路径分隔符或“..”,不合法。 |
| No effective keepalive template for com.game.test | 本地配置和DB数据库缓存均无该包名的有效配置。 |
| File already exists: /data/local/tmp/output.json | 目标文件已存在,防止覆盖。 |
保活模板导出成功后,您还可以使用以下命令将导出后的JSON文件拉取到本地。
hdc file recv /data/local/tmp/output.json ./output.json
如果本地保活模板有更新,您可以选择将导出后的本地保活模板配置刷新到云侧。
hdc shell hidumper -s 66006 -a "-sr keepLiveTemplate <bundleName>"
使用样例如下:
# 刷新com.game.test的云侧保活配置 hdc shell hidumper -s 66006 -a "-sr keepLiveTemplate com.game.test"
返回结果说明如下:
| 结果 | 说明 |
|---|---|
| Refresh cloud config success | 云侧保活配置刷新成功 |
| bundleName invalid | bundleName格式不合法。 |
| Operation too frequent, please try again later | 1分钟内重复操作,请延长等待时间后再次尝试。 |
| Refresh cloud config failed for com.game.test | 云侧刷新请求失败。 |
| Refresh cloud config failed for com.game.test: no local config and cloud request failed | 云侧没有当前游戏的保活配置。 |
刷新操作限制的时间间隔为1分钟,频繁操作会返回限频提示。
刷新的保活配置为云侧配置,若存在本地模板,依旧优先使用本地模板。
如果需要使用刷新后的云侧配置,需要先去使能本地模板。
调试完毕,去使能本地模板,恢复使用云侧配置。
hdc shell hidumper -s 66006 -a "-sd keepLiveTemplate <bundleName>"
使用样例如下:
# 去使能com.game.test的本地保活模板,恢复使用云侧配置 hdc shell hidumper -s 66006 -a "-sd keepLiveTemplate com.game.test"
返回结果说明如下:
| 结果 | 说明 |
|---|---|
| Disable local template success for com.game.test | 去使能成功。 |
| bundleName invalid | bundleName格式不合法。 |
| No local template found for com.game.test | 该包名无本地配置。 |
{
"enterDesc": {
"en": "%key1% finding a match ...",
"zh": "%key1%开始匹配,请稍后..."
},
"enterSceneId": "0",
"enterTitle": {
"en": "Matching",
"zh": "正在匹配中"
},
"exitDesc": {
"en": "Match complete",
"zh": "匹配完成"
},
"exitTitle": {
"en": "Match complete",
"zh": "已匹配到玩家"
},
"isAlarmOnExit": true,
"keys": [
"key1"
],
"exitExtendData": {
"en": "",
"zh": ""
},
"maxKeepAliveTime": 30,
"templateId": 0
} {
"enterDesc": {
"zh": "%39%"
},
"enterSceneId": "7",
"enterTitle": {
"zh": "复活中"
},
"exitTitle": {
"zh": "已复活"
},
"isAlarmOnExit": true,
"keys": [
"39"
],
"exitExtendData": {
"zh": "返回游戏"
},
"maxKeepAliveTime": 30,
"templateId": 1
} {
"enterDesc": {
"en": "%key1% in game1...",
"zh": "%key1%正在对局中,请继续..."
},
"enterSceneId": "3",
"enterTitle": {
"en": "In game",
"zh": "正在对局中"
},
"exitDesc": {
"en": "game over",
"zh": "对局结束"
},
"exitTitle": {
"en": "Game over",
"zh": "退出对局"
},
"isAlarmOnExit": false,
"keys": [
"key1"
],
"maxKeepAliveTime": 1,
"templateId": 2
} {
"enterDesc": {
"en": "%key1% downloading...",
"zh": "%key1%正在下载中,请稍后..."
},
"enterSceneId": "4",
"enterTitle": {
"en": "Downloading",
"zh": "资源下载中"
},
"exitDesc": {
"en": "download complete",
"zh": "资源已下载完成,可打开游戏"
},
"exitTitle": {
"en": "Download complete",
"zh": "资源下载完成"
},
"isAlarmOnExit": true,
"keys": [
"key1"
],
"maxKeepAliveTime": 30,
"templateId": 3
}