SDK Integration for Mobile Applications

1 CrashSight Integration on Mobile Devices

2 iOS SDK Integration

2.1 CocosPods Integration

1. Add pod ‘CrashSight’ to your Podfile.

2. Run pod install or pod update.

3. Import <CrashSight/CrashSight.h>

2.2 Manual Integration

1. Download CrashSight SDK (Download is unavailable due to an ongoing internal review. To download it, please contact WeTest@wetest.net).

2. Add iOS SDK Dependencies

• Drag the CrashSight.framework file into the Xcode project (Select “Copy items if needed”)
• Add dependency library SystemConfiguration.framework, Security.framework,libz.dylib, or libz.tdb, libc++.dylib or libc++.tdb (You can add none if no error message appears.)

2.3 SDK Initialization

• Import header file
  #import <CrashSight/CrashSight.h>
  in the project’s AppDelegate.m file (If it is a Swift project, import the file in bridging-header.h)

• Initialization: Initialize in the

application:didFinishLaunchingWithOptions:

method of the project’s AppDelegate.m file

CrashSightConfig* config = [[CrashSightConfig alloc] init];
//  Customize the domain name for reporting (optional)
config.crashServerUrl = @"http://xxxx";
config.appId = @"appId";
[CrashSight startWithAppId:appid config:config];

Domain name for reporting

• Domestic public cloud https://ios.crashsight.qq.com/pb/sync
• Overseas public cloud https://ios.crashsight.wetest.net/pb/sync

2.4 Integration Result Testing

• a. Enable Debug mode. Initialize CrashSight and assign suitable config parameters
• b. Network and report: Check if “begin to upload <CSAnalyticsLogic” or “cmd: 641” is printed in the test device log
• c. Crash detection: Check if “Handle the crash scene in callback” is printed in the test device log
• d. Report exceptions: Check if “begin to upload <CSCrashLogic” or “cmd: 631” is printed in the test device log

3 Android SDK Integration

Maven Integration

a. Add Tencent maven mirror to the project's build.gradle:

allprojects {
    repositories {
        maven { 
            url "https://mirrors.tencent.com/nexus/repository/maven-public" 
        }
    }
}

b. Add dependencies to the build.gradle module:

dependencies {
    implementation 'net.crashsight:crashsight-android:latest.release'
}

Manual Integration

Download CrashSight SDK (Download is unavailable due to an ongoing internal review. To download it, please contact WeTest@wetest.net).

• If your project has Native code (C/C++) or has other third-party shared libraries integrated, it’s recommended to download CrashSight’s NDK dynamic library. CrashSight NDK contains shared libraries of various architecture:
• armeabi
• armeabi-v7a
• arm64-v8a
• x86
• x86_64

When integrating CrashSight shared libraries, please only keep shared libraries with supported architecture.

Eclipse Project

• Copy the CrashSight library file to the project’s libs directory.

• Refresh the project.

• Add project dependency: Right-click the JAR file of CrashSight and add it to compilation path.

Android Studio Project

• Copy the CrashSight library file to the project’s libs directory.
• To integrate CrashSight NDK, add shared library directory configurations to Module’s buid.gradle file.

android {
    sourceSets {
        main.jniLibs.srcDirs = ['libs']
    }
}

• Click Sync to sync configurations.

To improve readability of APP Crash stack, it’s recommended to configure symbol table file to better locate issues:

• Java-only projects: Just configure the Mapping file generated after obfuscation.
• Projects containing Native code: it’s recommended to configure the Symbol symbol table file extracted by symbol table tools from Debug SO. CrashSight supports manual and auto configurations. For detailed configuration process, please see: “CrashSight Symbol Table Configurations for Android”.

3.4 Parameter Config

• Add permissions to AndroidManifest.xml:

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

Note: If you are going to release the app on Google Play Store, you need to block or remove the READ_PHONE_STATE permission, or the app may be removed from the store.

• Please don’t obfuscate CrashSight. Add the following configurations to the ProGuard obfuscation file:

-dontwarn com.uqm.crashsight.**
-keep public class com.uqm.crashsight.**{*;}

3.4 Simple Initialization

Obtain APP ID and copy the following code to onCreate() of the project’s Application class. CrashSight will automatically detect the environment and finish configurations: (To ensure accuracy of operation data, please don’t initialize CrashSight in a asynchronous thread).

// Set reporting address
CrashReport.setServerUrl(serverUrl);
//Initialization
CrashReport.initCrashReport(getApplicationContext(), "注册时申请的APPID", false);

The third parameter is the switch of SDK debugging mode. Features of the debugging mode’s operation include:

• Outputs detailed CrashSight SDK log.
• All crashes are reported right away.
• Custom log will be output in Logcat.

You’re recommended to set it as true during tests, and as false upon release.

Reporting Address

• Domestic public cloud https://android.crashsight.qq.com/pb/async
• Overseas public cloud https://android.crashsight.wetest.net/pb/async

3.5 Notes on MultiDex

If MultiDex is used, it’s recommended to put CrashSight’s class into the main Dex through Gradle’s “multiDexKeepFile” config or other means. In addition, you’re recommended to manually load sub-Dex in the “attachBaseContext” method of Application class.

