Installing the Android SDK

Installing via Gradle

In the build.gradle file living in the projectname/app directory, add the Apteligent dependency information in dependencies{...}

compile 'com.crittercism:crittercism-android-agent:+'

or, for the NDK agent:

compile 'com.crittercism:crittercism-android-ndk-agent:+'

Be sure to sync your project with your gradle files after you add this!

Installing Manually

  1. Download the Android SDK. You must choose between the standard SDK and the NDK-enabled SDK.
  2. Copy the Apteligent JAR file to your libs folder.
  3. If you are using gradle, ensure that your dependency information in dependencies{...} includes jars in your libs folder:
compile fileTree(dir: 'libs', include: ['*.jar'])
  1. If you’re using Eclipse, right click your project, click Properties, select Java Build Path, click Add External Jar, and then add the Apteligent JAR file.

Setting Up the Manifest

Add the following permissions to your app’s AndroidManifest.xml file.

INTERNET
Required. Used to report data to Apteligent.
ACCESS_NETWORK_STATE
Optional. Allows providing network connectivity information such as carrier and network type.
<?xml version="1.0" encoding="UTF-8"?>
<manifest android:versionCode="3"
    android:versionName="1.0"
    package="com.crittercism.demo"
    xmlns:android="http://schemas.android.com/apk/res/android">

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

    <application android:icon="@drawable/icon"
        android:label="@string/app_name" android:name=".DemoApp">

        <activity android:label="@string/app_name" android:name=".MainActivity">
            <intent-filter>
                <action android:name="android.intent.action.MAIN"/>
                <category android:name="android.intent.category.LAUNCHER"/>
            </intent-filter>
        </activity>

    </application>
</manifest>

For more information on these permissions, refer to the Android Manifest documentation

Initializing Apteligent

Obtain your App ID from Apteligent’s “New App Registration” page (Apteligent Quickstart).

The following initialization instructions are the same for both the standard (sdkonly) SDK and the NDK-enabled SDK.

  1. To initialize Apteligent add the following code at the beginning of the onCreate() of your main Activity:
Crittercism.initialize(getApplicationContext(), "CRITTERCISM_APP_ID");

Note

Apteligent should be initialized once on the main thread as early as possible. Hence, if you subclass the Application singleton, you should initialize Apteligent in the onCreate() of that Application subclass using the same code, instead of the main activity. App loads will be sent from the first visible activity; they will not be sent from background services and BroadcastReceivers.

Note

Your main Activity is the one with android.intent.action.MAIN intent filter in your AndroidManifest.

  1. You may need to add the following import, if Android Studio has not automatically added it already:
import com.crittercism.app.Crittercism;

Your Android app is now integrated with Apteligent and you can go ahead and build it. Additional features require adding more code to your project.

Configuring Proguard Symbolication

Symbolication is the process of translating stack traces into a human-readable form by mapping hexadecimal addresses to function names using symbol file(s). Apteligent automatically symbolicates crashes once you have uploaded your app’s symbol file(s).

Note

Follow the instructions in this section only if your app obfuscates with Android Proguard. Otherwise, skip this section.

For Android applications, developers have the option to obfuscate their function names using the ProGuard tool in order to reduce app size and to prevent others from reverse engineering the app source. In order to replace the obfuscated name with a human-readable name, developers use a Proguard mapping file.

Setting Up ProGuard

  1. To build a project with Apteligent, place the Apteligent JAR in the libs/ directory of your project.
  2. Add the following lines to your project’s proguard.cfg file:
-dontwarn com.crittercism.**
-keep public class com.crittercism.**
-keepclassmembers public class com.crittercism.**
{
    *;
}
  1. To get line number information, make sure that you keep the file names and line numbers in your ProGuard .cfg settings file.
-keepattributes SourceFile, LineNumberTable

This information will be visible in all stacktraces, however - even those that are not symbolicated.

Uploading the mapping.txt File

To have your crashes automatically symbolized, you must upload a mapping.txt file on your App Settings page.

Each mapping.txt file you upload is associated with a version of your app. We symbolize crashes for only one version with each mapping.txt file.

Note

Be careful to upload the right file for your version! If you upload the wrong file, you might get incorrect stacktraces. If you accidentally upload the wrong mapping.txt for a version, simply delete the file and upload it again.

Use the following command to upload a Proguard mapping file to the Apteligent server.

Syntax

curl "https://app.crittercism.com/api_beta/proguard/<app_id>" -F proguard=@"<path/to/proguard-mapping.txt>" -F app_version="app-version-name" -F key=<key>

Note

Specify the “@” symbol when using this command.

Important

Use appropriate base URL with respect to the Data Location of your application: North America (app.crittercism.com), Europe (app.eu.crittercism.com).

Arguments

Name Description
app_id Application ID.
path Path to the proguard-mapping.txt file.
app-version-name Name of the app version.
key API Key.

Returns

Code Meaning
200 Success.
400 Problem with the specified proguard file. The HTML response body describes the problem.
404 App not found or tokens incorrect.

