Android应用接入
简介
DataFlux 应用监测能够通过收集各个Android应用的指标数据,以可视化的方式分析各个Android应用端的性能。
前置条件
- 安装 DataKit(DataKit 安装文档)
- 配置 RUM 数据采集
Android 应用接入
登录 DataFlux 控制台,进入「应用监测」页面,点击右上角「新建应用」,在新窗口输入「应用名称」,点击「创建」,即可开始配置。
安装
Gradle 配置
在项目的根目录的 build.gradle 文件中添加 DataFlux SDK 的远程仓库地址
buildscript {
//...省略部分代码
repositories {
//...省略部分代码
//添加 DataFlux SDK 的远程仓库地址
maven {
url 'https://mvnrepo.jiagouyun.com/repository/maven-releases'
}
}
dependencies {
//...省略部分代码
//添加 DataFlux Plugin 的插件依赖
classpath 'com.cloudcare.ft.mobile.sdk.tracker.plugin:ft-plugin:[ latest version ]'
}
}
allprojects {
repositories {
//...省略部分代码
//添加 DataFlux SDK 的远程仓库地址
maven {
url 'https://mvnrepo.jiagouyun.com/repository/maven-releases'
}
}
}
在项目主模块( app 模块)的 build.gradle 文件中添加 DataFlux SDK 的依赖及 DataFlux Plugin 的使用 和 Java 8 的支持
dependencies {
//添加 DataFlux SDK 的依赖
implementation 'com.cloudcare.ft.mobile.sdk.tracker.agent:ft-sdk:$last_version'
//捕获 native 层崩溃信息的依赖,需要配合 ft-sdk 使用不能单独使用
implementation 'com.cloudcare.ft.mobile.sdk.tracker.agent:ft-native:$last_version'
//推荐使用这个版本,其他版本未做过充分兼容测试
implementation 'com.google.code.gson:gson:2.8.5'
}
//应用插件
apply plugin: 'ft-plugin'
//配置插件使用参数
FTExt {
//是否显示 Plugin 日志,默认为 false
showLog = true
}
android{
//...省略部分代码
defaultConfig {
//...省略部分代码
ndk {
//当使用 ft-native 捕获 native 层的崩溃信息时,应该根据应用适配的不同的平台
//来选择支持的 abi 架构,目前 ft-native 中包含的 abi 架构有 'arm64-v8a',
// 'armeabi-v7a', 'x86', 'x86_64'
abiFilters 'armeabi-v7a'
}
}
compileOptions {
sourceCompatibility = 1.8
targetCompatibility = 1.8
}
}
最新的版本请看上方的 Agent 和 Plugin 的版本名
SDK 参数配置
配置项说明
功能说明
方法名 | 含义 | 是否必须 | 注意 |
---|---|---|---|
setUseOAID | 是否使用OAID作为设备唯一识别号的替代字段 | 否 | 默认不使用,开启后全会替代 deviceUUID 进行使用 了解 OAID |
setXDataKitUUID | 设置数据采集端的名称 | 否 | 不设置该值系统会生成一个默认的 uuid |
setDebug | 是否开启调试模式 | 否 | 默认不开启,开启后方可打印 SDK 运行日志 |
setMonitorType | 设置辅助监控信息 | 否 | 添加附加监控数据到Rum 崩溃数据采集中 |
metricsUrl | metrics 写入地址 | 是 | 必须配置,配置后才能上报 |
setEnableTrackAppCrash | 是否开启 App 崩溃日志上报功能 | 否 | 默认不开启,开启后将上报当前应用的崩溃日志。上报成功后,可以在后台的日志模块查看对应的日志。 关于崩溃日志中混淆内容转换的问题 |
setEnableTrackAppANR | 是否开启 App ANR 检测 | 否 | 默认不开启,开启后上报 ANR 数据信息 |
setServiceName | 设置崩溃日志的名称 | 否 | 默认为 dataflux sdk 。你可以将你的应用名称设置给该字段,用来区分不同的日志 |
setEnv | 设置崩溃日志中显示的应用的环境 | 否 | 默认情况下会获取应用当前的环境。如:debug 、release |
setSampleRate | 设置采集率 | 否 | 采集率的值范围为>=0、<=1,默认值为1。说明:SDK 初始化是会随机生成一个0-1之间的随机数,当这个随机数小于你设置的采集率时,那么会上报当前设备的行为相关的数据,否则就不会上报当前设备的行为数据 |
setTraceConsoleLog | 是否开启本地打印日志上报功能 | 否 | 当开启后会将应用中打印的日志上报到后台,日志等级对应关系 Log.v -> ok; Log.i、Log.d -> info; Log.e -> error; Log.w -> warning |
setNetworkTrace | 是否开启网络追踪功能 | 否 | 开启后,可以在 web 中“日志”查看到对应日志的同时也可以在“链路追踪”中查找到对应的链路信息 |
setTraceType | 设置链路追踪所使用的类型。 | 否 | 目前支持 Zipkin 和 Jaeger 两种,默认为 Zipkin |
setEventFlowLog | 设置是否开启页面事件的日志 | 否 | 可以在 web 版本日志中,查看到对应上报的日志,事件支持启动应用,进入页面,离开页面,事件点击等等 |
setOnlySupportMainProcess | 设置是否只支持在主进程中初始化 | 否 | 默认是 true ,默认情况下 SDK 只能在主进程中运行。如果应用中存在多个进程,那么其他进程中将不会执行。如果需要在其他进程中执行需要将该字段设置为 true |
setLogCacheDiscardStrategy | 设置频繁日志丢弃规则 | 否 | 默认为 LogCacheDiscard.DISCARD ,丢弃往后追加的数据 |
setRumAppId | 设置 Rum AppId |
否 | 对应设置 RUM appid ,才会开启 RUM 的采集功能,appId 需要从 DataFlux "应用监测" 创建应用获取,获取 appid 方法 |
用户信息绑定
方法说明表
方法名 | 含义 | 是否必须 | 注意 |
---|---|---|---|
install | 安装初始化配置项 | 是 | 在项目 application 中运行 |
get | 获得安装后创建的 FTSdk 对象 | 否 | 应该在 install 运行后调用 |
unbindUserData | 解绑用户信息 | 否 | |
bindUserData | 绑定用户信息 | 否 | |
shutDown | 关闭SDK中正在执行的操作 | 否 |
示例代码
class DemoAplication : Application() {
private val serverUrl = "serverUrl"
override fun onCreate() {
super.onCreate()
val ftSDKConfig = FTSDKConfig.builder(
serverUrl//服务器地址
).setUseOAID(true)//是否使用OAID
.setDebug(true)//是否开启Debug模式(开启后能查看调试数据)
.setXDataKitUUID("ft-dataKit-uuid-001")
.setRumAppId("appIdxxxxxx")
.setEnableTrackAppCrash(true)
.setEnv(EnvType.GRAY)
.setTraceType(TraceType.ZIPKIN)
.setTraceSamplingRate(0.5f);//设置采样率
FTSdk.install(ftSDKConfig)
}
}
//可以在用户登录成功后调用此方法用来绑定用户信息
bind_user.setOnClickListener {
FTSdk.get().bindUserData("001")
}
//可以在用户退出登录后调用此方法来解绑用户信息
unbind_user.setOnClickListener {
FTSdk.get().unbindUserData()
}
主动日志上报
方法说明表
方法名 | 含义 | 是否必须 | 注意 |
---|---|---|---|
logBackground | 自定义日志 | 否 | 日志过快会触发丢弃机制 |
示例代码
//上传单个日志
FTLogger.getInstance().logBackground("test", Status.INFO)
//批量上传日志
FTLogger.getInstance().logBackground(mutableListOf(LogData("test1",Status.INFO)))
Proguard 混淆配置
-keep class ftnative.NativeHandler {
native <methods>;
void crashCallback(...);
void traceCallback(...);
}
-keep class ftnative.NativeCrash{
*;
}
-keep class ftnative.NativeCrash$InitParameters{
*;
}
-keep class com.bun.miitmdid.core.**{*;}
-keep class * extends com.ft.sdk.garble.http.ResponseData{
*;
}
权限配置
DataFlux SDK 用到了系统的四个权限,分别为 READ_PHONE_STATE
、WRITE_EXTERNAL_STORAGE
、ACCESS_FINE_LOCATION
权限使用说明
名称 | 使用原因 |
---|---|
READ_PHONE_STATE |
用于获取手机的设备信息,便于精准分析数据信息 |
WRITE_EXTERNAL_STORAGE |
用户存储缓存数据 |
ACCESS_FINE_LOCATIO |
获取当前位置所属城市,非必须 |
关于如何申请动态权限,具体详情参考Android Developer
方法
FTSDK
SDK 初始化
class FTSDK{
/**
* SDK 配置项入口
* @param ftSDKConfig 配置项参数
* @return
*/
public static synchronized FTSdk install(FTSDKConfig ftSDKConfig);
/**
* SDK 初始化后,获得 SDK 对象
* @return
*/
public static synchronized FTSdk get();
/**
* 注销用户信息
*/
public void unbindUserData();
/**
* 绑定用户信息
* @param name 用户名
* @param id 用户唯一标识 ID
* @param exts 其他参数
*/
public void bindUserData(@NonNull String id);
/**
* 设置开启网络请求追踪
* @param networkTrace
*/
public void setNetworkTrace(boolean networkTrace);
}
FTSDKConfig
条件配置类
class FTSDKConfig{
/**
* 构建 SDK 必要的配置参数(当不需要签名时可以用此方法)
* @param metricsUrl 服务器地址
* @return
*/
public static FTSDKConfig builder(String metricsUrl);
/**
* 构建 SDK 必要的配置参数
* @param metricsUrl 服务器地址
* @param enableRequestSigning 是否需要对请求进行签名
* @param akId 签名 id,当 enableRequestSigning 为 true 时必须设置
* @param akSecret 签名 Secret,当 enableRequestSigning 为 true 时必须设置
* @return
*/
public static FTSDKConfig builder(String metricsUrl, boolean enableRequestSigning, String akId, String akSecret);
/**
* 是否使用 UseOAID 作为设备唯一识别号的替代字段
* @param useOAID
* @return
*/
public FTSDKConfig setUseOAID(boolean useOAID);
/**
* 是否开启Debug,开启后将显示 SDK 运行日志
* @param debug
* @return
*/
public FTSDKConfig setDebug(boolean debug);
}
MonitorType
监控配置项类
public class MonitorType {
//所有配置
public static int ALL = 1;
//电池(电池总量、电池使用量)
public static int BATTERY = 1<<1;
//内存(内存总量、内存使用率)
public static int MEMORY = 1<<2;
//CPU(CPU 占用率)
public static int CPU = 1<<3;
//GPS 是否开启
public static int LOCATION = 1<<7;
//蓝牙
public static int BLUETOOTH = 1<<10;
//屏幕帧率
public static int FPS = 1 << 19;
}
常见问题
关于 OAID
介绍
在 Android 10
版本中,非系统应用将不能获取到系统的 IMEI
、MAC
等信息。面对该问题移动安全联盟联合国内的手机厂商推出了
补充设备标准体系方案,选择用 OAID
字段作为IMEI等系统信息的替代字段。OAID
字段是由中国信通院联合华为、小米、OPPO、
VIVO 等厂商共同推出的设备识别字段,具有一定的权威性。目前 DataFlux SDK 使用的是 oaid_sdk_1.0.22.aar
关于 OAID 可移步参考移动安全联盟
使用
使用方式和资源下载可参考移动安全联盟的集成文档
示例
下载好资源文件后,将 oaid_sdk_1.0.22.aar 拷贝到项目的 libs 目录下,并设置依赖 获取最新版本
将下载的资源中的 supplierconfig.json
文件拷贝到主项目的 assets
目录下,并修改里面对应的内容,特别是需要设置 appid
的部分。需要设置 appid
的部分需要去对应厂商的应用商店里注册自己的 app
。
设置依赖
implementation files('libs/oaid_sdk_1.0.22.arr')
混淆设置
-keep class com.bun.miitmdid.core.**{*;}
设置 gradle
编译选项,这块可以根据自己的对平台的选择进行合理的配置
ndk {
abiFilters 'armeabi-v7a','x86','arm64-v8a','x86_64','armeabi'
}
packagingOptions {
doNotStrip "*/armeabi-v7a/*.so"
doNotStrip "*/x86/*.so"
doNotStrip "*/arm64-v8a/*.so"
doNotStrip "*/x86_64/*.so"
doNotStrip "armeabi.so"
}
以上步骤配置完成后,在配置 FT SDK 时调用 FTSDKConfig 的 setUseOAID(true) 方法即可
HttpClient RUM 问题
目前 HttpClient
无法做到 RUM
网络请求的性能分析,目前只支持 okhttp3
做网络数据的追踪
日志混淆内容转换
问题描述
当你的应用发生崩溃且你已经接入 DataFlux SDK
同时你也开启了崩溃日志上报的开关时,你可以到 DataFlux
后台你的工作空间下的日志模块找到相应
的崩溃日志。如果你的应用开启了混淆,此时你会发现崩溃日志的堆栈信息也被混淆,无法直接定位具体的崩溃位置,因此你需要按以下方式来解决该问题。
解决方式
找到 mapping 文件。如果你开启了混淆,那么在打包的时候会在该目录下(
module-name
->build
->outputs
->mapping
)生成一个混淆文件映射表(mapping.txt
),该文件就是源代码与混淆后的类、方法和属性名称之间的映射。因此每次发包后应该根据应用的版本号保存好对应mapping.txt
文件,以备根据后台日志tag
中的版本名字段(app_version_name
)来找到对应mapping.txt
文件。下载崩溃日志文件。到 DataFlux 的后台中把崩溃日志下载到本地,这里假设下载到本地的文件名为
crash_log.txt
运行
retrace
命令转换崩溃日志。Android SDK
中自带retrace
工具(该工具在目录sdk-root/tools/proguard
下,windows
版本是retrace.bat,Mac/Linux
版本是retrace.sh
),通过该工具可以恢复崩溃日志的堆栈信息。命令示例retrace.bat -verbose mapping.txt crash_log.txt
上一步是通过
retrace
命令行来执行,当然也可以通过GUI
工具。在<sdk-root>/tools/proguard/bin
目录下有个proguardgui.bat
或proguardgui.sh
GUI 工具。运行proguardgui.bat
或者./proguardgui.sh
-> 从左侧的菜单中选择“ReTrace
” -> 在上面的Mapping file
中选择你的mapping
文件,在下面输入框输入要还原的代码 ->点击右下方的“ReTrace!
”