Ingest Android app monitoring data

Step 1: Integrate the SDK

You can integrate the SDK automatically or manually.

(Recommended) Automatic integration

1. Add the following configuration to your project-level build.gradle file.

   buildscript {
       repositories {
           google()
           jcenter()
           mavenCentral()
       }
   }
   allprojects {
       repositories {
           google()
           jcenter()
           mavenCentral()
       }
   }

2. Add the following configuration to your app-level build.gradle file.

   android {
      defaultConfig {
          ndk {
              // Specify the supported SO library architectures. If this is not set, all architectures are supported by default.
              abiFilters 'armeabi' //, 'armeabi-v7a', 'arm64-v8a', 'x86', 'x86_64'
          }
      }
   }
   dependencies {
       // For Gradle 3.0 and later, use implementation.
       // latest.release refers to the latest SDK version. We recommend that you pin an explicit version.
       implementation 'com.aliyun.openservices:aliyun-log-android-sdk:latest.release'
       implementation'com.aliyun.openservices:sls-android-core:latest.release'
       implementation'com.aliyun.openservices:sls-android-ot:latest.release'
       implementation'com.aliyun.openservices:sls-android-crashreporter:latest.release'
   }

Manual integration

Step 2: Configure permissions

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

Step 3: Configure obfuscation

If your project uses code shrinking and obfuscation, you must configure rules to prevent the SDK from being stripped. In your obfuscation rules, keep all class and method names under the com.uc.crashsdk package. For example, add the following configuration to your proguard.cfg file:

-keep class com.uc.crashsdk.** { *; }
-keep interface com.uc.crashsdk.** { *; }
-keep class com.aliyun.sls.android.producer.* { *; }
-keep interface com.aliyun.sls.android.producer.* { *; }
-keep class com.aliyun.sls.android.** { *; }

Step 4: Configure the service

1. Add the Application class to the $PROJECT/app/src/main/AndroidManifest.xml file.

   For example, to add a SLSDemoApplication class, your configuration would look like this:

   <manifest xmlns:android="http://schemas.android.com/apk/res/android"
             package="com.aliyun.sls.android.demo">
       ...
       <application
           android:icon="@mipmap/ic_launcher"
           ...
           android:name="com.aliyun.sls.android.demo.SLSDemoApplication"
           ...
           android:theme="@style/AppTheme">
               ...
       </application>
   </manifest>

   Your IDE, such as Android Studio, will prompt you to automatically create the specified class in your project.

2. In the MyApplication.onCreate method, add the following initialization code.

   public class MyApplication extends Application {
       @Override
       public void onCreate() {
           super.onCreate();
           Credentials credentials = new Credentials();
           credentials.instanceId = "your instance id";
           credentials.endpoint = "your endpoint";
           credentials.project = "your project";
           credentials.accessKeyId = "your access key id";
           credentials.accessKeySecret = "your access key secret";
           SLSAndroid.initialize(
               this,
               credentials,
               configuration -> {
                   // Enable the crash capture feature.
                   configuration.enableCrashReporter = true;
                   // Enable the block detection feature.
                   configuration.enableBlockDetection = true;
               }
           );
       }
   }

   • Credentials

     The Credentials class holds the parameters for authentication and connection.

     Type	Field	Example	Description
     Configuration parameters	instanceId	sls-****d60f	The ID of the application that you added in the Log Service console. For more information, see Obtain an application ID.
     	endpoint	https://cn-hangzhou.log.aliyuncs.com	The endpoint of the Log Service Project. You must add the https:// prefix. To obtain the endpoint, see Endpoints. Important Only public service endpoints are supported.
     	project	sls-ayasls-demo	The Log Service Project associated with your application. For more information, see Add Application.
     Authentication parameters	accessKeyId	LTAI****eYDw	The AccessKey ID for the Log Service Project. For more information, see AccessKey pair.
     	accessKeySecret	lrRq****GOVM	The AccessKey Secret for the Log Service Project. For more information, see AccessKey pair.
     	securityToken	124f****a369	The security token for accessing the Log Service Project. This is required when you use STS for authentication. To obtain the token, see AssumeRole.

   • SLSAndroid

     The SLSAndroid class provides interfaces for SDK initialization, credential updates, and user information configuration.

     Type	Field or method	Description
     Debug method	setLogLevel	Sets the log level for the SDK. Valid values include Log.VERBOSE, Log.DEBUG, Log.INFO, Log.WARN, and Log.ERROR.
     Credential update	setCredentials	Updates the credential information in the Credentials object. Updates take effect immediately, without restarting the SDK.
     Configuration method	setUserInfo	Updates user information.

   • Configuration

     The Configuration class lets you customize SDK behavior during initialization.

     Type	Field/method	Description
     Configuration methods	enableCrashReporter	Enables or disables the crash capture feature.
     	enableBlockDetection	Enables or disables the block detection feature.
     	spanProvider	Customizes the resource and attribute information for spans.
     Environment configuration	env	The environment of the application. The default value is default. Typically, you can set this to dev for development environments and prod for production environments.

