Installation and set-up

Installing

The Snowplow Java tracker 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.

The current tracker version is 2.1.0. New issues and pull requests are very welcome! Find the Github repository here.

Install using Maven

Add into your project’s pom.xml:

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

Install using Gradle

From version 0.10.1 onwards, we provide 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:2.1.0'
    implementation ('com.snowplowanalytics:snowplow-java-tracker:2.1.0') {
        capabilities {
            requireCapability 'com.snowplowanalytics:snowplow-java-tracker-okhttp-support'
        }
    }
}

Adding dependencies for Apache HTTP support instead (read this page for how to configure this):

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

If you are using your own HttpClientAdapter implementation and/or will be installing dependencies separately:

dependencies {
    implementation 'com.snowplowanalytics:snowplow-java-tracker:2.1.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"  % "2.1.0"

Setting up

The simplest initialization looks like this:

import com.snowplowanalytics.snowplow.tracker.Snowplow;
import com.snowplowanalytics.snowplow.tracker.Tracker;

Tracker tracker = Snowplow.createTracker("trackerNamespace", "appId", "http://collectorEndpoint");

The URL path for your collector endpoint should include the protocol, "http" or "https". The Java tracker is able to send events to either.

The Snowplow interface, added in v1, contains static methods to help initialise and manage Tracker objects. This is especially useful when multiple trackers are needed (see here). See the API docs for the full Snowplow details.

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
subclasses of Event	What you want to track

Configuring the Tracker

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

Both trackerNamespace and appId are required arguments when creating a Tracker. 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 instances within your app. It's also the identifier for Tracker objects in the Snowplow class. 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 DevicePlatform enum during construction.

The final two Tracker configuration options are whether to use base-64 encoding, and whether to add a Subject object (see here for details about Subject). By default, JSONs within the event are sent base-64 encoded. This can be set to false here at Tracker initialization.

To create a Tracker with custom configuration, use the TrackerConfiguration class.

TrackerConfiguration trackerConfig = new TrackerConfiguration("namespace", "appId")
        .base64Encoded(false)
        .platform(DevicePlatform.Desktop);

// Use the Snowplow class to create Trackers
Tracker tracker = Snowplow.createTracker(
    trackerConfig,
    new NetworkConfiguration("http://collector"));

// Alternatively, create an Emitter first, and then create a Tracker directly
// Emitters are introduced in the next section
BatchEmitter emitter = new BatchEmitter(new NetworkConfiguration("http://collector"));
Tracker tracker = new Tracker(trackerConfig, emitter);

This Tracker will produce events with the platform value pc.

See the API docs for the full Tracker, TrackerConfiguration and Snowplow details.

Stopping the tracker

The default Emitter, BatchEmitter, contains a pool of non-daemon threads managed by a ScheduledExecutorService. To close the executor service and stop the threads, use the close() method. This method can be called directly on an Emitter, or via a Tracker:

tracker.close()

// It's also possible to close the Emitter directly
tracker.getEmitter().close()
emitter.close()

There is no way to restart the Emitter after this. Note that if your app is not quit, events can still be tracked after close() has been called: they will accumulate in the Emitter buffer, unable to be sent.

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.