Analytics and Reporting

This document is a quick guide to integrating Reports support with your Android application using the Airship client library. We will briefly cover the event upload model the client library implements.

Analytics Events and Uploading

Our client library stores events in a local database and uploads them periodically in a background thread. We've taken great care to make sure that the database won't grow beyond a small fixed size, so extended periods of lost connectivity are nothing to worry about. The event upload thread is woken up when new events are triggered and goes to sleep when there are no more events to process, so the impact on battery life is negligible.

Custom Events

Custom events let you track user activities and key conversions in your application, and tie them back to corresponding push messaging campaigns. Custom events require analytics to be enabled. If disabled, any event that is added to analytics will be ignored. For a more detailed explanation on custom events and possible use cases, see the Custom Events topic guide.

Convenient templates are provided to create custom events for common account, media or retail related events. For more details see the Custom Event Templates topic guide.

Recording custom events
CustomEvent.Builder builder = CustomEvent.newBuilder("event_name")
                                         .setEventValue(123.12)
                                         .addProperty("my custom property", "some custom value");

// Set custom event properties on the builder
builder.addProperty("bool_property", true);
builder.addProperty("string_property", "string_property_value");
builder.addProperty("int_property", 11);
builder.addProperty("double_property", 11.0d);
builder.addProperty("long_property", 11L);

ArrayList<String> collection = new ArrayList<String>();
collection.add("string_array_value_1");
collection.add("string_array_value_2");
collection.add("string_array_value_3");
builder.addProperty("collection_property", collection);

// Record the event
builder.build().track();

Custom Identifiers

You can assign up to 20 custom identifiers to users. Identifiers that define additional ways of looking at a user— for example, Android Advertising ID, Google Analytics CID, or any other identifier you deem significant -- can be added to your users.

Setting custom identifiers
UAirship.shared().getAnalytics()
                 .editAssociatedIdentifiers()
                 .addIdentifier("key", "value")
                 .apply();
Automatically track the Android Advertising ID
UAirship.shared().getAnalytics().setAutoTrackAdvertisingIdEnabled(true);

Custom identifiers will be visible in Real-Time Data Streaming. We recommend adding any IDs that you may want to be visible in your event stream, even if Real-Time Data Streaming does not yet support the relevant integration. Unlike the other identifiers (e.g., tags), you cannot use custom identifiers to target your users.

Screen Tracking

The Airship SDK gives you the ability to track what screen a user views within the application, as well as how long the user stayed on that screen and the user's previous screen. These events then come through Airship Real-Time Data Streaming and allow you to see the path that a user takes through an application, or to trigger actions based on a user visiting a particular area of the application.

Track a screen
UAirship.shared().getAnalytics().trackScreen("MainActivity");
Tracking all activities as screens

When a new screen is tracked or when the application backgrounds, a screen tracking event will be generated. Normally, Analytics.trackScreen should be called in either Activity.onStart or Fragment.onStart, depending on how the application is built.

For applications where you only want to track activities, you can automate screen tracking with an activity life cycle listener.

this.registerActivityLifecycleCallbacks(new ActivityLifecycleCallbacks() {
    @Override
    public void onActivityStarted(Activity activity) {
        UAirship.shared().getAnalytics().trackScreen(activity.getClass().getSimpleName());
    }
});

Disabling Analytics

 Warning

Features that depend on analytics being enabled may not work properly if it is disabled (reports, location segmentation, region triggers, push to local time).

If you do not wish to include analytics and reporting in your application, you can disable analytics in the Airship Config under the analyticsEnabled flag.

Disable analytics at runtime
UAirship.shared().getAnalytics().setEnabled(false);

When analytics is disabled at runtime it will delete any locally stored events and prevent any events from uploading.