Android Gradle 本地部署

获取SDK

基调听云App SDK目录结构如下：

.
├── bcpkix-jdk15to18-version.jar
├── bcprov-jdk15to18-version.jar
├── nbs.newlens.android.log-version.aar
├── nbs.newlens.nativecrash-version.aar
├── rewriter
│   ├── json-20231013.jar
│   ├── nbs.newlens.so.parser-version.jar
│   ├── tingyun-ea-agent-android-class-rewriter-version.jar
│   └── tingyun-ea-agent-android-gradle-plugin-version.jar
├── shark-version.jar
├── tingyun-android-base-version.aar
├── tingyun-basemonitor-version.aar
├── tingyun-dump-version.aar
├── tingyun-ea-agent-android-version.aar
└── tingyun-javaleak-version.aar

将「tingyun-ea-agent-android-version.aar」、「nbs.newlens.nativecrash-version.aar」、「nbs.newlens.android.log-version.aar」、「tingyun-javaleak-version.aar」、「tingyun-basemonitor-version.aar」、「tingyun-android-base-version.aar」、「 tingyun-dump-version.aar」、「shark-verison.jar」、「bcpkix-jdk15to18-version.jar」、「bcprov-jdk15to18-version.jar」复制到嵌码项目工程的 libs 目录下。

添加插件

1. 在 project 级别的 build.gradle 文件中添加以下内容。

   buildscript {
     dependencies {
       classpath fileTree(dir: 'rewriter', include: ['*.jar'])//将 sdk 的 rewriter 文件夹解压到 project 级别的 build.gradle 文件同级目录下，rewriter 文件夹中的 jar 包仅在编译时使用，不会打包到 apk 中
     }
   }
   
   allprojects {
     repositories {
        flatDir {
           dirs 'libs'// 集成本地 aar 包需添加此配置
        }
     }
   }

2. 在App级别的 build.gradle 文件中添加以下内容。

   apply plugin:'newlens'// 放在 apply plugin: 'com.android.application' 下面
       
   dependencies {
      //请将「Version」更改具体版本号
      implementation(name: 'tingyun-ea-agent-android-version', ext: 'aar') 
      implementation(name: 'nbs.newlens.nativecrash-version', ext: 'aar') // 采集 natvie crash 需集成此包
      implementation(name: 'nbs.newlens.android.log-version', ext: 'aar') // 日志回捞需集成此包
      // 采集 OOM 数据需要 kotlin-gradle-plugin 插件 1.3+ ，并依赖 androidx.core:core-ktx、androidx.appcompat:appcompat、androidx.lifecycle:lifecycle-process、com.squareup.okio:okio 等库
      implementation(name: 'tingyun-javaleak-version', ext: 'aar') // 采集OOM 需集成此包
      implementation(name: 'tingyun-basemonitor-version', ext: 'aar') // 采集 OOM 需集成此包
      implementation(name: 'tingyun-android-base-version', ext: 'aar') // 采集OOM 需集成此包
      implementation(name: 'tingyun-dump-version', ext: 'aar') // 采集 OOM 需集成此包
      implementation files('libs/shark-version.jar') // 采集 OOM 需集成此包
      implementation files('libs/bcpkix-jdk15to18-version.jar') // 启用国密加密需集成此包
      implementation files('libs/bcprov-jdk15to18-version.jar') // 启用国密加密需集成此包
   }

添加SDK

1. 获取基调听云App Key。

2. 初始化SDK。

   i. 在 Application 中的 onCreate() 方法初始化Android SDK。

   //"Appkey" 请从基调听云平台获取
   //"Host" 为基调听云平台「Redirect」服务器地址，无需添加协议头
   // setStartOption(7) 设置首次启动开启网络、用户体验、崩溃采集，仅首次启动生效
   NBSAppAgent.setLicenseKey("AppKey").setRedirectHost("Host").setStartOption(7).start(this.getApplicationContext());  

   ii. SDK默认以HTTPS上传数据，若服务端只支持HTTP，需设置 「setHttpEnabled(true)」。

   NBSAppAgent.setLicenseKey("AppKey").setRedirectHost("Host").setHttpEnabled(true).setStartOption(7).start(this.getApplicationContext());

权限配置说明

基调听云App SDK 为了与服务端交互「网络权限」为必要权限。

<!--必要权限，用以与服务端交互-->
<uses-permission android:name="android.permission.INTERNET"/>
<!--非必要权限，用以获取当前设备的网络状态和WiFi状态，如：2G、3G、4G、WiFi，建议添加-->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<!--非必要权限，用以获取 targentVersion 29 及以上 Android 10 设备的网络状态-->
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<!--非必要权限，用以使用「可视化操作命名功能」-->
<uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW"/>
<uses-permission android:name="android.permission.SYSTEM_OVERLAY_WINDOW"/>
<!--非必要权限，用以获取当前移动网络连接的基站信息-->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>

添加 WebView 配置

说明：自动注入 JS 探针和腾讯「 X5 Webview」配置详情参见接口说明。

采集 WebView 数据需设置 setDomStorageEnabled(true)，还需调用 setWebViewClient() 方法，如嵌码 App 中未调用该方法，请添加以下内容：

  WebSettings webSettings = webview.getSettings();
  webSettings.setDomStorageEnabled(true);
  webview.setWebViewClient(new WebViewClient(){});

