# Flutter SDK接入 APM Flutter SDK基于原生APM SDK，具备采集上报App启动性能、崩溃、卡顿、错误、网络请求、终端设备、自定义上报等应用监控能力。 #### 使用前提 使用SDK前，您需要注册华为账号，并在App监控控制台创建移动端iOS、Android App。 #### 传输协议 HTTPS。 #### 版本更新说明 | 版本号 | 更新说明 | 系统 | |:---|:---|:---| | 1.0.1 | 优化错误摘要。 | Flutter 3.35.6+、Dart 3.9.2+、iOS 15+、Android 7+、Gradle 8.11.1+、AGP：8.9.1+、KGP 2.1.0+、JDK 17+、APM iOS SDK 2.1.0+、APM SDK 2.1.0+ | | 1.0.0 | 提供采集上报App启动性能、崩溃、卡顿、错误、网络请求、终端设备、自定义事件等应用监控能力。 | Flutter 3.35.6+、Dart 3.9.2+、iOS 15+、Android 7+、Gradle 8.11.1+、AGP：8.9.1+、KGP 2.1.0+、JDK 17+、APM iOS SDK 2.1.0+、APM SDK 2.1.0+ | #### 操作步骤 1. 接入SDK。 1. 添加APM Flutter SDK到flutter_app/pubspec.yaml中。相关代码如下： ``` dependencies: ...省略 apm_flutter_plugin: 1.0.1 ``` 2. 添加APM Android SDK到flutter_app/android/build.gradle.kts中。相关代码如下： ``` buildscript { repositories { google() mavenCentral() } ...省略 dependencies { ...省略 classpath("io.github.apm-sdk:apm-sdk-plugin:2.1.0") } } ``` 3. 添加APM Android SDK到flutter_app/android/app/build.gradle.kts中。相关代码如下： ``` plugins { ...省略 id("com.cloud.apm.plugin") } android { ...省略 dependencies { ...省略 implementation("io.github.apm-sdk:apm-sdk-android:2.1.0") } } ``` 4. 添加APM iOS SDK到flutter_app/ios/Podfile中。相关代码如下： ``` pod 'APMSDK', '2.1.0' ``` 2. 添加配置文件。 在创建移动端App过程中，会生成名为apm-sdk-config.json的配置文件，配置文件参数如下： 表1配置参数说明 | 参数名称 | 是否必填 | 默认值 | 描述 | |:---|:---|:---|:---| | 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。 | - iOS App添加配置文件。 1. 用Xcode打开flutter_app/ios/Runner.xcworkspace。 ![](https://support.huaweicloud.com/usermanual-apm2/zh-cn_image_0000002549816173.png) 2. 下载配置文件，拖拽至Runner根目录，并按照下图配置。 ![](https://support.huaweicloud.com/usermanual-apm2/zh-cn_image_0000002549696167.png "点击放大") 3. iOS App添加配置文件成功。 ![](https://support.huaweicloud.com/usermanual-apm2/zh-cn_image_0000002518336320.png) - Android App添加配置文件。 1. 下载配置文件，拖拽至app模块根目录。 ![](https://support.huaweicloud.com/usermanual-apm2/zh-cn_image_0000002518336318.png) 3. 启动SDK。 - 启动APM Flutter SDK。 ``` import 'package:apm_flutter_plugin/apm_flutter_plugin.dart'; void main() { APMFlutterSDK.runApp(() async { // （可选）设置自定义ID APMFlutterSDK.setUid("自定义ID"); // （可选）设置自定义标签 APMFlutterSDK.addTag("自定义标签1,自定义标签2,自定义标签3"); // 运行App return runApp(const MyApp()); }); } ``` - 启动APM Android SDK。 ``` import com.cloud.apm.APMSDK; import com.cloud.apm_flutter_plugin.APMFlutterPlugin; public class MyApplication extends Application { @Override public void onCreate() { super.onCreate(); // 启动APM SDK var extraConfig = new HashMap(); extraConfig.put("crossPlatformUA", APMFlutterPlugin.crossPlatformUA()); APMSDK.start(this, extraConfig); } } ``` 4. 自定义上报统计。 | 方法名称 | 参数说明 | |:---|:---| | static Future\ event(String key, Object value) | key：事件名称，最大长度为2048个字符。 value：事件内容，支持String，List，Map，num，转JSON字符串最大长度为30720个字符。 | 代码示例： ``` // 事件统计 APMFlutterSDK.event("User Information", {"name": "XXX"}); APMFlutterSDK.event("Error Description", "The request timed out."); APMFlutterSDK.event("Call Stack", ["0x0000000101ee9c6c", "0x0000600000e61d80"]); // 数值统计 APMFlutterSDK.event("Custom Load Time", 0.238); APMFlutterSDK.event("Purchase Statistics", 1); ``` #### 混淆配置 如App对代码进行混淆，请在混淆配置文件proguard-rules.pro添加代码： ``` # 请根据App自身要求选择性设置：保留源文件名、源代码行号 -keepattributes LineNumberTable, SourceFile # 防止APM SDK被混淆 -keep class com.cloud.apm_flutter_plugin.** { *; } -keep class com.cloud.apm.** { *; } # 请自行选择使用下面的配置 -keepclasseswithmembers class okhttp3.** { *; } # 使用okhttp3&okhttp -dontwarn okhttp3.** # 未使用okhttp3&okhttp4 -keepclasseswithmembers class com.squareup.okhttp.** { *; } # 使用 okhttp2 -dontwarn com.squareup.okhttp.** # 未使用 okhttp2 ``` #### ASM版本配置 如发生以下编译错误： ``` java.lang.UnsupportedOperationException: NestMember requires ASM7 at org.objectweb.asm.ClassVisitor.visitNestMember(ClassVisitor.java:265) at org.objectweb.asm.ClassReader.accept(ClassReader.java:697) at org.objectweb.asm.ClassReader.accept(ClassReader.java:425) at com.cloud.apm.plugin.tasks.trace.methodTrace.MethodTracer.innerTraceMethodFromJar(MethodTracer.kt:184) at com.cloud.apm.plugin.tasks.trace.methodTrace.MethodTracer.traceMethodFromJar$lambda-4$lambda-3(MethodTracer.kt:89) ``` 请在flutter_app/android/gradle.properties添加如下代码： ``` com.cloud.apm.asmApi=ASM7 ``` #### 数据上报策略 SDK支持四种上报策略：阈值上报、定时上报、应用切后台以及启动时上报。根据场景选择合适的值配置cacheThreshold、timeInterval、reportBackground、reportLaunch等参数。 #### 开启调试日志 在开发过程中可以开启调试日志，借助控制台实时查看SDK运行状况，观察日志并根据需要进行调整。日志级别有：debug、info、warn、error、off（关闭）。 请开发者在App上线前关闭调试日志功能，即设置为off。 示例：在配置文件apm-sdk-config.json中设置日志级别。 ``` { "logLevel": "debug" } ```