public class MyApplication extends SomeOtherApplication {
  @Override
  protected void attachBaseContext(Context base) {
     super.attachBaseContext(context);
     Multidex.install(this);
  }
}

3.6 Integration Result Testing

Now you can cause a crash (triggering it with “keys” is recommended) to see CrashSight’s capabilities. After initializing CrashSight, call CrashSight to test the Java Crash interface.

CrashReport.testJavaCrash();

When executing this code, a crash will happen. The output of Logcat’s TAG=CrashSightReport is:

Now you can see the Crash issue just triggered on the “Crash” page (usually delayed by no more than 10s). If the project contains a Native project or uses code obfuscation, you’re recommended to configure a symbol table file.

3.7 Enable Javascript's Exception Detection Feature

CrashSight Android SDK 4.2.12 and above versions offer Javascript exception detection and reporting features for developers to detect Javascript exceptions occurring in WebView.

/**
* Set Javascript exception monitoring
* 
* @param webView: specify the webView to monitor
* @param autoInject: whether to inject crashsight.js file automatically
* @return true: successfully set; false: failed to set
*/
CrashReport.setJavascriptMonitor(WebView webView, boolean autoInject)

• The “crashsight.js” file is in the CrashSight SDK and can be embedded manually via HTML.
• When auto SDK integration is used, you can choose between auto injection and manual injection. To use auto integration + manual injection, you need to download the “crashsight.js” file.
• Because versions lower than Android 4.4 have a flawed deflect mechanic, the interface only works in Android 4.4 and higher versions by default.
• The interface doesn’t configure WebViewClient and Listener of webView.
• The interface enables webView’s JS executing capabilities by default.

If non-standard Android WebView is used (such as one with a X5 core), it needs to be used like below:

CrashReport.WebViewInterface webView = new CrashReport.WebViewInterface() {
    /**
     * Obtain WebView URL.
     *
     * @return WebView URL
     */
    @Override
    public String getUrl() {
        // The following is for demonstration only. Please use real logics in real-life scenarios
        return <third-party WebView object>.getUrl();
    }

    /**
     * Activate JavaScript.
     *
     * @param flag true means activated; false means deactivated
     */
    @Override
    public void setJavaScriptEnabled(boolean flag) {
        // The following is for demonstration only. Please use real logics in real-life scenarios
        WebSettings webSettings = <third-party WebView object>.getSettings();
        webSettings.setJavaScriptEnabled(flag);
    }

    /**
     * Load URL.
     *
     * @param url URL to be loaded
     */
    @Override
    public void loadUrl(String url) {
        // The following is for demonstration only. Please use real logics in real-life scenarios
        <third-party WebView object>.loadUrl();
    }

    /**
     * Add JavaScript interface object.
     *
     * @param jsInterface JavaScript interface object
     * @param name JavaScript interface object name
     */
    @Override
    public void addJavascriptInterface(H5JavaScriptInterface jsInterface, String name) {
        // The following is for demonstration only. Please use real logics in real-life scenarios
        <third-party WebView object>.addJavascriptInterface(jsInterface, name);
    }

    /**
     * Obtain content description of WebView.
     *
     * @return Content description of WebView.
     */
    @Override
    public CharSequence getContentDescription() {
        // The following is for demonstration only. Please use real logics in real-life scenarios
        return <third-party WebView object>.getContentDescription();
    }
};
// Just import the WebView interface object created when calling CrashSight to set the JS exception detection interface

Auto Injection

It's recommended to call the interface with the onProgressChanged function of WebChromeClient.

CrashReport.setJavascriptMonitor(webView, true);

Example:

WebView webView = new WebView(this);
// Set WebChromeClient
webView.setWebChromeClient(new WebChromeClient() {
    @Override
    public void onProgressChanged(WebView webView, int progress) {
        // Add Javascript exception monitoring
        CrashReport.setJavascriptMonitor(webView, true);
        super.onProgressChanged(webView, progress);
    }
});
// Load HTML
webView.loadUrl(url);

Manual Injection

Download crashsight.js file and add it to the HTML where Javascript exception monitoring is needed:

<html>
  <script src="crashsight.js" ></script>
<body>
    ...
</body>
</html>

After WebView has loaded the HTML, configure Javascript’s exception detection feature:

WebView webView = new WebView(this);
// Load HTML
webView.loadUrl(url);
// Add Javascript exception monitoring
CrashReport.setJavascriptMonitor(webView, false);

After CrashSight Android SDK has detected a Javascript exception, the following info will be reported by default:

• Android device info;
• Javascript exception stack and other info;
• Java stack;
• WebView info, which only includes ContentDescription at present.

4 Android Interfaces

4.1 Error Reporting

public static void postException(int category, String errorType, String errorMsg, String stack, Map<String, String> extraInfo)

Note: Active reporting of error info

View page:

extraInfo: Crash Details->Trace Data->extraMessage.txt

4.2 Set User ID

public static void setUserId(String userId)

Note: Set User ID

4.3 Mark a Scene

public static void setUserSceneTag(int tagId)

Note: Mark a Scene

4.4 Add Custom Data

