Application Insights for Android (1.0-beta.4)

This project provides an Android SDK for Application Insights. Application Insights is a service that allows developers to keep their applications available, performing, and succeeding. This module allows you to send telemetry of various kinds (events, traces, exceptions, etc.) to the Application Insights service where your data can be visualized in the Azure Portal.

The minimum SDK to use the Application Insights SDK in your app is 9.

Automatic collection of lifecycle-events requires API level 15 and up (Ice Cream Sandwich+).

Content

1. Release Notes
2. Breaking Changes
3. Setup
4. Advanced Setup
5. Developer Mode
6. Basic Usage
7. Automatic Collection of Lifecycle Events
8. Exception Handling (Crashes)
9. Additional configuration
10. Documentation
11. Contributing

1. Release Notes

• Improvements regarding threat safety
• Improved unit tests (now using Mockito)
• Simplified threading model (still deferring work to background tasks)
• Bugfix for sending logic (number of running operations wasn't decremented when we don't have a connection)
• Fix for potential memory leaks
• Updated code in sample app
• Data is now persisted when the user sends the app into the background (requires API level 14)
• Data is now persisted when the device is low on memory

## 2. Breaking Changes

Starting with the first 1.0 stable release, we will start deprecating API instead of breaking old ones.

• [1.0-beta.4] No breaking API changes.

• Two setup-methods for ApplicationInsightshave been deprecated and will be removed in the next beta

• [1.0-beta.3] Configuration of the Application Insights SDK is now done using ApplicationInsightsConfig. The previous config-classes have been removed

