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 "canonical" method to track a small subset of contextual data, using the Subject class. As with the "canonical" 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 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 behavior 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. Alternatively, configure a CookieJar to persist the sp cookie, and the network_userid, across requests (see here).

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:

SubjectConfiguration subjectConfig = new SubjectConfiguration()
        .userId("java@snowplowanalytics.com");
Subject subject = new Subject(subjectConfig);

In this case only the userId (and timezone) were set. There are no required properties for the SubjectConfiguration.

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

// This example shows an SelfDescribing event, but all events can have a Subject
SelfDescribing selfDescribing = SelfDescribing.builder()
            .eventData(dataAsSelfDescribingJson)
            .subject(subject)
            .build();

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

// A Subject can be provided at Tracker initialisation
// Indirectly, using the Snowplow interface and a SubjectConfiguration object
SubjectConfiguration subjectConfig = new SubjectConfiguration().useragent("useragent");
Tracker tracker = Snowplow.createTracker(
        new TrackerConfiguration("trackerNamespace", "appId"),
        new NetworkConfiguration("http://collector-url"),
        subjectConfig);

// Creating a Tracker directly using Subject and Emitter objects
Subject subject = new Subject();
BatchEmitter emitter = new BatchEmitter(new NetworkConfiguration("http://endpoint"));
Tracker tracker = new Tracker(new TrackerConfiguration("trackerNamespace", "appId"), emitter, subject);

// Alternatively, a Subject can be set later
Tracker tracker = Snowplow.createTracker("trackerNamespace", "appId", "http://collectorEndpoint");
Subject subject = new Subject();
tracker.setSubject(subject);

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
SubjectConfiguration trackerSubjectConfig = new SubjectConfiguration()
        .language("EN")
        .useragent("Snowplow");

Tracker tracker = Snowplow.createTracker(
        new TrackerConfiguration("trackerNamespace", "appId"),
        new NetworkConfiguration("http://collector-url"),
        trackerSubjectConfig);

// Adding an Event-specific Subject
SubjectConfiguration eventSubjectConfig = new SubjectConfiguration()
        .userId("java@snowplowanalytics.com")
        .useragent("Mozilla/5.0");

SelfDescribing selfDescribing = SelfDescribing.builder()
        .eventData(dataAsSelfDescribingJson)
        .subject(new Subject(eventSubjectConfig))
        .build();

// Tracking the event
tracker.track(selfDescribing);

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

Column in enriched event	Value / example value	Source
user_id	"java@snowplowanalytics.com"	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

Overriding autogenerated event properties​

Adding Subject properties to events​

Overriding autogenerated event properties

Adding `Subject` properties to events