public static void putUserData(Context context, String key, String value)

Set the Key-Value data customized by the user. It will be reported together with exception info when sending the crash. Each key shouldn’t exceed 100 characters, each value shouldn’t exceed 1000 characters, and the total length (all keys+all values) shouldn’t exceed 64KB.

View page:

Crash Details->Trace Data->valueMapOthers.txt

4.5 Custom Log

import com.uqm.crashsight.crashreport.CrashSightLog;

Verbose level log：

public static void v(String tag, String content)

Debug level log

public static void d(String tag, String content)

info level log

public static void i(String tag, String content)

warn level log

public static void w(String tag, String content)

error level log

public static void e(String tag, String content)

Note: The custom log shouldn’t exceed 30KB.

4.6 Set Callback

Note: Set the callback function for crash and error reporting.

View page:

onCrashHandleStart: Crash Details->Trace Data->extraMessage.txt

onCrashHandleStart2GetExtraDatas: Crash Details->Trace Data->userExtraByteData

CrashReport.UserStrategy strategy = new CrashReport.UserStrategy(MainActivity.this);
// Set CrashSight callback
strategy.setCrashHandleCallback(new CrashReport.CrashHandleCallback() {
    /**
      * Customize the crash callback for info reporting
      *
      * @param crashType     Error type: CRASHTYPE_JAVA, CRASHTYPE_NATIVE, CRASHTYPE_U3D, CRASHTYPE_ANR
      * @param errorType     Error type name
      * @param errorMessage  Error message
      * @param errorStack    Error stack
      * @return Return extra custom info reporting
      */
    @Override
    public synchronized Map<String, String> onCrashHandleStart(int crashType, String errorType, String errorMessage, String errorStack) {
        // Obtain custom info Map of parent class
        Map<String, String> userDatas = super.onCrashHandleStart(crashType, errorType, errorMessage, errorStack);
        if (userDatas == null) {
            userDatas = new HashMap<>();
        }
        for (String k : extraMap.keySet()) {
            userDatas.put(k, extraMap.get(k));
        }
        return userDatas;
    }

    /**
      * Crash callback of binary info reporting
      *
      * @param crashType     Error type: CRASHTYPE_JAVA, CRASHTYPE_NATIVE, CRASHTYPE_U3D, CRASHTYPE_ANR
      * @param errorType Error type name
      * @param errorMessage Error message
      * @param errorStack Error stack
      * @return byte[] Report extra binary content
      */
    @Override
    public byte[] onCrashHandleStart2GetExtraDatas(int crashType, String errorType, String errorMessage, String errorStack) {
        return "test onCrashHandleStart2GetExtraDatas".getBytes();
    }
});
CrashReport.initCrashReport(MainActivity.this, appId, true, strategy);

5 iOS Interfaces

5.1 Initialize CrashSight with Specified Configurations

Class：CrashSight
Method：+ (void)startWithAppId:(NSString * CS_NULLABLE)appId
     developmentDevice:(BOOL)development
                config:(CrashSightConfig * CS_NULLABLE)config;

5.2 Set User ID

Class：CrashSight
Method：+ (void)setUserIdentifier:(NSString *)userId;

5.3 Set App Version Info

Class：CrashSight
Method：+ (void)updateAppVersion:(NSString *)version;

5.4 Set Key Data, Reported with Crash Info

Note: Set the Key-Value data customized by the user. It will be reported together with exception info when sending the crash. Each key shouldn’t exceed 100 characters, each value shouldn’t exceed 1000 characters, and the total length (all keys+all values) shouldn’t exceed 128KB.

View page: Crash Details->Trace Data->valueMapOthers.txt

Class：CrashSight
Method：+ (void)setUserValue:(NSString *)value
              forKey:(NSString *)key;

5.5 Set Scene Marks

Class：CrashSight
Method：+ (void)setUserSceneTag:(NSString *)userSceneTag;

5.6 Report Custom Errors

Class：CrashSight
Method：+ (void)reportExceptionWithCategory:(NSUInteger)category
                               name:(NSString *)aName
                             reason:(NSString *)aReason
                          callStack:(NSArray *)aStackArray
                          extraInfo:(NSDictionary *)info
                       terminateApp:(BOOL)terminate;

View page：

info: Crash Details->Trace Data->extraMessage.txt

5.7 Set Reporting Log Level

Class：CrashSightLog
Method：+ (void)initLogger:(CrashSightLogLevel) level consolePrint:(BOOL)printConsole;

5.8 Custom Reporting Log

Note: Shouldn’t exceed 30KB.

Class：CrashSightLog
Method：+ (void)level:(CrashSightLogLevel) level log:(NSString *)format, ... NS_FORMAT_FUNCTION(2, 3);

5.9 Set Exception Callback

Class：CrashSightDelegate
Proxy property：delegate
Proxy protocol：CrashSightDelegate
Proxy protocol method：- (NSString * CS_NULLABLE)attachmentForException:(NSException * CS_NULLABLE)exception callbackType:(CSCallbackType)callbackType;

Note: The result returned by proxy protocol method will be reported along with the exception View page: Crash Details->Trace Data->catch_log.txt