• 相关接口

/*
采集 WebView 数据需在 WebChromeClient 的 onProgressChanged() 方法中调用本接口
 */
NBSWebChromeClient.initJSMonitor(view, newProgress);

• 代码示例

webview.setWebChromeClient(new WebChromeClient(){
    @Override
    public void onProgressChanged(WebView view, int newProgress) {
        NBSWebChromeClient.initJSMonitor(view, newProgress);
        super.onProgressChanged(view, newProgress);
    }
});

获取用户标识

通过添加「用户标识」可在基调听云报表平台通过该标识检索到具体用户的性能问题。

• 相关接口

//userIdentifier 最多包含256个字符，支持中文、英文、数字、下划线，但不能包含空格或其他的转义字符
NBSAppAgent.setUserIdentifier(String userIdentifier);

• 代码示例

public class MainActivity extends Activity {  
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        String userIdentifier = getUserID();
        NBSAppAgent.setLicenseKey("AppKey").start(this.getApplicationContext());
        //用户标识可为邮箱、手机号等能够标识用户身份的信息，如：xxx@tingyun.com
        NBSAppAgent.setUserIdentifier(userIdentifier);
      }
}

启用国密加密

SDK 支持国密加密方式发送数据。

注意：

• 国密加密只支持 Android 6.0 及以上版本，启用国密加密后，安卓 5.x 及以下版本 SDK 将不采集数据。

• 启用国密需集成 bcpkix-jdk15to18-version.jar 和 bcprov-jdk15to18-version.jar 。

• 服务端也需要同步开启国密加密功能。

• 相关接口

//isEncryptionRequired 默认 false，设置为 true 启用国密加密
NBSAppAgent.encryptionRequired(boolean isEncryptionRequired)

• 代码示例

NBSAppAgent.setLicenseKey("AppKey").setRedirectHost("Host")
.encryptionRequired(true)// 启用国密加密
.start(this.getApplicationContext());

配置混淆

在proguard混淆配置文件中增加以下内容，以免基调听云App SDK不可用。

# ProGuard configurationsfor NetworkBench Lens
-keep class com.networkbench.** { *; }
-dontwarn com.networkbench.**
-keepattributes Exceptions, Signature, InnerClasses
# End NetworkBench Lens

若项目使用了 OkHttp 3，请在 proguard.cfg 中添加以下内容，以免影响网络指标采集。

-keep class okhttp3.** { *;}
-dontwarn okhttp3.**

若项目启用了国密，请在 proguard.cfg 中添加以下内容，以免影响数据采集。

-keep class org.bouncycastle.**{ *;}
-dontwarn org.bouncycastle.**

若需要保留行号信息，请在 proguard.cfg 中添加以下内容。

-keepattributes SourceFile,LineNumberTable

打包编译

gradle clean build

嵌码验证

嵌码完成后可通过 “LogCat” 查看基调听云App SDK日志输出结果，用以进行数据收集服务器校验 TAG 为 NBSAgent，标准日志输出结果如下所示：

NBSAgent start
NBSAgent enabled
NBSAgent V “TingYun_Version” //TingYun_Version 为当前SDK的版本号
connect success

功能模块开关校验：

嵌码完成后可通过 “LogCat” 查看基调听云App SDK日志输出结果，用以进行功能模块校验，过滤「TAG」为「TingYun」，标准日志输出结果如下所示：

D/TingYun: networkModule is true
D/TingYun: uiModule is true
D/TingYun: crashModule is true
D/TingYun: webviewModule is true
D/TingYun: socketDataModule is true
D/TingYun: crossAppModule is true
D/TingYun: anrModule is true
D/TingYun: userActionModule is true
D/TingYun: cdnModule is false
D/TingYun: recordModule is true
D/TingYun: allTraceCollectModule is true
D/TingYun: violenceModule is true
D/TingYun: logModule is true
D/TingYun: oomModule is true
D/TingYun: batteryModule is true
D/TingYun: batteryErrorEnabled is true
D/TingYun: recordNetworkEnabled is true
D/TingYun: cpuModuleEnabled is true
D/TingYun: fpsModuleEnabled is true

附录（可选配置）

开启可视化命名

开启可视化命名功能，可以通过在App应用内点选的方式为「原生页面」和「操作」进行重命名并在用户体验模块中展示。

1. 获取 Scheme。

   在应用「设置」中的「修改设置」中选择【URL Scheme】。

   

2. 在 AndroidMainfest.xml 文件的「LAUNCHER Actvitiy」中增加 scheme 配置，如下所示：

   <activity android:name=".MainActivity">
      <intent-filter>
         <action android:name="android.intent.action.MAIN" />
         <category android:name="android.intent.category.LAUNCHER" />
      </intent-filter>
      <!--请添加这里的整个intent-filter区块，并确保其中只有一个data字段-->
      <intent-filter>
         <data android:scheme="tingyun.xxxx" />
         <!--请将 scheme 中的“tingyun.xxxx”替换为基调听云报表设置页面中的 URL Scheme-->
         <action android:name="android.intent.action.VIEW"/>
         <category android:name="android.intent.category.DEFAULT"/>
         <category android:name="android.intent.category.BROWSABLE"/>
      </intent-filter>
      <!--请添加这里的整个intent-filter区块，并确保其中只有一个data字段-->
   </activity>