3. Use STS to configure credentials.accessKeyId, credentials.accessKeySecret, and credentials.securityToken.

   public class MyApplication extends Application {
       @Override
       public void onCreate() {
           super.onCreate();
           Credentials credentials = new Credentials();
           // The instanceId is a required parameter.
           credentials.instanceId = "your instance id";
           // The following parameters are optional.
           credentials.endpoint = "your endpoint";
           credentials.project = "your project";
           credentials.accessKeyId = "your access key id";
           credentials.accessKeySecret = "your access key secret";
           SLSAndroid.initialize(
               this,
               credentials,
               configuration -> {
                   // Enable the crash capture feature.
                   configuration.enableCrashReporter = true;
                   // Enable the block detection feature.
                   configuration.enableBlockDetection = true;
               }
           );
       }
       // After you obtain request-related information, you can call the following API.
       private void onUpdateSLS() {
           Credentials credentials = new Credentials();
           // (Optional) Update the AccessKey.
           credentials.accessKeyId = "your access key id";
           credentials.accessKeySecret = "your access key secret";
           credentials.securityToken = "your access security token";
           // (Optional) Update the Project and other information.
           credentials.endpoint = "your endpoint";
           credentials.project = "your project";
           SLSAndroid.setCredentials(credentials);
       }
   }

Step 5: Verify the integration

1. In the MyApplication.onCreate method, call SLSAndroid.setLogLevel(Log.DEBUG); to enable logging for the plugin.

   For more information, see Step 4: Configure the service.

2. Write test code to simulate or trigger a mobile app crash.

   Common types of crashes include:

   • Null pointer exception

     private void crashInJavaNull() {
         String nullStr = "1";
         if (nullStr.equals("1")) {
             nullStr = null;
         }
         nullStr.equals("");
     }

   • Class cast exception

     private void crashInJavaClassCast() {
         View view = new View(this);
         TextView text = (TextView)view;
     }

   • Out-of-bounds exception

     private void crashInJavaOutOfBounds() {
         new ArrayList<>(10).get(11);
     }

   • Native crash

     JNIBridge.nativeCrash(0, 0);

   • Native abort

     JNIBridge.nativeCrash(2, 0);

   • ANR

     while (true) {
         try {
             Thread.sleep(1);
         } catch (InterruptedException e) {
             e.printStackTrace();
         }
     }

3. Restart the mobile client, and after about 2 minutes, you can view the crash information in the target LogStore on the Log Service console.

   On the Custom Query page of the target mobile O&M monitoring instance, click Query/Analysis. If logs are displayed, this indicates that data has been successfully ingested. In the left navigation bar of the mobile O&M monitoring console, select Custom Query, select the target LogStore, set a time range, and then click the Query/Analysis button. If the total number of logs is greater than 0 and the query status is displayed as "Accurate Result", this indicates that crash information has been successfully reported to Log Service.