Note

If you set a customized app version name in the CrittercismConfig instance, you should use that string and not the manifest string in app-version-name. Also, if you choose to include the app version code in the app version, that should also be included in app-version-name.

Adding a Command to the Build File

You can insert an additional step in your build file to execute a command based on the following example. Consult the Apteligent API docs for more information.

curl "https://app.crittercism.com/api_beta/proguard/<app_id>" -F proguard=@"<path/to/proguard-mapping.txt>" -F
app_version="app-version-name" -F key=<key>

Note

At this point, you have enabled Apteligent to receive Application Performance Information from your application, and have set up your build environment to automatically provide Apteligent with your symbol files.

Important

Use appropriate base URL with respect to the Data Location of your application: North America (app.crittercism.com), Europe (app.eu.crittercism.com).

Configuring Android NDK Symbolication

Symbolication is the process of translating stack traces into a human-readable form by mapping hexadecimal addresses to function names using symbol file(s). Apteligent automatically symbolicates crashes once you have uploaded your app’s symbol file(s).

Note

Follow the instructions in this section only if you have an Android NDK app in which NDK crash reporting is enabled. Otherwise, skip this section.

Android NDK symbol files have the extension .sym and use the standard, plain-text objdump/llvm-objdump format. Symbols can be uploaded directly as .sym files, or as a compiled shared library objects (.so), which undergo conversion to symbol files on our servers.

Options for sending files include:
  • One-at-a-time direct upload
  • .zip archive (zipfile)
  • .tar archive with optional gzip (.tar.gz) or bzip2 (.tar.bz2) compression applied

If a .zip or .tar file is uploaded, all .so or .sym files, in all directories, will be queued for processing.

Symbols can be uploaded interactively via Apteligent’s website, or by a batch/automatic job using the symbol upload API.

Uploading Symbols Using the Website

To upload symbols for one version of your app, use the following procedure:

  1. In your environment, change to your NDK app’s root directory.
  2. Zip up the obj directory in your Android project.
  3. Drag that zip archive into the drop box (located under the Upload NDK Symbols tab in your App Settings) for uploading NDK symbols; it will report success or failure.
  4. Go to a crash report and click Add to Symbolication Queue.

Once you complete these steps, you should be able to view your symbolicated native crashes. Thereafter, all symbols in the crashes we receive will be converted to source code using the symbols you uploaded.

Uploading Symbols Using the API

Note

Using Apteligent’s API requires an OAuth2 access token. See Retrieve an OAuth2 Access Token for details.

The symbol upload endpoint permits scripted upload of application symbols. Several customers have used the API in conjunction with their build jobs to automatically upload symbols to Apteligent on production app releases.

1. Obtain an access token. The token must include the scope app/{appId}/symbols; for app with ID 519d53101386202089000007, the scope would be app/519d53101386202089000007/symbols (“app%2F519d53101386202089000007%2Fsymbols” after encoding).

  1. Create a new “Apteligent File Resource” by issuing the following POST command:
curl -X POST https://files.crittercism.com/api/v1/applications/{appId}/symbol-uploads -H ‘Authorization: Bearer <token>'

{"resource-id":"d6a11f25-600e-4b39-98b8-f4a5488e42a4","filename":"","appid":"{appId}","created":"2014-11-24T23:25:18.842Z","last-modified":"2014-11-24T23:25:18.842Z","size":0,"md5sum":"","status":"empty","resource-type":"symbol-uploads","storage-key":"applications/{appId}/symbol-uploads/d6a11f25-600e-4b39-98b8-f4a5488e42a4"}

Important

Use appropriate base URL with respect to the Data Location of your application: North America (files.crittercism.com), Europe (files.eu.crittercism.com).

The command will return a JSON response, including a “resource id” UUID - “d6a11f25-600e-4b39-98b8-f4a5488e42a4” in the example above. The UUID is a pointer to the uploaded file and should not be reused. Each time an upload is required, it should use its own UUID.

  1. “Fill” the given file resource (identified by UUID) using the following PUT command:
curl -X PUT https://files.crittercism.com/api/v1/applications/{appId}/symbol-uploads/d6a11f25-600e-4b39-98b8-f4a5488e42a4 -F name=symbolUpload -F "filedata=@/Users/dalbrecht/Downloads/appSymbols.tar.bz2" -H 'Authorization: Bearer <token>'

Important

Use appropriate base URL with respect to the Data Location of your application: North America (files.crittercism.com), Europe (files.eu.crittercism.com).

  1. Create a symbol upload job using the following command:
curl -X POST https://app.crittercism.com/v1.0/app/{appId}/symbols/uploads -d '{"uploadUuid": "d6a11f25-600e-4b39-98b8-f4a5488e42a4","filename":"upload.zip"}' -H 'Authorization: Bearer <token>' -H 'Content-Type: application/json'

After a few minutes, incoming crashes will begin using the provided symbols.

Important

Use appropriate base URL with respect to the Data Location of your application: North America (app.crittercism.com), Europe (app.eu.crittercism.com).