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.

The tracker allows to add a persistent set of information through the SubjectConfiguration which represents the basic information about the user and the app which will be attached on all the events as context entity.

• userId = null: The custom user identifier.
• useragent = null: The custom user-agent. It overrides the user-agent used by default.
• ipAddress = null: The IP address (not automatically set).
• timezone (set by the tracker): The current timezone label.
• language (set by the tracker): The language set in the device.
• screenResolution (set by the tracker): The screen resolution.
• screenViewPort = null: The screen viewport.
• colorDepth = null: The color depth.

The fields tracked using SubjectConfiguration are 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

As always, be aware of privacy when tracking personal identifiable information such as email addresses or IP addresses. The tracker provides anonymous tracking functionality to mask certain user identifiers. Refer to the section on anonymous tracking to learn more.

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 (unless anonymous tracking with server anonymisation is enabled). To manually override this, use a Subject and set an ipAddress string; use an empty string to prevent IP address tracking. Alternatively, use the IP anonymization enrichment.

The useragent is also automatically added but it can be overriden on configuration. Snowplow pipelines provide multiple useragent-parsing enrichments. To manually override the detected useragent, use a Subject and set a useragent string.

The network_userid is the cookie value for the event collector's third-party cookie. The cookie is named sp (or micro for Snowplow Micro pipelines). To override the collector cookie’s value with your own generated ID, use a Subject object and set networkUserId.

The network_userid is stored in the tracker and it's kept the same until the app is deleted or the collector endpoint is changed or the cookie is expired. It is not assigned to events if anonymous tracking with server anonymisation is enabled.

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.

Set the SubjectConfiguration

A simple SubjectConfiguration initialisation looks like this:

iOS

let subjectConfig = SubjectConfiguration()
    .userId("username")

See the API docs for the full list of options.

Android (Kotlin)

val subjectConfig = SubjectConfiguration()
    .userId("username")

See the API docs for the full list of options.

Android (Java)

SubjectConfiguration subjectConfig = new SubjectConfiguration()
    .userId("username");

See the API docs for the full list of options.

Subject properties can be updated or added to after initialization using the SubjectController retrieved from the tracker:

iOS

let tracker = Snowplow.defaultTracker()
tracker?.subject?.userId = ""

Android (Kotlin)

val tracker = Snowplow.defaultTracker
tracker?.subject?.userId = ''

Android (Java)

TrackerController tracker = Snowplow.getDefaultTracker();
tracker.getSubject().setUserId("");