Events from Android Apps

See the Overview for details about setting up the Datacoral Collect Events Slice.

Step 1. Add Snowplow to your dependencies

  • Download the Snowplow jar file
  • Copy the snowplow.jar file into the libs directory of your app.
  • Add libs/snowplow.jar and com.squareup.okhttp:okhttp:2.1.0 as project dependencies. If you are using gradle, specify it in build.gradle file as...
dependencies {
...
compile files('libs/snowplow.jar')
compile 'com.squareup.okhttp:okhttp:2.1.0'
}
  • Sync project (if you are using Android Studio)

Step 2: Update Permissions

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

<uses-permission android:name="android.permission.INTERNET" />
To have the emitter check for online status before sending you will need to add the following:
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
If you want to send location information with each event you will need to add the following permissions to your AndroidManifest.xml:
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

Step 3: Initialize Tracker

  • Initialize the Emitter with appropriate values for collector after substituting the appropriate environment parameters.

URL_ENDPOINT : The URL of your Datacoral Events API gateway. Ex. events.dccustomer.datacoral.io

API_KEY : The Datacoral API key to authorize the events invocations. Ex. 1js9q5Gqmk2VDv2omx2WI3yUGV0K7b464fWUJXDX

ENVIRONMENT : Set the environment as dev or prod, based on the emitter of the events

NAMESPACE : The name of this Tracker instance to include with events sent to the collector. The namespace argument attached to every event fired by the new tracker. This allows you to later identify which tracker fired which event if you have multiple trackers running. Ex. landing_pages

APP_ID : Name of application to include with events sent to the collector. The application ID is used to distinguish different applications that are being tracked by the same Snowplow stack. Ex. "finance" or "hr"

  • Import the Android Tracker's classes into your Android code
import com.snowplowanalytics.snowplow.tracker.*
Emitter emitter = new Emitter
.EmitterBuilder("URL_ENDPOINT", context,
com.snowplowanalytics.snowplow.tracker.classic.Emitter.class).method(HttpMethod.POST).security(RequestSecurity.HTTPS).
apiKey("API_KEY").environment("ENVIRONMENT")
.build();
  • Initialize the Tracker with appropriate values for namespace and appId.
Tracker tracker = new Tracker
.TrackerBuilder(emitter, "NAMESPACE", "APP_ID", context,
com.snowplowanalytics.snowplow.tracker.classic.Tracker.class)
.level(LogLevel.DEBUG)
.base64(false)
.platform(DevicePlatforms.Mobile)
.sessionContext(true)
.subject(new Subject.SubjectBuilder().build()) // Optional - a subject which contains values appended to every event
.build();

Step 4: Track events

To track specific events, invoke the track(event) methods with appropriate event type.

tracker.track(PageView.builder().pageUrl("pageUrl").pageTitle("pageTitle").referrer("pageReferrer").customContext(getCustomContext()).build());
Map<String, String> attributes = new HashMap<String, String>();
attributes.put("test-key-1", "test-value-1");
SelfDescribingJson test = new SelfDescribingJson("iglu:com.snowplowanalytics.snowplow/test_sdj/jsonschema/1-0-1", attributes);
tracker.track(Unstructured.builder().eventData(test).customContext(getCustomContext()).build());
private static List<SelfDescribingJson> getCustomContext() {
List<SelfDescribingJson> contexts = new ArrayList<SelfDescribingJson>();
Map<String, String> attributes = new HashMap<String, String>();
attributes.put("snowplow", "demo-tracker");
SelfDescribingJson json1 = new SelfDescribingJson(
"iglu:com.snowplowanalytics.snowplow/demo_android/jsonschema/1-0-0", attributes);
contexts.add(json1);
return contexts;
}

References: