Installation and set-up

caution

You are reading documentation for an outdated version. Here’s the latest one!

Installing

The Snowplow Java tracker (GitHub) has been built and tested using Java versions 8, 11 and 17, so should work within any Java application built using JDK8 upwards. The Java tracker is also usable from Scala.

These pages are for version 0.12

See here for the documentation for the latest version.

Install using Maven

Add into your project’s pom.xml:

<dependency>
    <groupId>com.snowplowanalytics</groupId>
    <artifactId>snowplow-java-tracker</artifactId>
    <version>0.12.0</version>
</dependency>

Install using Gradle

From version 0.10.1 onwards, we have provided out-of-the-box support for sending events via OkHttp or Apache HTTP. The appropriate dependencies must be specified. The default tracker configuration uses OkHttp.

Add this into your project’s build.gradle for the default installation with OkHttp support:

dependencies {
    implementation 'com.snowplowanalytics:snowplow-java-tracker:0.12.0'
    implementation ('com.snowplowanalytics:snowplow-java-tracker:0.12.0') {
        capabilities {
            requireCapability 'com.snowplowanalytics:snowplow-java-tracker-okhttp-support'
        }
    }
}

Adding Apache HTTP support instead:

dependencies {
    implementation 'com.snowplowanalytics:snowplow-java-tracker:0.12.0'
    implementation ('com.snowplowanalytics:snowplow-java-tracker:0.12.0') {
        capabilities {
            requireCapability 'com.snowplowanalytics:snowplow-java-tracker-apachehttp-support'
        }
    }
}

If you are using your own HttpClientAdapter class:

dependencies {
    implementation 'com.snowplowanalytics:snowplow-java-tracker:0.12.0'
}

Install by direct download

You can also manually insert the tracker by downloading the jar directly from Maven Central.

Install in Scala project (SBT)

The Snowplow Java tracker is also usable from Scala. Add this to your SBT config:

// Dependency
val snowplowTracker = "com.snowplowanalytics"  % "snowplow-java-tracker"  % "0.12.0"

Setting up

The simplest initialization looks like this:

import com.snowplowanalytics.snowplow.tracker.*;
import com.snowplowanalytics.snowplow.tracker.emitter.*;

BatchEmitter emitter = BatchEmitter.builder()
        .url("http://collectorEndpoint")
        .build();
Tracker tracker = new Tracker
        .TrackerBuilder(emitter, "trackerNamespace", "appId")
        .build();

The Java tracker Github repository includes a mini demo, "simple-console". Follow the instructions in the README to send one event of each type to your event collector. Simple-console is provided as a simple reference app to help you set up the tracker.

These are the required objects for tracking using the Java tracker:

Class	Function
Tracker	Tracks events
Emitter (BatchEmitter)	Sends event payloads
subclasses of Event	What you want to track

Configuring the Tracker

The Tracker class has the responsibility for tracking events. Certain properties can also be set when creating a Tracker that will be attached to all events. These are trackerNamespace, appId, and platform.

Both trackerNamespace and appId are required arguments for TrackerBuilder. Snowplow events are designed to be stored in a single data warehouse/lake, regardless of their source, to make data modeling easier and provide a single valuable source of truth for your business. The tracker namespace allows you to distinguish events sent by this specific Tracker, if you are using multiple Tracker objects within your app. The appId allows you to identify events from this specific application, if you are tracking from multiple places.

The other Tracker property that will be added to all tracked events is platform. This is set by default to srv - "server-side app". To set another valid platform type, use the optional TrackerBuilder method platform().

The final two TrackerBuilder methods are base64() and subject(). By default, JSONs within the event are sent base-64 encoded. This can be set to false here at Tracker initialization. The subject() method is for adding a Subject object to the Tracker, explained here.

To initialize a Tracker with all the options:

Tracker tracker = new Tracker.TrackerBuilder(emitter, namespace, appId)
            .base64(false)
            .platform(DevicePlatform.Desktop)
            .subject(Subject)
            .build();

This Tracker will produce events with the platform value pc.

See the API docs for the full TrackerBuilder details.

Configuring the Emitter

The Emitter class manages the buffering and sending of tracked events. Event sending configuration is described fully on this page.

See the API docs for the full BatchEmitter.Builder and AbstractEmitter.Builder options.

Logging

Logging in the Tracker is done using SLF4J. The majority of the logging set as DEBUG so it will not overly populate your own logging.

Since Java tracker v0.11, user-supplied values are only logged at DEBUG level.