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 the addition of a persistent set of information through the SubjectConfiguration, which represents the basic information about the user and the app. This data is added to every event as part of the canonical event properties.

Property	Description	Automatically added?	Column(s) in enriched event
userId	User identifier.	❌	user_id
ipAddress	User IP address.	✅	user_ipaddress
timezone	Current timezone label.	✅	os_timezone
language	Language set in the device.	✅	br_lang
useragent	User-agent.	✅	useragent
viewport	Screen viewport.	✅ (iOS) / ❌ (Android)	br_viewheight, br_viewwidth
screenResolution	Screen resolution.	✅	dvce_screenheight, dvce_screenwidth
colorDepth	Screen color depth.	❌	br_colordepth
networkUserId	Network user ID.	✅	network_userid
domainUserId	Domain user ID.	❌	domain_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.

Android screen resolution

The default screen resolution values are fetched from WindowManager, an older Android API. Screen resolution is also reported in the platform context entity, which obtains the screen size from the Android context resources. The height value will likely be higher in dvce_screenheight than in the context entity, as the WindowManager size includes the menu bar.

To use the modern API throughout the tracker and standardize the screen resolution between event and entity properties, set useContextResourcesScreenResolution(true) flag in SubjectConfiguration. This flag is off by default, and available from Android tracker v6.0.3 onwards.

Overriding autogenerated event properties

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

Unless anonymous tracking with server anonymisation is enabled, the user_ipaddress is automatically added to all enriched events. To manually override this without using anonymous tracking, use a SubjectConfiguration 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, 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, set networkUserId. Again, anonymous tracking with server anonymisation will prevent the addition of this property to events. The network_userid is stored in the tracker and is kept the same until the app is deleted or the collector endpoint is changed or the cookie is expired.

All other Subject properties can also be manually overriden via SubjectConfiguration and SubjectController.

Set the Subject properties

Initialize the tracker with a SubjectConfiguration like this:

iOS

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

let networkConfig = NetworkConfiguration(endpoint: "https://snowplow-collector-url.com")
Snowplow.createTracker(
    namespace: "appTracker",
    network: networkConfig,
    configurations: [subjectConfig]
)

See the API docs for the full list of options.

Android (Kotlin)

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

val networkConfig = NetworkConfiguration("[http:/endpoint](https://snowplow-collector-url.com)")
Snowplow.createTracker(
    applicationContext,
    "namespace",
    networkConfig,
    subjectConfig
)

See the API docs for the full list of options.

Android (Java)

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

NetworkConfiguration networkConfig = new NetworkConfiguration(
    "https://snowplow-collector-url.com"
);
Snowplow.createTracker(
    getApplicationContext(),
    "appTracker",
    networkConfig,
    subjectConfig
);

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("");