性能管理（AppGallery Connect）快速入门

华为 AppGallery Connect（简称 AGC）性能管理（APM，App Performance Management）服务，提供分钟级应用性能监控能力，开发者可以在 AGC 后台查看和分析性能管理服务收集到的应用性能数据，从而全面了解所开发应用的性能特点，快速精准修复应用存在的性能问题，持续提升应用的用户体验。

主要功能

版本更新说明（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.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 远程配置打开性能监控开关，性能管理服务也不会进行性能数据采集。

参数说明：

示例：

huawei.agc.apms.apmsService.enableCollection(true);

设置ANR监控开关

enableAnrMonitor(enable: boolean): void

可参考 停用ANR监控 文档。开关的默认值为打开（true），如果需要停用ANR监控，可将开关设为关闭（false）。

APM性能监控开关优先级高于ANR监控开关，仅在APM性能监控开关打开情况下，ANR监控开关才会生效。

参数说明：

示例：

huawei.agc.apms.apmsService.enableAnrMonitor(true);

为上报数据绑定用户标识（可选）

setUserIdentifier(userIdentifier: string): void

可参考 为上报数据绑定用户标识 文档。为上报数据绑定用户标识，性能数据上报时会一并上报该用户标识，方便单用户问题定位。

参数说明：

示例：

huawei.agc.apms.apmsService.setUserIdentifier('475f5afaxxxxx');

添加自定义跟踪记录（可选）

可参考 添加自定义跟踪记录 文档。自定义跟踪记录可用于监控开发者的应用在特定场景下的性能，如应用登录场景、应用页面长时间无响应场景等。性能管理插件封装后的方法，比起 SDK 原型方法，需要加入 name 参数，用于获取对象调用。若当前名称的对象不存在，则会再新建一个对象。

启动自定义跟踪记录

startCustomTrace(name: string): void

可参考 启动自定义跟踪记录 文档。

参数说明：

示例：

huawei.agc.apms.apmsService.startCustomTrace("traceID");

停止自定义跟踪记录

stopCustomTrace(name: string): void

可参考 停止自定义跟踪记录 文档。

参数说明：

示例：

huawei.agc.apms.apmsService.stopCustomTrace("traceID");

添加自定义属性

putCustomTraceProperty(name: string, propertyName: string, propertyValue: string): void

设置自定义跟踪记录属性名称和属性值。每个 CustomTrace 实例最多只能设置 5 个自定义属性。

参数说明：

示例：

let traceID = "testTrace";
let pName = "product";
let pValue = "food";

huawei.agc.apms.apmsService.putCustomTraceProperty(traceID, pName, pValue);

移除自定义属性

removeCustomTraceProperty(name: string, propertyName: string): void

从 CustomTrace 实例中移除自定义属性。

参数说明：

示例：

let traceID = "testTrace";
let pName = "product";

huawei.agc.apms.apmsService.removeCustomTraceProperty(traceID, pName);

获取自定义属性值

getCustomTraceProperty(name: string, propertyName: string): string

可参考 获取自定义属性值 文档。

参数说明：

示例：

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

增加自定义跟踪记录指标的指标值。如果指标不存在，将创建一个新指标。如果自定义跟踪记录未启动或已停止，接口不生效。

参数说明：

示例：

let traceID = "testTrace";
let mName = "MeasureName";
let mValue = 12000;

huawei.agc.apms.apmsService.incrementCustomTraceMeasure(traceID, mName, mValue);

获取自定义跟踪记录指标值

getCustomTraceMeasure(name: string, measureName: string): string

可参考 获取自定义跟踪记录指标值 文档。

参数说明：

示例：

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

添加自定义跟踪记录指标。如果指标已经存在，则更新指标的值。

参数说明：

示例：

let traceID = "testTrace";
let mName = "MeasureName";
let mValue = 12000;

huawei.agc.apms.apmsService.putCustomTraceMeasure(traceID, mName, mValue);

获取自定义跟踪记录的所有属性

getCustomTraceProperties(name: string): string

获取自定义跟踪记录的所有属性。返回值为 JSON 对象，存放所有属性的键值对。

参数说明：

示例：

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 参数。

参数说明：

示例：

let id = huawei.agc.apms.apmsService.initNetworkMeasure(url, "POST");
console.log("createNetworkMeasure, id = ", id);

设置请求开始时间

startNetworkMeasure(id: string): void

可参考 设置请求开始时间 文档。

参数说明：

示例：

huawei.agc.apms.apmsService.startNetworkMeasure(id);

设置请求结束时间

stopNetworkMeasure(id: string): void

可参考 设置请求结束时间 文档 ，并上报网络请求指标及自定义属性数据。

参数说明：

示例：

huawei.agc.apms.apmsService.stopNetworkMeasure(id);

设置请求的响应码

setNetworkMeasureStatusCode(id: string, statusCode: number): void

可参考 设置请求的响应码 文档。

参数说明：

示例：

huawei.agc.apms.apmsService.setNetworkMeasureStatusCode(id, 500);

设置请求体大小

setNetworkMeasureBytesSent(id: string, length: number): void

可参考 设置请求体大小 文档。

参数说明：

示例：

huawei.agc.apms.apmsService.setNetworkMeasureBytesSent(id, 10000);

设置响应体大小

setNetworkMeasureBytesReceived(id: string, length: number): void

可参考 设置响应体大小 文档。

参数说明：

示例：

huawei.agc.apms.apmsService.setNetworkMeasureBytesReceived(id, 10000);

设置响应体 contentType 类型

setNetworkMeasureContentType(id: string, contentType: string): void

可参考 设置响应体 contentType 类型 文档。

参数说明：

示例：

huawei.agc.apms.apmsService.setNetworkMeasureContentType(id, "contentType1");

设置网络请求的自定义属性名称和属性值

putNetworkMeasureProperty(id: string, propertyName: string, propertyValue: string): void

可参考 设置网络请求的自定义属性名称和属性值 文档。每个 NetworkMeasure 实例最多只能设置 5 个自定义属性。

参数说明：

示例：

let pName = "propName";
let pValue = "12000";
huawei.agc.apms.apmsService.putNetworkMeasureProperty(id, pName, pValue);

从 NetworkMeasure 实例中移除已存在属性

removeNetworkMeasureProperty(id: string, propertyName: string): void

可参考 从 NetworkMeasure 实例中移除已存在属性 文档。

参数说明：

示例：

let pName = "propName";
huawei.agc.apms.apmsService.removeNetworkMeasureProperty(id, pName);

从 NetworkMeasure 实例中获取所有属性

getNetworkMeasureProperties(id: string): string

可参考 从 NetworkMeasure 实例中获取所有属性 文档，返回 JSON 对象。

参数说明：

示例：

let mProp = huawei.agc.apms.apmsService.getNetworkMeasureProperties(id);
console.log("mProp = ", JSON.stringify(mProp));

获取自定义属性值

getNetworkMeasureProperty(id: string, propertyName: string): string

可参考 获取自定义属性值 文档。

参数说明：

示例：

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

可参考文档。

参数

示例：

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);

其他

详细的功能说明，请参考服务指南。