Flutter SDK接入

使用前提

使用SDK前，您需要注册华为账号，并在App监控控制台创建移动端iOS、Android App。

传输协议

HTTPS。

版本更新说明

操作步骤

1. 接入SDK。
   1. 添加APM Flutter SDK到flutter_app/pubspec.yaml中。相关代码如下：

      dependencies:  
      ...省略
         apm_flutter_plugin: 1.0.0

   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的配置文件，配置文件参数如下：

   参数名称	是否必填	默认值	描述
   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启动时上报功能。
   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。

        

     2. 下载配置文件，拖拽至Runner根目录，并按照下图配置。

        

     3. iOS App添加配置文件成功。

        

   • Android App添加配置文件。
     1. 下载配置文件，拖拽至app模块根目录。

        

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<String, Object>();         
              extraConfig.put("crossPlatformUA", APMFlutterPlugin.crossPlatformUA());         
              APMSDK.start(this, extraConfig);
          } 
     }

4. 自定义上报统计。

   方法名称	参数说明
   static Future<void> 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"
}