• [1.0-beta.2] To enable automatic lifecycle-tracking, Application Insights has to be set up with an instance of Application (see [Life-cycle tracking] (#2)), otherwise, lifecycle-tracking is disabled.

• [1.0-beta.1] Setup and start of the Application Insights SDK are now done using the new umbrella class ApplicationInsights instead of AppInsights

• [1.0-Alpha.5] Setup and start of the Application Insights SDK are now done using the new umbrella class AppInsights instead of TelemetryClient

## 3. Setup

This is the recommended way to setup Application Insights for your Android app. For other ways to setup the SDK, see Advanced Setup.

We're assuming you are using Android Studio and gradle to build your Android application.

3.1 Add a compile dependency for the SDK

In your module's build.gradleadd a dependency for Application Insights

dependencies {
    compile 'com.microsoft.azure:applicationinsights-android:1.0-beta.3'
}

3.2 Configure the instrumentation key

Please see the "Getting an Application Insights Instrumentation Key" section of the wiki for more information on acquiring a key.

3.3 Add permissions

Add the two permissions for INTERNET and ACCESS_NETWORK_STATE to your app's AndroidManifest.xml

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

3.4 Add your instrumentation key to manifest

Add the instrumentation key for your app to your Android Manifest as follows. Replace ${AI_INSTRUMENTATION_KEY} with your instrumentation key. You can leave the variable as is if you want to use your gradle.properties to set it (see Advanced Setup).

<manifest>
    <application>
        <meta-data
            android:name="com.microsoft.applicationinsights.instrumentationKey"
            android:value="${AI_INSTRUMENTATION_KEY}" />
    </application>
</manifest>

3.5 Add code to setup and start Application Insights

Add the following import to your app's root activity

import com.microsoft.applicationinsights.library.ApplicationInsights;

and add

ApplicationInsights.setup(this.getApplicationContext(), this.getApplication());
ApplicationInsights.start();

in the activity's onCreate-callback.

Congratulation, now you're all set to use Application Insights! See Usage how to use Application Insights.

## 4. Advanced Setup

4.1 Set the instrumentation key in your gradle.properties

Add the <meta-data>to your Android Manifest as described above but leave the variable ${AI_INSTRUMENTATION_KEY}as is. In your global gradle.properties, add

ai_instrumentation_key=<KEY_PLACEHOLDER>

and replace <KEY_PLACEHOLDER> with your instrumentation key. After that, open your top-level build.gradleand add the mainfest placeholder as follows:

android {
    buildTypes {
        all {
            manifestPlaceholders = [AI_INSTRUMENTATION_KEY: ai_instrumentation_key]
        }
    }
}

4.2 Set instrumentation key in code

It is also possible to set the instrumentation key of your app in code. This will override the one you might have set in your gradle or manifest file. Setting the instrumentation key programmatically can be done while setting up Application Insights:

ApplicationInsights.setup(this.getApplicationContext(), getApplication(), "<YOUR-INSTRUMENTATION-KEY>");
ApplicationInsights.start();

5. Developer Mode

The developer mode is enabled automatically in case the debugger is attached or if the app is running in the emulator. This will enable the console logging and decrease the number of telemetry items sent in a batch (5 items) as well as the interval items will be sent (3 seconds). If you don't want this behavior, disable the developer mode.

You can explicitly enable/disable the developer mode like this:

//do this after ApplicationInsights.setup(this.getApplicationContext(), this.getApplication())
//and before ApplicationInsights.start()

ApplicationInsights.setDeveloperMode(false);

6. Basic Usage

The TelemetryClient-instance provides various methods to track events, traces, metrics page views, and handled exceptions.

	
//somewhere in your app, e.g. in the callback of a button
//or in the onCreate-callback of an activity
	
//Get the instance of TelemetryClient
TelemetryClient client = TelemetryClient.getInstance();

//track an event
client.trackEvent("sample event");

//track a trace
client.trackTrace("sample trace");

//track a metric
client.trackMetric("sample metric", 3);

Some data types allow for custom properties.

//Get the instance of TelemetryClient
TelemetryClient client = TelemetryClient.getInstance();

Setup a custom property
HashMap<String, String> properties = new HashMap<String, String>();
properties.put("property1", "my custom property");

//track an event with custom properties
client.trackEvent("sample event", properties);

7. Automatic collection of life-cycle events (Sessions & Page Views)

This only works in Android SDK version 15 and up (Ice Cream Sandwich+) and is enabled by default. Don't forget to provide an Application instance when setting up Application Insights (otherwise auto collection will be disabled):

ApplicationInsights.setup(this.getApplicationContext(), this.getApplication());

If you want to explicitly Disable automatic collection of life-cycle events (auto session tracking and auto page view tracking), call setAutoCollectionDisabled inbetween setup and start of Application Insights.

ApplicationInsights.setup(this.getApplicationContext());
ApplicationInsights.setAutoCollectionDisabled(true); //disable the auto-collection
ApplicationInsights.start();

After ApplicationInsights.start() was called, you can enable or disable those features at any point:

// Disable automatic session renewal & tracking
ApplicationInsights.disableAutoSessionManagement();

// Enable automatic page view tracking
ApplicationInsights.enableAutoPageViewTracking();

8. Exception Handling (Crashes)

The Application Insights SDK enables crash reporting per default. Unhandled exceptions (aka crashes) will be immediately sent to the server if a connection is available.

This feature can be disabled as follows:

 ApplicationInsights.setExceptionTrackingDisabled(true);

9. Additional Configuration

To configure Application Insights according to your needs, first, call

ApplicationInsights.setup(this.getApplicationContext(), this.getApplication());

After that you can use ApplicationInsightsConfig to customize the behavior and values of the SDK.

ApplicationInsightsConfig config = ApplicationInsights.getConfig();
//do the different configurations

After all custom configurations have been made, just start ApplicationInsights:

ApplicationInsights.start();

9.1 Set User Session Time

The default time the users entering the app counts as a new session is 20s. If you want to set it to a different value, do the following:

config.setSessionIntervalMs(30000); //set intercal to 30s (30,000ms)

9.2 Batch Size for a Bundle of Telemetry

Unhandled exceptions (aka ”your app is crashing!“) are sent out immediately, while regular telemetry data is send out in batches or after a specified interval.

[NOTE] The developer mode will automatically set the batching interval to 3s and the size of a batch to 5 items.

The default interval until a batch of telemetry is sent to the server is 15s. The following code will change it to 5s:

config.setMaxBatchIntervalMs(5000); //set the interval to e.g. 5s (5,000ms)

To set the maxBatchSize to a different value (default is 100) like this:

config.setMaxBatchCount(20); //set batch size to 20.

9.3 Set Different Endpoint

You can also configure a different server endpoint for the SDK if needed:

config.setEndpointUrl("https://myserver.com/v2/track");

9.4 Override sessionID and userID

Application Insights manages IDs for a session and for individual users for you. If you want to override the generated IDs with your own, it can be done like this:

ApplicationInsights.setUserId("New user ID");
ApplicationInsights.renewSession("New session ID");

[NOTE] If you want to manage sessions manually, please disable Automatic Collection of Lifecycle Events.

9.5 Other

For all available configarion options, see our Javadoc for ApplicationInisghtsConfig

## 10. Documentation

Our Javadoc can be found at http://microsoft.github.io/ApplicationInsights-Android/

## 11 Contributing

Development environment

• Install a Java Development Kit (JDK). The SDK can be compiled using JDK 1.6, though we recoommend installing JDK 1.8
• Install Android studio
• Get an instrumentation key and set it in the manifest
• Run tests from Android Studio

12. Contact

If you have further questions or are running into trouble that cannot be resolved by any of the steps here, feel free to contact us at AppInsights-Android@microsoft.com