Class: SnowplowTracker::Subject

Inherits:
Object
  • Object
show all
Defined in:
lib/snowplow-tracker/subject.rb

Overview

Note:

All the Subject instance methods return the Subject object, allowing method chaining, e.g. SnowplowTracker::Subject.new.set_timezone('Europe/London').set_user_id('12345')

Subject objects store information about the user associated with the event, such as their user_id, what type of device they used, or what size screen that device had. Also, they store which platform the event occurred on - e.g. server-side app, mobile, games console, etc.

Subject parameters are saved into the tracked event as part of the 'atomic' event properties, which have their own column in the eventual table of events. For example, a Subject's user_id parameter will be sent as uid in the raw event payload, ending up in the user_id column. These parameters represent part of the Snowplow Tracker Protocol, which defines a Snowplow event.

Each Tracker is initialized with a Subject. This means that every event by default has the platform (p parameter in the raw event) srv: server-side app. Platform is the only preset Subject parameter, which can be overriden using the #set_platform method. All other parameters must be set manually. This can be done directly on the Subject, or, if it is associated with a Tracker, via the Tracker, which has access to all the methods of its Subject.

Your server-side code may not have access to all these parameters, or they might not be useful to you. All the Subject parameters are optional, except platform.

Since many of the Subject parameters describe the user, different Subject properties may often be desired for each event, if there are multiple users. This can be achieved in one of three ways:

  1. the properties of the Tracker-associated Subject can be overriden by the properties of an event-specific Subject. A Subject can be added to any Tracker #track_x_event method call, as one of the arguments. Remember to set the platform for the event Subject if you're not using srv.
  2. the Tracker-associated Subject can be swapped for another Subject, using the Tracker method Tracker#set_subject.
  3. the properties of the Tracker-associated Subject can be changed before every #track_x_event, by calling the Subject methods via the Tracker.

Examples:

Subject methods can be called from their associated Tracker

# Creating the components explicitly
emitter = SnowplowTracker::Emitter.new(endpoint: 'localhost')
subject = SnowplowTracker::Subject.new
tracker = SnowplowTracker::Tracker.new(emitters: emitter, subject: subject)

# These lines are equivalent
subject.set_user_id('12345')
tracker.set_user_id('12345')

# This would also be equivalent
emitter = SnowplowTracker::Emitter.new(endpoint: 'localhost')
subject = SnowplowTracker::Subject.new
subject.set_user_id('12345')
tracker = SnowplowTracker::Tracker.new(emitters: emitter, subject: subject)

Adding properties to the auto-generated Tracker-associated Subject

# Creating the components
emitter = SnowplowTracker::Emitter.new(endpoint: 'localhost')
tracker = SnowplowTracker::Tracker.new(emitters: emitter)

# Set Subject parameters via the Tracker
tracker.set_user_id('12345')

See Also:

Constant Summary collapse

SUPPORTED_PLATFORMS =
p value Platform
app General App
cnsl Games Console
iot Internet of Things
mob Mobile/Tablet
pc Desktop/Laptop/Netbook
srv [DEFAULT] Server-side App
tv Connected TV
web Web (including Mobile Web) 
%w[app cnsl iot mob pc srv tv web]

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Subject

Returns a new instance of Subject.



118
119
120
 
# File 'lib/snowplow-tracker/subject.rb', line 118

def initialize
  @details = { 'p' => DEFAULT_PLATFORM }
end

Instance Attribute Details

#details ⇒ Object (readonly)

Access the Subject parameters

Examples:

SnowplowTracker::Subject.new.set_user_id('12345').details
=> {"p"=>"srv", "uid"=>"12345"}


115
116
117
 
# File 'lib/snowplow-tracker/subject.rb', line 115

def details
  @details
end

Instance Method Details

#set_color_depth(depth) ⇒ Object

Note:

Value is sent in the event as cd (raw event) or br_colordepth (processed event).

Set the color depth of the browser, in bits per pixel.

Examples:

subject.set_color_depth(24)

Parameters:

  • depth (Num) —

    the colour depth

Returns:

  • self



200
201
202
203
 
# File 'lib/snowplow-tracker/subject.rb', line 200

def set_color_depth(depth)
  @details['cd'] = depth
  self
end

#set_domain_session_id(sid) ⇒ Object

Note:

Value is sent in the event as sid (raw event) or domain_sessionid (processed event).

Set the domain session ID. The domain_sessionid is a client-side unique ID for a user's current session. It is set by the browser-based JavaScript trackers, and stored in a first party cookie (cookie name: _sp_id), along with other parameters such as domain_userid. For stitching together client-side and server-side events originating from the same user and session, the domain session ID can be extracted from the cookie and set using this method.

Examples:

subject.set_domain_session_id('9c65e7f3-8e8e-470d-b243-910b5b300da0')

Parameters:

  • sid (String) —

    the unique domain session ID

Returns:

  • self

See Also:



281
282
283
284
 
# File 'lib/snowplow-tracker/subject.rb', line 281

def set_domain_session_id(sid)
  @details['sid'] = sid
  self
end

#set_domain_session_idx(vid) ⇒ Object

Note:

Value is sent in the event as vid (raw event) or domain_sessionidx (processed event).

Set the domain session index. The domain_sessionidx is a client-side property that records how many visits (unique domain_sessionids) a user (a unique domain_userid) has made to the site. It is stored in the first party cookie set by the JavaScript tracker, along with other parameters such as domain_userid. For stitching together client-side and server-side events originating from the same user and session, the domain session index can be extracted from the cookie and set using this method.

Examples:

subject.set_domain_session_idx(3)

Parameters:

  • vid (Num) —

    the number of sessions

Returns:

  • self

See Also:



304
305
306
307
 
# File 'lib/snowplow-tracker/subject.rb', line 304

def set_domain_session_idx(vid)
  @details['vid'] = vid
  self
end

#set_domain_user_id(duid) ⇒ Object

Note:

Value is sent in the event as duid (raw event) or domain_userid (processed event).

Set the domain user ID. The domain_userid is a client-side unique user ID, which is set by the browser-based JavaScript tracker, and stored in a first party cookie (cookie name: _sp_id). For stitching together client-side and server-side events originating from the same user, the domain user ID can be extracted from the cookie and set using this method. A third party gem, snowplow_ruby_duid, has been created to help with this.

Examples:

subject.set_domain_user_id('aeb1691c5a0ee5a6')

Ruby on Rails: getting the domain_user_id from the cookie

# Assuming the Snowplow JavaScript has also been incorporated
# cookies are accessible only within a Controller
def snowplow_domain_userid
  sp_cookie = cookies.find { |key, _value| key =~ /^_sp_id/ }
  sp_cookie.last.split(".").first if sp_cookie.present?
end

Parameters:

  • duid (String) —

    the unique domain user ID

Returns:

  • self

See Also:



259
260
261
262
 
# File 'lib/snowplow-tracker/subject.rb', line 259

def set_domain_user_id(duid)
  @details['duid'] = duid
  self
end

#set_fingerprint(fingerprint) ⇒ Object

Note:

Value is sent in the event as fp (raw event) or user_fingerprint (processed event).

Set a business-defined fingerprint for a user.

Examples:

subject.set_fingerprint(4048966212)

Parameters:

  • fingerprint (Num) —

    a user fingerprint

Returns:

  • self



162
163
164
165
 
# File 'lib/snowplow-tracker/subject.rb', line 162

def set_fingerprint(fingerprint)
  @details['fp'] = fingerprint
  self
end

#set_ip_address(ip) ⇒ Object

Note:

Value is sent in the event as ip (raw event) or user_ipaddress (processed event).

Set the user's IP address.

Examples:

subject.set_ip_address('37.157.33.178')

Parameters:

  • ip (String) —

    the IP address

Returns:

  • self



316
317
318
319
 
# File 'lib/snowplow-tracker/subject.rb', line 316

def set_ip_address(ip)
  @details['ip'] = ip
  self
end

#set_lang(lang) ⇒ Object

Note:

Value is sent in the event as lang (raw event) or br_lang (processed event).

Set the language.

Examples:

Setting the language to Spanish

subject.set_lang('es')

Parameters:

  • lang (String) —

    the language being used on the device

Returns:

  • self



224
225
226
227
 
# File 'lib/snowplow-tracker/subject.rb', line 224

def set_lang(lang)
  @details['lang'] = lang
  self
end

#set_network_user_id(nuid) ⇒ Object

Note:

