性能管理（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）
当前版本： [3.X]2.1.6_1.6.2.300
- 完善内部实现
当前版本：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.1.3_1.6.2.300
- 升级SDK版本。
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 打开需要接入性能管理服务的项目工程。
点击菜单栏的 面板 -> 服务，打开 服务 面板，在HUAWEI AppGallery Connect下选择 性能管理，进入服务详情页。然后点击右上方的 启用 按钮即可开通服务。
如果华为后台的 性能管理 服务尚未开通，需登录 AppGallery Connect 后台，选择 我的项目，进入 质量 -> 性能管理 页面，点击 立即开通 按钮开通服务。
配置华为参数文件
大部分的华为相关项目都需要用到 agconnect-services.json 配置文件。若有新开通服务等操作，请及时更新该文件。
登录 AppGallery Connect 后台，在 项目列表 -> 应用列表 中找到对应的应用。
在 项目设置 页面的 应用 区域，点击
agconnect-services.json下载配置文件。agconnect-services.json文件在下载或者更新完成后，必须手动拷贝 到工程目录的settings目录下。
Cocos Creator v2.4.3 及以上版本，若 发布到 HUAWEI AppGallery Connect，开发者可直接在 构建发布 面板中选取下载或更新后的配置文件，不需要手动拷贝。
Sample 工程
开发者可以通过 Sample 工程快速体验推送服务。
点击分析服务面板中的 Sample 工程 按钮，Clone 或下载 HUAWEI Sample 工程，并在 Cocos Creator 中打开。
参照上文开通分析服务并配置华为参数文件后，可通过 Creator 编辑器菜单栏的 项目 -> 构建发布 打开 构建发布 面板来构建编译工程。Creator v2.4.1 及以上版本，可 发布到 HUAWEI AppGallery Connect，Creator v2.4.1 以下的版本可 发布到 Android 平台。
需要在已安装 HMS Core 服务的华为手机上测试。
Sample 工程运行到手机后，点击首页的 Apms 按钮，即可进入功能界面进行测试。
验证服务是否接入成功
完成 性能管理 服务接入步骤后，无需改动代码，即可 发布到 Android 平台。请确保 构建发布 面板中的包名与华为后台设置的包名一致。
工程运行到手机后，登录 AppGallery Connect 后台，打开对应项目，进入 质量 -> 性能管理，若能看到应用性能数据正常显示（通常会在 15 分钟内显示），即为接入成功。
开发指南
设置性能管理服务开关
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);
创建自定义日志打印实例，支持打印的日志被日志回捞任务拉取
getNetworkMeasureProperty(id: string, propertyName: string): string
可参考文档。
示例：
let suc = huawei.agc.apms.apmsService.createApmsLog();
写入自定义日志
setApmsLog (type: string, tag: string, msg: string): boolean
可参考文档。
参数
| 参数 | 说明 |
|---|---|
| type | verbose / debug / info / warn / error |
| tag | 日志tag。 |
| msg | 日志内容。 |
示例：
let debug = huawei.agc.apms.apmsService.setApmsLog("debug", "TEST-LOG", "this is debug");
同意执行日志回捞任务，将会根据回捞任务配置上传日志
grantApmsLog (): void
可参考文档。
示例：
huawei.agc.apms.apmsService.grantApmsLog();
拒绝执行日志回捞任务
denyApmsLog (): void
可参考文档。
示例：
huawei.agc.apms.apmsService.denyApmsLog();
将日志缓存到本地文件
flushApmsLog (): void
可参考文档。
示例：
huawei.agc.apms.apmsService.flushApmsLog();
释放实例
releaseApmsLog (): void
可参考文档。
示例：
huawei.agc.apms.apmsService.releaseApmsLog();
拉取回捞任务
fetchApmsLog (): void
可参考文档。
示例：
huawei.agc.apms.apmsService.once(
huawei.agc.apms.API_EVENT_LIST.fetchApmsLogCallback,
(result) => {
console.log('fetchApmsLog', result);
}
);
huawei.agc.apms.apmsService.fetchApmsLog();
设置是否已同意用户隐私协议
setUserPrivacyAgreed(isAgreed: boolean): void
可参考文档。
示例：
huawei.agc.apms.apmsService.setUserPrivacyAgreed(true);
其他
详细的功能说明，请参考服务指南。