Snowplow Android Tracker 0.1.1 released

17 September 2014  •  Jonathan Almeida

We are proud to release the Snowplow Android Tracker, one of the most requested Trackers so far. This is a major milestone for us, leveraging Snowplow 0.9.8 for mobile analytics support.

The Android Tracker has evolved in tandem with the Java Tracker. We have based the Android Tracker on the same Java Tracker Core that powers the Java Tracker, along with a few additions, such as tracking geographical location, and sending mobile-specific context data.

So you’ll see many similarities between the two Trackers, which I’ll explain in further detail in the rest of the post:

  1. Compatibility
  2. How to install the tracker
  3. How to use the tracker
  4. Mobile context
  5. Location context
  6. Under the hood
  7. Getting help

1. Compatibility

The Android Tracker has been built and tested with the Android SDK version 19, but is compatible with SDK version 11 and above. This means that the tracker is compatible with majority of the Android devices currently being used.

2. How to install the tracker

The release version of this tracker (0.1.1) is available within Snowplow’s Maven repository. We have instructions for installing the tracker for Maven, Gradle and SBT in the Android Tracker Setup guide.

Here is the Gradle setup for example:

repositories {
    ...
    maven {
        url "http://maven.snplow.com/releases"
    }
}

dependencies {
    ...
    // Snowplow Android Tracker
    compile 'com.snowplowanalytics:snowplow-android-tracker:0.1.1'
    compile 'com.snowplowanalytics:snowplow-java-tracker-core:0.1.3'
}

To send the events, you need to update your AndroidManifest.xml with the internet access permission:

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

3. How to use the tracker

Using the tracker requires you to import the Tracker module like so:

import com.snowplowanalytics.snowplow.tracker.*;

We need to create an Emitter to send events created by the Tracker. The Emitter instance requires an Android Context instance as well for caching, which we explain more about later in this post. For now, here is an example of how the Emitter and Tracker are created:

Emitter e1 = new Emitter("d3rkrsqld9gmqf.cloudfront.net", context, HttpMethod.POST);
Tracker t1 = new Tracker(e1, "AF003", "cloudfront");

Now let’s send in a couple of events:

t1.trackStructuredEvent("shop", "add-to-basket", "Add To Basket", "pcs", 2);
t1.trackScreenView("HUD > Save Game", "screen23");

Check out the Android Tracker documentation on the wiki for the tracker’s full API.

4. Mobile context

If you create a Subject instance, it will attach as much contextual information as it can, including by default the operating system version, device model and manufacturer.

If you construct the Subject with an Android Context, the Tracker will attach additional context about the user’s device, such as screen resolution, carrier information and most importantly, the Advertising ID. The Advertising ID requires the Play Services SDK to be set-up which you can find in more detail at the Android Tracker Setup guide.

Here an example of how this would look:

// We attach basic context
Subject subject1 = new Subject();

// We attach additional context
Subject subject2 = new Subject(context);

The mobile-specific context is added to each event’s context array structured using the mobile context schema.

If you’re using Redshift, you would need to install the mobile_context table using this script.

5. Geolocation context

The Subject class also lets you attach location-based contextual information to your events. To grab the location information you need to add the following permissons to your AndroidManifest.xml:

<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

Geolocation context requires you to pass an Android Context to the Subject class. The location information will then be added as part of the context array, structured using the geolocation context schema.

If you’re using Redshift, you would need to install the geolocation_context table using this script.

6. Under the hood

The Android Tracker uses an SQLite database to store events, saving them until they have been successfully sent to a collector (i.e. a 200 HTTP response is received back from the request sent). This is the main reason we requre an Android Context to be passed to the Emitter.

All requests made, either GET or POST, are sent using an AsyncTask class. This lets us send events using a background thread. Note that we have removed the option to send requests synchronously, which the Java Tracker can do, to avoid blocking calls on the main UI thread.

7. Getting help

This is only our first release of the Android Tracker and we look forward to further releases based on your real-world usage of the tracker.

We’re looking forward to user feedback, feature requests or possible bugs. Feel free to get in touch or raise an issue on GitHub!