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);
Code language: PHP (php)

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);
Code language: C++ (cpp)

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

• set_user_id
• set_screen_resolution
• set_viewport
• set_color_depth
• set_timezone
• set_language
• set_useragent
• set_ip_address

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}}" );
Code language: C++ (cpp)

Example:

subject->set_user_id("alexd");
Code language: C++ (cpp)

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}} );
Code language: C++ (cpp)

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

subject->set_screen_resolution(1366, 768);
Code language: C++ (cpp)

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}} );
Code language: C++ (cpp)

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

subject->set_viewport(300, 200);
Code language: C++ (cpp)

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}} );
Code language: C++ (cpp)

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

subject->set_color_depth(32);
Code language: C++ (cpp)

Set timezone with “set_timezone”

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

subject->set_timezone( {{TIMEZONE}} );
Code language: C++ (cpp)

The timezone should be a string:

subject->set_timezone("Europe/London");
Code language: C++ (cpp)

Set the language with “set_language”

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

subject->set_language( {{LANGUAGE}} );
Code language: C++ (cpp)

The language should be a string:

subject->set_language('en');
Code language: C++ (cpp)

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}} );
Code language: C++ (cpp)

The user-agent should be a string:

subject->set_useragent("YourApp/5.0 (Macintosh; Intel Mac OS X 10_15_7)");
Code language: C++ (cpp)

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}} );
Code language: C++ (cpp)

The IP address should be a string:

subject->set_ip_address("169.254.0.2");
Code language: C++ (cpp)

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