Cocos Service:性能管理(AppGallery Connect)快速入门
推荐:将NSDT场景编辑器加入你的3D工具链
3D工具集:NSDT简石数字孪生
性能管理(AppGallery Connect)快速入门
华为 AppGallery Connect(简称 AGC)性能管理(APM,App Performance Management)服务,提供分钟级应用性能监控能力,开发者可以在 AGC 后台查看和分析性能管理服务收集到的应用性能数据,从而全面了解所开发应用的性能特点,快速精准修复应用存在的性能问题,持续提升应用的用户体验。
主要功能
功能 | 说明 |
---|---|
自动采集应用启动、应用屏幕、HTTP/HTTPS 网络请求等方面的性能数据 | 性能管理 APM SDK 能够自动采集应用启动、应用屏幕、HTTP/HTTPS 网络请求等关键性能数据。 1. 应用启动性能数据:记录应用启动(冷启动和热启动)时间。 2. 应用屏幕性能数据:记录应用屏幕渲染缓慢帧和冻结帧数量。 3. HTTP/HTTPS 网络性能数据:SDK 记录响应时长,成功率,响应大小等指标数据。 |
支持查看和分析应用性能数据,精准发现应用性能在哪些方面有改进空间 | 性能管理 APM 通过多个维度(版本号、国家/地区、手机类型、一级区域、系统版本、运营商、网络)向开发者展示应用的性能指标,帮助开发者快速了解应用在哪些方面可优化改进。 |
支持创建自定义跟踪记录,监控应用在特定场景下的性能 | 借助性能管理 APM SDK,开发者可以: 1. 创建自定义跟踪记录来监控应用在特定场景,如用户登录或者屏幕加载场景下的性能。 2. 为自定义跟踪记录添加指标(如登录次数)和属性(如登录是否成功)。 |
版本更新说明(Cocos Creator 2.x)
当前版本:v0.5.4_1.5.2.300
- 新增对Game SDK的支持。
v0.5.3_1.5.2.300
- 升级APMS SDK至版本1.5.2.300。
- 支持自动监控应用ANR的能力,新增enableAnrMonitor方法用来启用和停用该能力。
- 新增setUserIdentifier方法,用于设置用户标识,方便定位单用户问题。
v0.5.2_1.3.1.300
- 修复部分 bug。
v0.5.1_1.3.1
- 集成华为 AGC APM 服务。
版本更新说明(Cocos Creator 3.x)
当前版本:v2.0.2_1.5.2.300
- 新增对Game SDK的支持。
v2.0.1_1.5.2.300
- 升级APMS SDK至版本1.5.2.300。
- 支持自动监控应用ANR的能力,新增enableAnrMonitor方法用来启用和停用该能力。
- 新增setUserIdentifier方法,用于设置用户标识,方便定位单用户问题。
v2.0.0_1.3.1.300
- 适配 华为性能管理 到 Cocos Creator 3.0。
一键接入性能管理服务
开通服务
- 使用 Cocos Creator 打开需要接入性能管理服务的项目工程。
点击菜单栏的 面板 -> 服务,打开 服务 面板,选择 性能管理,进入服务详情页。然后点击右上方的 启用 按钮即可开通服务。详情可参考 服务面板操作指南。
如果华为后台的 性能管理 服务尚未开通,需登录 AppGallery Connect 后台,选择 我的项目,进入 质量 -> 性能管理 页面,点击 立即开通 按钮开通服务。
配置华为参数文件
大部分的华为相关项目都需要用到 agconnect-services.json
配置文件。若有新开通服务等操作,请及时更新该文件。
- 登录 AppGallery Connect 后台,在 项目列表 -> 应用列表 中找到对应的应用。
在 项目设置 页面的 应用 区域,点击 agconnect-services.json
下载配置文件。agconnect-services.json
文件在下载或者更新完成后,必须手动拷贝 到工程目录的 settings
目录下。
Cocos Creator v2.4.3 及以上版本,若 发布到 HUAWEI AppGallery Connect,开发者可直接在 构建发布 面板中选取下载或更新后的配置文件,不需要手动拷贝。
验证服务是否接入成功
- 完成 性能管理 服务接入步骤后,无需改动代码,即可 发布到 Android 平台。请确保 构建发布 面板中的包名与华为后台设置的包名一致。
工程运行到手机后,登录 AppGallery Connect 后台,打开对应项目,进入 质量 -> 性能管理,若能看到应用性能数据正常显示(通常会在 15 分钟内显示),即为接入成功。
Sample 工程
开发者可以通过 Sample 工程快速体验性能管理服务。
- 点击性能管理服务面板中的 Sample 工程 按钮,Clone 或下载 HUAWEI Sample 工程,并在 Cocos Creator 中打开。
- 参照上文开通性能管理并配置华为参数文件后,可通过 Creator 编辑器菜单栏的 项目 -> 构建发布 打开 构建发布 面板来构建编译工程。Creator v2.4.1 及以上版本,可 发布到 HUAWEI AppGallery Connect。Creator v2.4.1 以下的版本可 发布到 Android 平台。
Sample 工程运行到手机后,点击首页的 APMS 按钮,即可进入功能界面进行测试。
开发指南
设置性能管理服务开关
enableCollection(enable: boolean): void
可参考 在应用客户端停用 文档。开关的默认值为打开(true),如果需要停用应用性能数据采集,可将开关设为关闭(false)。
应用客户端停用的级别 高于 AGC 远程配置停用。如用户在应用客户端停用性能监控,即使通过 AGC 远程配置打开性能监控开关,性能管理服务也不会进行性能数据采集。
参数说明:
参数 | 说明 |
---|---|
enable | APM 服务开关。true :打开,性能管理服务会采集性能监控数据。false :关闭,性能管理服务不会采集性能监控数据。 |
示例:
huawei.agc.apms.apmsService.enableCollection(true);
设置ANR监控开关
enableAnrMonitor(enable: boolean): void
可参考 停用ANR监控 文档。开关的默认值为打开(true),如果需要停用ANR监控,可将开关设为关闭(false)。
APM性能监控开关优先级高于ANR监控开关,仅在APM性能监控开关打开情况下,ANR监控开关才会生效。
参数说明:
参数 | 说明 |
---|---|
enable | ANR 监控开关。true :打开,性能管理服务会启用ANR监控并上报数据。false :关闭,性能管理服务停用ANR监控。 |
示例:
huawei.agc.apms.apmsService.enableAnrMonitor(true);
为上报数据绑定用户标识(可选)
setUserIdentifier(userIdentifier: string): void
可参考 为上报数据绑定用户标识 文档。为上报数据绑定用户标识,性能数据上报时会一并上报该用户标识,方便单用户问题定位。
参数说明:
参数 | 说明 |
---|---|
userIdentifier | 用户标识。 |
示例:
huawei.agc.apms.apmsService.setUserIdentifier('475f5afaxxxxx');
添加自定义跟踪记录(可选)
可参考 添加自定义跟踪记录 文档。自定义跟踪记录可用于监控开发者的应用在特定场景下的性能,如应用登录场景、应用页面长时间无响应场景等。性能管理插件封装后的方法,比起 SDK 原型方法,需要加入 name
参数,用于获取对象调用。若当前名称的对象不存在,则会再新建一个对象。
启动自定义跟踪记录
startCustomTrace(name: string): void
可参考 启动自定义跟踪记录 文档。
参数说明:
参数 | 说明 |
---|---|
name | 自定义跟踪记录名称,只能包含中文、字母(不区分大小写)、数字和下划线,且长度不能超过 100 字符,所有方法需要根据该名称获取对象调用。若当前名称的对象不存在,则会再新建一个对象。 |
示例:
huawei.agc.apms.apmsService.startCustomTrace("traceID");
停止自定义跟踪记录
stopCustomTrace(name: string): void
可参考 停止自定义跟踪记录 文档。
参数说明:
参数 | 说明 |
---|---|
name | 自定义跟踪记录名称,只能包含中文、字母(不区分大小写)、数字和下划线,且长度不能超过 100 字符,所有方法需要根据该名称获取对象调用。若当前名称的对象不存在,则会再新建一个对象。 |
示例:
huawei.agc.apms.apmsService.stopCustomTrace("traceID");
添加自定义属性
putCustomTraceProperty(name: string, propertyName: string, propertyValue: string): void
设置自定义跟踪记录属性名称和属性值。每个 CustomTrace 实例最多只能设置 5 个自定义属性。
参数说明:
参数 | 说明 |
---|---|
name | 自定义跟踪记录名称,只能包含中文、字母(不区分大小写)、数字和下划线,且长度不能超过 100 字符,所有方法需要根据该名称获取对象调用。若当前名称的对象不存在,则会再新建一个对象。 |
propertyName | 自定义属性名称,只能由中文、字母(不区分大小写)、数字和下划线组成,且长度不超过 40 字符。 |
propertyValue | 自定义属性值,只能由中文、字母(不区分大小写)、数字和下划线组成,且长度不超过 100 字符。 |
示例:
let traceID = "testTrace";
let pName = "product";
let pValue = "food";
huawei.agc.apms.apmsService.putCustomTraceProperty(traceID, pName, pValue);
移除自定义属性
removeCustomTraceProperty(name: string, propertyName: string): void
从 CustomTrace 实例中移除自定义属性。
参数说明:
参数 | 说明 |
---|---|
name | 自定义跟踪记录名称,只能包含中文、字母(不区分大小写)、数字和下划线,且长度不能超过 100 字符,所有方法需要根据该名称获取对象调用。若当前名称的对象不存在,则会再新建一个对象。 |
propertyName | 自定义属性名称,只能由中文、字母(不区分大小写)、数字和下划线组成,且长度不超过 40 字符。 |
示例:
let traceID = "testTrace";
let pName = "product";
huawei.agc.apms.apmsService.removeCustomTraceProperty(traceID, pName);
获取自定义属性值
getCustomTraceProperty(name: string, propertyName: string): string
可参考 获取自定义属性值 文档。
参数说明:
参数 | 说明 |
---|---|
name | 自定义跟踪记录名称,只能包含中文、字母(不区分大小写)、数字和下划线,且长度不能超过 100 字符,所有方法需要根据该名称获取对象调用。若当前名称的对象不存在,则会再新建一个对象。 |
propertyName | 自定义属性名称,只能由中文、字母(不区分大小写)、数字和下划线组成,且长度不超过 40 字符。 |
示例:
let traceID = "testTrace";
let pName = "product";
let propertValue = huawei.agc.apms.apmsService.getCustomTraceProperty(traceID, pName);
console.log("pValue = ", propertValue);
增加自定义跟踪记录指标
incrementCustomTraceMeasure(name: string, measureName: string, measureValue: number): void
增加自定义跟踪记录指标的指标值。如果指标不存在,将创建一个新指标。如果自定义跟踪记录未启动或已停止,接口不生效。
参数说明:
参数 | 说明 |
---|---|
name | 自定义跟踪记录名称,只能包含中文、字母(不区分大小写)、数字和下划线,且长度不能超过 100 字符,所有方法需要根据该名称获取对象调用。若当前名称的对象不存在,则会再新建一个对象。 |
measureName | 自定义跟踪记录指标名称。 |
measureValue | 自定义跟踪记录指标值,对应 Java 侧 long 型数值。 |
示例:
let traceID = "testTrace";
let mName = "MeasureName";
let mValue = 12000;
huawei.agc.apms.apmsService.incrementCustomTraceMeasure(traceID, mName, mValue);
获取自定义跟踪记录指标值
getCustomTraceMeasure(name: string, measureName: string): string
可参考 获取自定义跟踪记录指标值 文档。
参数说明:
参数 | 说明 |
---|---|
name | 自定义跟踪记录名称,只能包含中文、字母(不区分大小写)、数字和下划线,且长度不能超过 100 字符,所有方法需要根据该名称获取对象调用。若当前名称的对象不存在,则会再新建一个对象。 |
measureName | 自定义跟踪记录指标名称。 |
示例:
let traceID = "testTrace";
let mName = "MeasureName";
let measureValue = huawei.agc.apms.apmsService.getCustomTraceMeasure(traceID, mName);
console.log("mValue = ", measureValue);
添加自定义跟踪记录指标
putCustomTraceMeasure(name: String, measureName: String, measureValue: number): void
添加自定义跟踪记录指标。如果指标已经存在,则更新指标的值。
参数说明:
参数 | 说明 |
---|---|
name | 自定义跟踪记录名称,只能包含中文、字母(不区分大小写)、数字和下划线,且长度不能超过 100 字符,所有方法需要根据该名称获取对象调用。若当前名称的对象不存在,则会再新建一个对象。 |
measureName | 自定义跟踪记录指标名称。 |
measureValue | 自定义跟踪记录指标值,对应 Java 侧 long 型数值。 |
示例:
let traceID = "testTrace";
let mName = "MeasureName";
let mValue = 12000;
huawei.agc.apms.apmsService.putCustomTraceMeasure(traceID, mName, mValue);
获取自定义跟踪记录的所有属性
getCustomTraceProperties(name: string): string
获取自定义跟踪记录的所有属性。返回值为 JSON 对象,存放所有属性的键值对。
参数说明:
参数 | 说明 |
---|---|
name | 自定义跟踪记录名称,只能包含中文、字母(不区分大小写)、数字和下划线,且长度不能超过 100 字符,所有方法需要根据该名称获取对象调用。若当前名称的对象不存在,则会再新建一个对象。 |
示例:
let traceID = "testTrace";
let tProp = huawei.agc.apms.apmsService.getCustomTraceProperties(traceID);
console.log("tProp = ", JSON.stringify(tProp));
添加针对特定网络请求的监控指标(可选)
可参考 添加针对特定网络请求的监控指标 文档。虽然 APM 会自动采集应用中大多数网络请求性能数据,但如果采用的是非 URLConnection 或非 Okhttp 框架,还是有少量网络请求 APM 无法自动采集。此时,可以按照下列方式采集网络请求性能数据。另外,您还可以对特定网络请求添加自定义属性。
创建网络请求指标实例
initNetworkMeasure(url: string, httpMethod: string): string
针对每个网络请求,创建网络请求指标实例,用于采集网络性能数据。返回值即为下方各方法所需的 id 参数。
参数说明:
参数 | 说明 |
---|---|
url | 网络请求 URL 地址 |
httpMethod | 请求方法,仅支持 GET、PUT、POST、DELETE、HEAD、PATCH、OPTIONS、TRACE 和 CONNECT 方法。 |
示例:
let id = huawei.agc.apms.apmsService.initNetworkMeasure(url, "POST");
console.log("createNetworkMeasure, id = ", id);
设置请求开始时间
startNetworkMeasure(id: string): void
可参考 设置请求开始时间 文档。
参数说明:
参数 | 说明 |
---|---|
id | initNetworkMeasure 方法返回的对象 id,同时可能有多个 id 对象存在。其他方法均需要传入此 id。 |
示例:
huawei.agc.apms.apmsService.startNetworkMeasure(id);
设置请求结束时间
stopNetworkMeasure(id: string): void
可参考 设置请求结束时间 文档 ,并上报网络请求指标及自定义属性数据。
参数说明:
参数 | 说明 |
---|---|
id | initNetworkMeasure 方法返回的对象 id,同时可能有多个 id 对象存在。其他方法均需要传入此 id。 |
示例:
huawei.agc.apms.apmsService.stopNetworkMeasure(id);
设置请求的响应码
setNetworkMeasureStatusCode(id: string, statusCode: number): void
可参考 设置请求的响应码 文档。
参数说明:
参数 | 说明 |
---|---|
id | initNetworkMeasure 方法返回的对象 id,同时可能有多个 id 对象存在。其他方法均需要传入此 id。 |
statusCode | 请求的响应码 |
示例:
huawei.agc.apms.apmsService.setNetworkMeasureStatusCode(id, 500);
设置请求体大小
setNetworkMeasureBytesSent(id: string, length: number): void
可参考 设置请求体大小 文档。
参数说明:
参数 | 说明 |
---|---|
id | initNetworkMeasure 方法返回的对象 id,同时可能有多个 id 对象存在。其他方法均需要传入此 id。 |
length | 请求体大小,对应 Java 侧 long 型数值。 |
示例:
huawei.agc.apms.apmsService.setNetworkMeasureBytesSent(id, 10000);
设置响应体大小
setNetworkMeasureBytesReceived(id: string, length: number): void
可参考 设置响应体大小 文档。
参数说明:
参数 | 说明 |
---|---|
id | initNetworkMeasure 方法返回的对象 id,同时可能有多个 id 对象存在。其他方法均需要传入此 id。 |
length | 响应体大小,对应 Java 侧 long 型数值。 |
示例:
huawei.agc.apms.apmsService.setNetworkMeasureBytesReceived(id, 10000);
设置响应体 contentType 类型
setNetworkMeasureContentType(id: string, contentType: string): void
可参考 设置响应体 contentType 类型 文档。
参数说明:
参数 | 说明 |
---|---|
id | initNetworkMeasure 方法返回的对象 id,同时可能有多个 id 对象存在。其他方法均需要传入此 id。 |
contentType | 响应体 contentType 类型 |
示例:
huawei.agc.apms.apmsService.setNetworkMeasureContentType(id, "contentType1");
设置网络请求的自定义属性名称和属性值
putNetworkMeasureProperty(id: string, propertyName: string, propertyValue: string): void
可参考 设置网络请求的自定义属性名称和属性值 文档。每个 NetworkMeasure 实例最多只能设置 5 个自定义属性。
参数说明:
参数 | 说明 |
---|---|
id | initNetworkMeasure 方法返回的对象 id,同时可能有多个 id 对象存在。其他方法均需要传入此 id。 |
propertyName | 自定义属性名称,只能由中文、字母(不区分大小写)、数字和下划线组成,且长度不能超过 40 字符。 |
propertyValue | 自定义属性值,只能由中文、字母(不区分大小写)、数字和下划线组成,且长度不能超过 100 字符。 |
示例:
let pName = "propName";
let pValue = "12000";
huawei.agc.apms.apmsService.putNetworkMeasureProperty(id, pName, pValue);
从 NetworkMeasure 实例中移除已存在属性
removeNetworkMeasureProperty(id: string, propertyName: string): void
可参考 从 NetworkMeasure 实例中移除已存在属性 文档。
参数说明:
参数 | 说明 |
---|---|
id | initNetworkMeasure 方法返回的对象 id,同时可能有多个 id 对象存在。其他方法均需要传入此 id。 |
propertyName | 自定义属性名称,只能由中文、字母(不区分大小写)、数字和下划线组成,且长度不能超过 40 字符。 |
示例:
let pName = "propName";
huawei.agc.apms.apmsService.removeNetworkMeasureProperty(id, pName);
从 NetworkMeasure 实例中获取所有属性
getNetworkMeasureProperties(id: string): string
可参考 从 NetworkMeasure 实例中获取所有属性 文档,返回 JSON 对象。
参数说明:
参数 | 说明 |
---|---|
id | initNetworkMeasure 方法返回的对象 id,同时可能有多个 id 对象存在。其他方法均需要传入此 id。 |
示例:
let mProp = huawei.agc.apms.apmsService.getNetworkMeasureProperties(id);
console.log("mProp = ", JSON.stringify(mProp));
获取自定义属性值
getNetworkMeasureProperty(id: string, propertyName: string): string
可参考 获取自定义属性值 文档。
参数说明:
参数 | 说明 |
---|---|
id | initNetworkMeasure 方法返回的对象 id,同时可能有多个 id 对象存在。其他方法均需要传入此 id。 |
propertyName | 自定义属性名称,只能由中文、字母(不区分大小写)、数字和下划线组成,且长度不能超过 40 字符。 |
示例:
let pName = "propName";
let nMeasure = huawei.agc.apms.apmsService.getNetworkMeasureProperty(id, pName);
console.log("nMeasure = ", nMeasure);
Game SDK(可选)
开始APM Game Plugin服务
start(): void
开始APM Game Plugin服务,一般在游戏开始时的初始化代码中调用,调用后才能使用Game SDK的其他API。
示例:
huawei.agc.apms.game.apmsGameService.start();
停止APM Game Plugin服务
stop(): void
停止APM Game Plugin服务。
示例:
huawei.agc.apms.game.apmsGameService.stop();
开始记录场景加载时间
startLoadingScene(gameAttribute: GameAttribute): string
开始记录场景加载时间,返回值为场景名称。
参数说明:
参数 | 说明 |
---|---|
gameAttribute | 游戏属性。 |
示例:
const gameAttribute = new huawei.agc.apms.game.GameAttribute('Game', huawei.agc.apms.game.LoadingState.LOADING);
huawei.agc.apms.game.apmsGameService.startLoadingScene(gameAttribute);
停止记录场景加载时间
stopLoadingScene(scene: string): void
停止记录场景加载时间。
参数说明:
参数 | 说明 |
---|---|
scene | 场景名称。 |
示例:
huawei.agc.apms.game.apmsGameService.stopLoadingScene('Game');
保存当前游戏属性
setCurrentGameAttribute(gameAttribute: GameAttribute): void
保存当前游戏属性。
参数说明:
参数 | 说明 |
---|---|
gameAttribute | 游戏属性。 |
示例:
const gameAttribute = new huawei.agc.apms.game.GameAttribute('Game', huawei.agc.apms.game.LoadingState.LOADING);
huawei.agc.apms.game.apmsGameService.setCurrentGameAttribute(gameAttribute);
设置游戏性能数据上报频率
setReportMinRate(intervalMin: number): void
设置游戏性能数据上报频率,单位:分钟。
参数说明:
参数 | 说明 |
---|---|
intervalMin | 上报频率,单位:分钟。 |
示例:
huawei.agc.apms.game.apmsGameService.setReportMinRate(5);
设置APM Game Plugin服务开关
enableGamePlugin(enabled: boolean): void
设置APM Game Plugin服务开关。开关的默认值为true(打开),表示启用APM Game Plugin应用性能数据采集。如果需要停用APM Game Plugin应用性能数据采集,可将开关值设为false(关闭)。
参数说明:
参数 | 说明 |
---|---|
enabled | 服务开关,true为开,false为关,默认为开。 |
示例:
huawei.agc.apms.game.apmsGameService.enableGamePlugin(true);
由3D建模学习工作室 翻译整理,转载请注明出处!
上一篇:Cocos Service:分析服务(HMS Core) (mvrlink.com)
下一篇:Cocos Service:认证服务(AppGallery Connect)快速入门 (mvrlink.com)