Adding extra data: the Subject class

Subject information describes the user and device associated with the event, such as their user ID, what type of device they used, or what size screen that device had.

Create a subject like this and add it to your tracker using the Snowplow::create_tracker call:

auto subject = make_shared<Subject>();
subject.set_user_id("a-user-id");

auto tracker = Snowplow::create_tracker("ns", "https://com.acme.collector", POST, "events.db", subject);

You can also attach custom Subject information to individual events. In this way, you may track events describing different users or devices using the same tracker. Events can be assigned a shared C++ pointer to a Subject instance using the set_subject method. The following example shows how to attach a subject instance to a structured event (see Tracking specific events for more information on tracking events):

auto subject = std::make_shared<Subject>();
subject->set_user_id("another-user");

StructuredEvent se("category", "action");
se.set_subject(subject);

The Subject class has a set of set...() methods to attach extra data relating to the user to all tracked events. The below table maps the setter functions to the event properties that they affect.

Setter method	Resulting event property
set_user_id	user_id
set_screen_resolution	dvce_screenwidth and dvce_screenheight
set_viewport	br_viewwidth and br_viewheight
set_color_depth	br_colordepth
set_timezone	os_timezone
`set_language	br_lang
set_useragent	useragent
set_ip_address	user_ipaddress

We will discuss each of these in turn below:

Set user ID with "set_user_id"

You can set the user ID to any string:

subject->set_user_id( "{{USER ID}}" );

Example:

subject->set_user_id("alexd");

Set screen resolution with "set_screen_resolution"

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

subject->set_screen_resolution( {{WIDTH}}, {{HEIGHT}} );

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

subject->set_screen_resolution(1366, 768);

Set viewport dimensions with "set_viewport"

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

subject->set_viewport( {{WIDTH}}, {{HEIGHT}} );

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

subject->set_viewport(300, 200);

Set color depth with "set_color_depth"

If your 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:

subject->set_color_depth( {{BITS PER PIXEL}} );

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

subject->set_color_depth(32);

Set timezone with "set_timezone"

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

subject->set_timezone( {{TIMEZONE}} );

The timezone should be a string:

subject->set_timezone("Europe/London");

Set the language with "set_language"

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

subject->set_language( {{LANGUAGE}} );

The language should be a string:

subject->set_language('en');

Set custom user-agent with "set_useragent"

To change the user-agent string sent along with events to identify the application and system, you may set custom useragent using this method:

subject->set_useragent( {{USERAGENT}} );

The user-agent should be a string:

subject->set_useragent("YourApp/5.0 (Macintosh; Intel Mac OS X 10_15_7)");

Set user's IP address with "set_ip_address"

To set the user's IP address, you may use this method:

subject->set_ip_address( {{IP_ADDRESS}} );

The IP address should be a string:

subject->set_ip_address("169.254.0.2");

If the IP address is not set, the events will be assigned the IP address from the HTTP request by the Collector.