# Harmony SDK接入 APM Harmony SDK拥有以下应用监控能力：采集上报App崩溃、卡顿、错误信息、网络请求、终端设备、自定义事件等。 #### 支持平台 API 12及以上。 #### 传输协议 HTTPS #### 版本更新说明 - SDK如何处理个人信息，请参考[应用性能管理服务数据采集SDK隐私声明](https://support.huaweicloud.com/usermanual-apm2/apm_07_0168.html)。 - 您集成和使用华为的SDK时，需要遵从个人信息保护基本要求，详情请参考[应用性能管理服务数据采集SDK开发者合规指南](https://support.huaweicloud.com/usermanual-apm2/apm_07_0169.html)。 表1版本更新说明 | 版本号 | SDK下载地址 | 更新说明 | 系统 | |:---|:---|:---|:---| | 2.0.6 | SDK[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm_harmony_sdk_2.0.6.har) | - 解决用户在初始化之后setUid和setTag不生效的问题。 - 解决用户ID在特殊场景下自动刷新的问题。 - 封装HTTP请求方法，监听HTTP请求下的API数据。 | API 12 及以上 | | 2.0.5 | SDK[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm_harmony_sdk_2.0.5.har) | 解决setUid和setTag方法被混淆的问题。 | API 12 及以上 | | 2.0.3 | SDK[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm_harmony_sdk_2.0.3.har) | - 添加参数校验。 - 添加调试日志。 | API 12 及以上 | | 2.0.2 | SDK[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-android-sdk-2.0.4.aar) | 解除SDK中对其他包的依赖。 | API 12 及以上 | | 2.0.1 | SDK[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm_harmony_sdk_2.0.1.har) | 提供采集上报App启动性能、崩溃、卡顿、错误、网络请求、终端设备、自定义上报等应用监控能力。 | API 12 及以上 | #### 集成SDK 1. 项目引入Harmony SDK。 - 方法一：从Harmony仓库拉取SDK。 1. 使用如下命令，从Harmony仓库拉取SDK。 ``` ohpm install apm_harmony_sdk ``` 2. 配置文件中添加依赖并引入SDK。 ``` 在app/oh-package.json5中添加依赖 dependencies { ... "apm_harmony_sdk": "2.0.6" ... } // 在终端中运行以下命令安装SDK ohpm install ``` - 方法二：手动引入SDK。 1. 下载[应用性能监控SDK包](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm_harmony_sdk_2.0.3.har)。 2. 将下载到的har静态库文件添加到您的项目工程中（以下以根目录下的plugin文件夹为例）。 3. 在app/oh-package.json5文件中添加依赖。 ``` dependencies { ... "apm_harmony_sdk": "file:../plugin/apm_harmony_sdk.har" // HAR包存放地址 ... } ``` 4. 在终端中运行以下命令使能SDK。 ``` ohpm install ``` 2. 数据上报与获取网络状态需要在module.json5中打开相关权限，文件路径application \> src \> main \> module.json5。 ``` "requestPermissions":[ { "name": "ohos.permission.INTERNET" }, { "name": "ohos.permission.GET_NETWORK_INFO" } ], ``` #### 配置参数 1. 登录APM控制台，创建Harmony App应用，详细操作参见[Harmony接入APM](https://support.huaweicloud.com/usermanual-apm2/apm_02_0033.html)。 2. 下载配置文件apm-sdk-config.json，并将文件拖入项目资源目录中，项目资源目录路径"src \> main \> resources \> rawfile"。 表2配置参数说明 | 参数名称 | 是否必填 | 默认值 | 描述 | |:---|:---|:---|:---| | appId | 是 | - | 移动端AppID。 | | authorization | 是 | - | 用于App的匹配。 | | region | 是 | - | 上报APM所处的region，目前支持cn-north-4。 | | uid | 否 | - | 用户自定义ID。 | | tag | 否 | - | 用户自定义标签，多个时使用英文逗号隔开。 | | url | 否 | - | 要上报APM的公网地址域名。 | | networkWhiteList | 否 | - | 网络监控白名单，排除监控。 | | cacheThreshold | 否 | 200条 | 当本地数据库存储条数达到该值会触发上报，取值范围为30-1000条。 | | timeInterval | 否 | 60秒 | 定时器每隔该值会触发上报，取值范围为60-1800秒。 | | reportBackground | 否 | true | 是否开启APP切后台上报功能。 | | reportLaunch | 否 | false | 是否开启APP启动时上报功能。如需开启，请在UIApplicationDidFinishLaunchingNotification通知发送前启动SDK。 | | enableNetwork | 否 | false | 是否开启网络采集。 | | enableCrash | 否 | false | 是否开启崩溃采集。 | | enableLaunch | 否 | false | 是否开启启动采集。 | | enableANR | 否 | false | 是否开启卡顿采集。 | | enableError | 否 | false | 是否开启错误采集。 | | enableDevice | 否 | false | 是否开启终端设备采集。 | | enableEvent | 否 | false | 是否开启用户自定义上报。 | | traceType | 否 | apm | 链路追踪类型。 - 开启：otel。 - 关闭：apm。 | | logLevel | 否 | off | 调试日志等级。 - debug - info - warn - error - off | | samplingRate | 否 | 1.0 | 采样率，取值范围0\~1.0。 | #### SDK使能 1. 引入依赖模块。 ``` import { APMSDK } from "apm_harmony_sdk"; ``` 2. 启动及自定义参数设置。 ``` // 启动SDK，在onCreate函数中添加以下代码： APMSDK.start(this.context.getApplicationContext()); // 设置自定义ID APMSDK.setUid(自定义ID); // 设置自定义标签 APMSDK.addTag(自定义标签); ``` #### 其他方法 1. 自定义上报错误数据。 ``` // 在try...catch...中添加捕获错误并上报到APM平台 // 1.捕获Error类型 import { APMSDK } from "apm_harmony_sdk"; try { ... } catch(e) { APMSDK.reportError(e); } // 2.捕获BusinessError类型 const response = await session.fetch(request).then((rep: rcp.Response) => { ... }).catch((err: BusinessError) => { ... APMSDK.reportBusinessError(err); }); ``` 2. 使用rcp拦截器，上报API数据到APM平台。 ``` // 代码示例： import { APMRcpInterceptor, ResponseCache } from "apm_harmony_sdk"; async function testInterceptor() { const cache: ResponseCache = new ResponseCache(); const session = rcp.createSession({ interceptors: [new APMRcpInterceptor(cache)] }); const response = await session.get('上报地址'); } ``` 3. 自定义埋点，主动上报数据。 ``` // APMCallbackHttp：监听带有url,OPTIONS,CALLBACK三个参数的请求 import { APMCallbackHttp } from "apm_harmony_sdk"; try { APMCallbackHttp( // 填写HTTP请求的URL地址，可以带参数也可以不带参数。URL地址需要开发者自定义。请求的参数可以在extraData中指定 "EXAMPLE_URL", { method: http.RequestMethod.GET, // 可选，默认为http.RequestMethod.GET // 开发者根据自身业务需要添加header字段 header: { 'Content-Type': 'application/json' }}, (err: BusinessError, data: http.HttpResponse) => { if (!err) { // data.result为HTTP响应内容，可根据业务需要进行解析 console.info('Result:' + JSON.stringify(data.result)); console.info('code:' + JSON.stringify(data.responseCode)); // data.header为HTTP响应头，可根据业务需要进行解析 console.info('header:' + JSON.stringify(data.header)); console.info('cookies:' + JSON.stringify(data.cookies)); // 8+ } else { console.error('error:' + JSON.stringify(err)); } }); } catch (e) { console.log(e); } // APMPromiseHttp：监听带有url,OPTIONS两个参数返回PROMISE的请求 import { APMPromiseHttp } from "apm_harmony_sdk"; try { let httpRequest = http.createHttp(); const res = await APMPromiseHttp( // 填写HTTP请求的URL地址，可以带参数也可以不带参数。URL地址需要开发者自定义。请求的参数可以在extraData中指定 "http://EXAMPLE_URL/apm2/web/cmdb/business/v1/test2", { method: http.RequestMethod.GET, // 可选，默认为http.RequestMethod.GET // 开发者根据自身业务需要添加header字段 header: { 'Content-Type': 'application/json' }}); console.log('res:' + JSON.stringify(res)); } catch (e) { console.log(e); } ```