Adding extra data: The Subject class

You may have additional information about the user (i.e. subject) performing the action or the environment in which the user has performed the action. Some of that additional data can be sent into Snowplow with each event as part of the subject class.

You can create a subject like this:

from snowplow_tracker import Subject
s = Subject()
Code language: JavaScript (javascript)

The Subject class has a set of set_...() methods to attach extra data relating to the user:

• set_platform
• set_user_id
• set_screen_resolution
• set_viewport
• set_color_depth
• set_timezone
• set_lang

If you initialize a Tracker instance without a subject, a default Subject instance will be attached to the tracker. You can access that subject like this:

t = Tracker(my_emitter)
t.subject.set_platform("mob").set_user_id("user-12345").set_lang("en")
Code language: JavaScript (javascript)

We will discuss each of these in turn below:

Change the tracker’s platform with set_platform

The default platform is “pc”. You can change the platform the subject is using by calling for example:

s.set_platform( {{ PLATFORM }})

For example:

s.set_platform("tv") # Running on a Connected TV
Code language: PHP (php)

For a full list of supported platforms, please see the Snowplow Tracker Protocol.

Set user ID with set_user_id

You can set the user ID to any string:

s.set_user_id( "{{USER ID}}" )
Code language: JavaScript (javascript)

Example:

s.set_user_id("alexd")
Code language: JavaScript (javascript)

Set screen resolution with set_screen_resolution

If your Python code has access to the device’s screen resolution, then you can pass this in to Snowplow too:

s.set_screen_resolution( {{WIDTH}}, {{HEIGHT}} )

Both numbers should be positive integers; note the order is width followed by height. Example:

s.set_screen_resolution(1366, 768)
Code language: CSS (css)

Set viewport dimensions with set_viewport

If your Python code has access to the viewport dimensions, then you can pass this in to Snowplow too:

s.set_viewport( {{WIDTH}}, {{HEIGHT}} )

Both numbers should be positive integers; note the order is width followed by height. Example:

s.set_viewport(300, 200)
Code language: CSS (css)

Set color depth with set_color_depth

If your Python code has access to the bit depth of the device’s color palette for displaying images, then you can pass this in to Snowplow too:

s.set_color_depth( {{BITS PER PIXEL}} )

The number should be a positive integer, in bits per pixel. Example:

s.set_color_depth(32)
Code language: CSS (css)

Set timezone with set_timezone

This method lets you pass a user’s timezone into Snowplow:

s.set_timezone( {{TIMEZONE}} )

The timezone should be a string:

s.set_timezone("Europe/London")
Code language: JavaScript (javascript)

Set the language with set_lang

This method lets you pass a user’s language into Snowplow:

s.set_lang( {{LANGUAGE}} )

The language should be a string:

s.set_lang('en')
Code language: JavaScript (javascript)

Setting the IP address with set_ip_address

If you have access to the user’s IP address, you can set it like this:

s.set_ip_address('34.633.11.139')
Code language: JavaScript (javascript)

Setting the useragent with set_useragent

If you have access to the user’s useragent (sometimes called “browser string”), you can set it like this:

s.set_useragent('Mozilla/5.0 (Windows NT 5.1; rv:23.0) Gecko/20100101 Firefox/23.0')
Code language: JavaScript (javascript)

Setting the domain user ID with set_domain_user_id

The domain_userid field of the Snowplow event model corresponds to the ID stored in the first party cookie set by the Snowplow JavaScript Tracker. If you want to match up server-side events with client-side events, you can set the domain user ID for server-side events like this:

s.set_domain_user_id('c7aadf5c60a5dff9')
Code language: JavaScript (javascript)

You can extract the domain user ID from the cookies of a request using the get_domain_user_id function below. The request argument is, as an example, the Django request object.

Note that this function has not been tested.

import re
def snowplow_cookie(request):
    for name in request.COOKIES:
        if re.match(r"_sp_id", name) != None:
           return request.COOKIES[name]
    return None

def get_domain_user_id(request):
    cookie = snowplow_cookie(request)
    if cookie != None:
        return cookie.split(".")[0]
Code language: JavaScript (javascript)

If you used the “cookieName” configuration option of the Snowplow JavaScript Tracker, replace “sp” with the same string you passed as the cookieName.

Setting the network user ID with set_network_user_id

The network_user_id field of the Snowplow event model corresponds to the ID stored in the third party cookie set by the Snowplow Collector. You can set the network user ID for server-side events like this:

s.set_network_user_id('ecdff4d0-9175-40ac-a8bb-325c49733607')
Code language: JavaScript (javascript)

Tracking multiple subjects

You may want to track more than one subject concurrently. To avoid data about one subject being added to events pertaining to another subject, create two subject instances and switch between them using Tracker.set_subject:

from snowplow_tracker import Subject, Emitter, Tracker

# Create a simple Emitter which will log events to http://d3rkrsqld9gmqf.cloudfront.net/i
e = Emitter("d3rkrsqld9gmqf.cloudfront.net")

# Create a Tracker instance
t = Tracker(emitters=e, namespace="cf", app_id="CF63A")

# Create a Subject corresponding to a pc user
s1 = Subject()

# Set some data for that user
s1.set_platform("pc")
s1.set_user_id("0a78f2867de")

# Set s1 as the tracker subject
# All events fired will have the information we set about s1 attached
t.set_subject(s1)

# Track user s1 viewing a page
t.track_page_view("http://www.example.com")

# Create another Subject instance corresponding to a mobile user
s2 = Subject()

# All methods of the Subject class return the Subject instance so methods can be chained:
s2.set_platform("mob").set_user_id("0b08f8be3f1")

# Change the tracker subject from s1 to s2
# All events fired will have instead have information we set about s2 attached
t.set_subject(s2)

# Track user s2 viewing a page
t.track_page_view("http://www.example.com")

# Switch back to s1 and track a structured event, this time using method chaining:
t.set_subject(s1).track_struct_event("Ecomm", "add-to-basket", "dog-skateboarding-video", "hd", 13.99)

**New in v0.9.0

Since version 0.9.0, it is now possible to set the subject per event, instead of having to mutate the Tracker’s subject. This enables a fine-grained control of the information you may want to add during the user journeys. It also makes the tracking of events idempotent even for multi-threaded applications, since it avoids mutating a shared state. The Tracker-level subject will only be used for events that don’t specify an event subject.

You can specify an event_subject in all track methods. For example:

from snowplow_tracker import Emitter, Tracker, Subject

e = Emitter("0.0.0.0", port=9090)
default_subject = Subject().set_platform("srv")
t = Tracker([e], s) 
# at this point the Tracker's subject is the default_subject. 
# The default_subject will be used in cases where an event_subject is not provided

# specifying event_subject - supported by all track methods
evSubject = Subject().set_platform("srv").set_user_id("tester")
t.track_page_view("www.example.com", event_subject=evSubject)

t.track_add_to_cart("sku1234", 1, event_subject=Subject().set_user_id("Bob"))
Code language: PHP (php)