Collecting data with Trackers and Webhooks

  1. Home
  2. Docs
  3. Collecting data with Trackers and Webhooks
  4. Trackers – collecting data from your own applications
  5. Java Tracker
  6. Tracking specific client-side properties

Tracking specific client-side properties

An event describes a single, transient activity. The context in which that event occurs – the relatively persistent environment – is also incredibly valuable data. As discussed on the previous page, the most powerful way to track such data is to use custom self-describing JSON entities. These are sent as JSON in the raw event payload. Depending on your data warehouse, event context entities are loaded into their own tables, or remain as JSON in the loaded event.

The Java tracker provides an additional "primitive" method to track a small subset of contextual data, using the Subject class. As with the "primitive" event types, e.g. PageView, Subject properties directly populate the "atomic" fields of the raw event payload. These data will always end up in individual columns of the main event table in the data warehouse.

The fields tracked using Subject tend to be most relevant in client-side tracking. Some are set automatically in all events during enrichment, even when no Subject is added. These properties are marked with * below, and discussed below. Timezone, marked with **, is only set when a Subject is tracked with the event.

Add these fields to an event using Subject:

Property Field in raw event Column(s) in enriched event
userId uid user_id
ipAddress* ip user_ipaddress
timezone** tz os_timezone
language lang br_lang
useragent* ua useragent
viewport vp br_viewheight, br_viewwidth
screenResolution res dvce_screenheight, dvce_screenwidth
colorDepth cd br_colordepth
networkUserId* tnuid network_userid
domainUserId duid domain_userid
domainSessionId sid domain_sessionid

Note: the ability to set domainSessionId was added in version 0.11.

These properties are especially useful for client-side tracking, or for linking client-side and server-side tracking. We highly recommend tracking in both client-side and server-side, if it’s relevant to your application. Read more about this in these blog posts.

If you are also using the Javascript tracker, it will set cookies in the browser. The Subject properties domainUserId, and domainSessionId are intended to be used for extracted cookie values passed to the Java tracker. If you want to track other identification tokens, we recommend creating schemas and using context entities.

As always, be aware of privacy when tracking personal identifiable information such as email addresses or IP addresses.

Overriding autogenerated event properties

All enriched Snowplow events contain values for user_ipaddress, useragent, and network_userid.

The user_ipaddress is automatically added to all enriched events. To manually override this, use a Subject and set a ipAddress string; use an empty string to prevent IP address tracking. Alternatively, use the IP anonymization enrichment.

The useragent is also automatically added during enrichment. Snowplow pipelines provide multiple useragent-parsing enrichments. To manually override the detected useragent, use a Subject and set a useragent string. For the default Tracker configuration with OkHttp, the default useragent will be "okhttp/4.2.2".

The network_userid is the cookie value for the event collector’s third-party cookie. It is the server-side user identifier. The cookie is named sp (or micro for Snowplow Micro pipelines). The default behaviour is for the collector to provide a new cookie/network_userid for each event it receives. To override the collector cookie’s value with your own generated ID, use a Subject object and set networkUserId.

A further property, timezone, is generated automatically during Subject initialization, based on Calendar.getInstance().getTimeZone(). Therefore, this will be added to all events with a Subject attached. The default will be overriden if timezone is provided explicitly.

Adding Subject properties to events

There are two ways to track the Subject "atomic" properties in your events: on an event-by-event basis; or globally, to affect all events. A combination of both methods is also possible.

A simple Subject initialisation looks like this:

Subject subject = new Subject.SubjectBuilder() .userId("") .build();
Code language: Java (java)

There are no required methods for the SubjectBuilder.

A Subject can be added to any event using the subject() Event.Builder method:

// This example shows an Unstructured event, but all events can have a Subject Unstructured unstructured = Unstructured.builder() .eventData(dataAsSelfDescribingJson) .subject(subject) .build();
Code language: Java (java)

To set Subject properties in all subsequent events, add a Subject to your Tracker object:

// A Subject can be provided at Tracker initialisation Tracker tracker = new Tracker .TrackerBuilder(emitter, "trackerNamespace", "appId") .subject(subject) .build(); // Alternatively, a Subject can be set later Tracker tracker = new Tracker .TrackerBuilder(emitter, "trackerNamespace", "appId") .build(); tracker.setSubject(subject);
Code language: Java (java)

Subject properties can be updated or added to after initialization, using setter methods. See the API docs for full details.

It’s possible to use both Event-specific and Tracker-associated Subject objects simultaneously. Fields from both Subject objects are added to the payload, with the Event-specific Subject having priority.

// Adding a global, Tracker-associated Subject Subject trackerSubject = new Subject.SubjectBuilder() .language("EN") .useragent("Snowplow") .build(); Tracker tracker = new Tracker .TrackerBuilder(emitter, "trackerNamespace", "appId") .subject(trackerSubject) .build(); // Adding an Event-specific Subject Subject eventSubject = new Subject.SubjectBuilder() .userId("") .useragent("Mozilla/5.0") .build(); Unstructured unstructured = Unstructured.builder() .eventData(dataAsSelfDescribingJson) .subject(eventSubject) .build(); // Tracking the event tracker.track(unstructured);
Code language: Java (java)

The resulting enriched event would have these Subject atomic columns populated:

Column in enriched event Value / example value Source
user_id "" eventSubject
os_timezone e.g. "Europe/London" eventSubject
br_lang "EN" trackerSubject
useragent "Mozilla/5.0" eventSubject
network_userid e.g. "8383057f-2769-4321-ad72-58fa1b22e4b3" pipeline

If you’d like to learn more about Snowplow BDP you can book a demo with our team, or if you’d prefer, you can try Snowplow technology for yourself quickly and easily.