Value is sent in the event as tnuid (raw event) and network_userid (processed event).

Set the network user ID. The network user ID is, like the domain_userid, a cookie-based unique user ID. It is stored in a third party cookie set by the event collector, hence the name "network" as it is set at a network level. It is the server-side user identifier. The raw event does not contain a nuid value; the network_userid property is added when the event is processed.

The default behaviour is for the collector to provide a new cookie/network user ID for each event it receives. This method provides the ability to override the collector cookie's value with your own generated ID.

Domain user IDs set on the Subject in this way are sent as tnuid in the raw event.

Examples:

subject.set_network_user_id('ecdff4d0-9175-40ac-a8bb-325c49733607')

Parameters:

  • nuid (String) —

    the network user ID

Returns:

  • self

See Also:



355
356
357
358
 
# File 'lib/snowplow-tracker/subject.rb', line 355

def set_network_user_id(nuid)
  @details['tnuid'] = nuid
  self
end

#set_platform(platform) ⇒ Object

Note:

Value is sent in the event as p (raw event) or platform (processed event).

Set the platform to one of the supported platform values.

Examples:

subject.set_platform('app')

Parameters:

  • platform (String) —

    a valid platform choice

Returns:

  • self

See Also:



130
131
132
133
134
135
 
# File 'lib/snowplow-tracker/subject.rb', line 130

def set_platform(platform)
  raise "#{platform} is not a supported platform" unless SUPPORTED_PLATFORMS.include?(platform)

  @details['p'] = platform
  self
end

#set_screen_resolution(width:, height:) ⇒ Object

Note:

Value is sent in the event as res (raw event) or dvce_screenheight and dvce_screenwidth (processed event).

Set the device screen resolution.

Examples:

subject.set_screen_resolution(width: 2880, height: 1800)

Parameters:

  • width (Integer) —

    the screen width, in pixels (must be a positive integer)

  • height (Integer) —

    the screen height, in pixels (must be a positive integer)

Returns:

  • self



175
176
177
178
 
# File 'lib/snowplow-tracker/subject.rb', line 175

def set_screen_resolution(width:, height:)
  @details['res'] = "#{width}x#{height}"
  self
end

#set_timezone(timezone) ⇒ Object

Note:

Value is sent in the event as tz (raw event) or os_timezone (processed event).

Set the timezone to that of the user's OS.

Examples:

subject.set_timezone('Africa/Lagos')

Parameters:

  • timezone (String) —

    the timezone

Returns:

  • self



212
213
214
215
 
# File 'lib/snowplow-tracker/subject.rb', line 212

def set_timezone(timezone)
  @details['tz'] = timezone
  self
end

#set_user_id(user_id) ⇒ Object

Note:

Value is sent in the event as uid (raw event) or user_id (processed event).

Set the unique business-defined user ID for a user. For example, an email address.

Examples:

Example user IDs

# an email address
janet.bloggs@email.com

# a username
janetabloggs2021

Parameters:

  • user_id (String) —

    a unique user ID

Returns:

  • self



150
151
152
153
 
# File 'lib/snowplow-tracker/subject.rb', line 150

def set_user_id(user_id)
  @details['uid'] = user_id
  self
end

#set_useragent(useragent) ⇒ Object

Note:

Value is sent in the event as ua (raw event) or useragent (processed event).

Set the browser user agent.

Examples:

subject.set_useragent('Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:92.0) Gecko/20100101 Firefox/92.0')

Parameters:

  • useragent (String) —

    the user agent string

Returns:

  • self



328
329
330
331
 
# File 'lib/snowplow-tracker/subject.rb', line 328

def set_useragent(useragent)
  @details['ua'] = useragent
  self
end

#set_viewport(width:, height:) ⇒ Object

Note:

Value is sent in the event as vp (raw event) or br_viewwidth and br_viewheight (processed event).

Set the dimensions of the current viewport.

Examples:

subject.set_viewport(width: 1440, height: 762)

Parameters:

  • width (Integer) —

    the viewport width, in pixels (must be a positive integer)

  • height (Integer) —

    the viewport height, in pixels (must be a positive integer)

Returns:

  • self



188
189
190
191
 
# File 'lib/snowplow-tracker/subject.rb', line 188

def set_viewport(width:, height:)
  @details['vp'] = "#{width}x#{height}"
  self
end