snowplow-tracker 0.6.1 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,4 +1,4 @@
1
- # Copyright (c) 2013-2014 Snowplow Analytics Ltd. All rights reserved.
1
+ # Copyright (c) 2013-2021 Snowplow Analytics Ltd. All rights reserved.
2
2
  #
3
3
  # This program is licensed to you under the Apache License Version 2.0,
4
4
  # and you may not use this file except in compliance with the Apache License Version 2.0.
@@ -9,65 +9,61 @@
9
9
  # "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
10
10
  # See the Apache License Version 2.0 for the specific language governing permissions and limitations there under.
11
11
 
12
- # Author:: Alex Dean, Fred Blundun (mailto:support@snowplowanalytics.com)
13
- # Copyright:: Copyright (c) 2013-2014 Snowplow Analytics Ltd
12
+ # Author:: Snowplow Analytics Ltd
13
+ # Copyright:: Copyright (c) 2013-2021 Snowplow Analytics Ltd
14
14
  # License:: Apache License Version 2.0
15
15
 
16
+
16
17
  require 'base64'
17
18
  require 'json'
18
19
  require 'net/http'
19
20
  require 'contracts'
20
21
 
21
22
  module SnowplowTracker
22
-
23
+ # @private
24
+ # Every`track_x_event` method creates a new Payload object. The Tracker then
25
+ # uses the Payload instance methods to add properties to the Payload `@data`
26
+ # hash. These properties form the raw event, after the completed hash is
27
+ # given to the Emitter.
23
28
  class Payload
24
-
25
29
  include Contracts
26
30
 
27
- attr_reader :context
31
+ attr_reader :data
28
32
 
29
- Contract nil => Payload
33
+ Contract nil => Any
30
34
  def initialize
31
- @context = {}
32
- self
35
+ @data = {}
33
36
  end
34
37
 
35
- # Add a single name-value pair to @context
36
- #
37
38
  Contract String, Or[String, Bool, Num, nil] => Or[String, Bool, Num, nil]
39
+ # Add a single name-value pair to @data.
38
40
  def add(name, value)
39
- if value != "" and not value.nil?
40
- @context[name] = value
41
- end
41
+ @data[name] = value if (value != '') && !value.nil?
42
42
  end
43
-
44
- # Add each name-value pair in dict to @context
45
- #
43
+
46
44
  Contract Hash => Hash
47
- def add_dict(dict)
48
- for f in dict
49
- self.add(f[0], f[1])
50
- end
45
+ # Add each name-value pair in a hash to @data.
46
+ def add_hash(hash)
47
+ hash.each { |key, value| add(key, value) }
51
48
  end
52
49
 
53
- # Stringify a JSON and add it to @context
54
- #
55
50
  Contract Maybe[Hash], Bool, String, String => Maybe[String]
56
- def add_json(dict, encode_base64, type_when_encoded, type_when_not_encoded)
57
-
58
- if dict.nil?
59
- return
60
- end
61
-
62
- dict_string = JSON.generate(dict)
51
+ # Stringify a JSON and add it to @data.
52
+ #
53
+ # In practice, the JSON provided will be a SelfDescribingJson. This method
54
+ # is used to add context to events, or for `track_self_describing_event`.
55
+ # @see Tracker#track_unstruct_event
56
+ # @see Tracker#finalise_payload
57
+ def add_json(json, encode_base64, type_when_encoded, type_when_not_encoded)
58
+ return if json.nil?
59
+
60
+ stringified = JSON.generate(json)
63
61
 
64
62
  if encode_base64
65
- self.add(type_when_encoded, Base64.strict_encode64(dict_string))
63
+ add(type_when_encoded, Base64.strict_encode64(stringified))
66
64
  else
67
- self.add(type_when_not_encoded, dict_string)
65
+ add(type_when_not_encoded, stringified)
68
66
  end
69
-
70
67
  end
71
-
72
68
  end
73
69
  end
@@ -1,4 +1,4 @@
1
- # Copyright (c) 2013-2014 Snowplow Analytics Ltd. All rights reserved.
1
+ # Copyright (c) 2013-2021 Snowplow Analytics Ltd. All rights reserved.
2
2
  #
3
3
  # This program is licensed to you under the Apache License Version 2.0,
4
4
  # and you may not use this file except in compliance with the Apache License Version 2.0.
@@ -9,26 +9,109 @@
9
9
  # "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
10
10
  # See the Apache License Version 2.0 for the specific language governing permissions and limitations there under.
11
11
 
12
- # Author:: Alex Dean, Fred Blundun (mailto:support@snowplowanalytics.com)
13
- # Copyright:: Copyright (c) 2013-2014 Snowplow Analytics Ltd
12
+ # Author:: Snowplow Analytics Ltd
13
+ # Copyright:: Copyright (c) 2013-2021 Snowplow Analytics Ltd
14
14
  # License:: Apache License Version 2.0
15
15
 
16
- module SnowplowTracker
17
16
 
17
+ module SnowplowTracker
18
+ # Creates the self-describing JSONs necessary for sending context or
19
+ # self-describing events. These are a specific kind of [JSON
20
+ # schema](http://json-schema.org/).
21
+ #
22
+ # A unique schema can be designed for each type of event or entity (for event
23
+ # context) that you want to track. This allows you to track the specific
24
+ # things that are important to you, in a way that is defined by you.
25
+ #
26
+ # A self-describing JSON has two keys, `schema` and `data`. The `schema` value
27
+ # should point to a valid self-describing JSON schema. They are called
28
+ # self-describing because the schema will specify the fields allowed in the
29
+ # `data` value. After events have been collected by the event collector, they
30
+ # are validated to ensure that the self-describing JSONs are correct. Mistakes
31
+ # (e.g. extra fields, or incorrect types) will result in events being
32
+ # processed as Bad Events.
33
+ #
34
+ # A SelfDescribingJson is initialized with `schema` and `data` as separate
35
+ # arguments. These parameters are combined into a complete self-describing
36
+ # JSON during the event creation, which is stringified and sent as part of the
37
+ # event. By default, they will be sent base64-encoded. This can be changed on
38
+ # {Tracker} initialization.
39
+ #
40
+ # The `data` argument must be a flat hash of key-value pairs. Either strings
41
+ # or symbols are accepted as keys. The `schema` argument must be a correctly
42
+ # formatted schema ID.
43
+ #
44
+ # When used to send event context data, stringified self-describing JSONs will
45
+ # be sent in the raw event as `cx`, or `co` if not encoded. Whether encoded or
46
+ # not, these strings will be converted back to JSON within the `contexts`
47
+ # parameter of the processed event. All the event context is contained within
48
+ # this one parameter, even if multiple context entities were sent.
49
+ #
50
+ # Self-describing JSONs in self-describing events are sent in a similar
51
+ # manner. They are sent as `ue_px` in the raw event, or `ue_pr` if not
52
+ # encoded. This is processed into the `unstruct_event` parameter of the
53
+ # finished event.
54
+ #
55
+ # @example
56
+ # # This example schema describes an ad_click event.
57
+ # # It defines a single property for that event type, a "bannerId".
58
+ #
59
+ # {
60
+ # "$schema": "http://json-schema.org/schema#",
61
+ # "self": {
62
+ # "vendor": "com.snowplowanalytics",
63
+ # "name": "ad_click",
64
+ # "format": "jsonschema",
65
+ # "version": "1-0-0"
66
+ # },
67
+ # "type": "object",
68
+ # "properties": {
69
+ # "bannerId": {
70
+ # "type": "string"
71
+ # }
72
+ # },
73
+ # "required": ["bannerId"],
74
+ # "additionalProperties": false
75
+ # }
76
+ #
77
+ # # Creating the SelfDescribingJson
78
+ # schema_name = "iglu:com.snowplowanalytics/ad_click/jsonschema/1-0-0"
79
+ # event_data = { bannerId: "4acd518feb82" }
80
+ # SelfDescribingJson.new(schema_name, event_data)
81
+ #
82
+ # # The self-describing JSON that will be sent (stringified) with the event
83
+ # {
84
+ # "schema": "iglu:com.snowplowanalytics/ad_click/jsonschema/1-0-0",
85
+ # "data": {
86
+ # "bannerId": "4acd518feb82"
87
+ # }
88
+ # }
89
+ #
90
+ # @api public
91
+ # @see
92
+ # https://docs.snowplowanalytics.com/docs/understanding-tracking-design/understanding-schemas-and-validation/
93
+ # introduction to Snowplow schemas
94
+ # @see
95
+ # https://docs.snowplowanalytics.com/docs/pipeline-components-and-applications/iglu/
96
+ # schema management using Iglu
97
+ # @see
98
+ # https://docs.snowplowanalytics.com/docs/collecting-data/collecting-from-own-applications/snowplow-tracker-protocol
99
+ # the Snowplow Tracker Protocol
18
100
  class SelfDescribingJson
19
-
101
+ # @param schema [String] schema identifier
102
+ # @param data [Hash] a flat hash that matches the description in the schema
20
103
  def initialize(schema, data)
21
104
  @schema = schema
22
105
  @data = data
23
106
  end
24
107
 
108
+ # make the self-describing JSON out of the instance variables
109
+ # @private
25
110
  def to_json
26
111
  {
27
- :schema => @schema,
28
- :data => @data
112
+ schema: @schema,
113
+ data: @data
29
114
  }
30
115
  end
31
-
32
116
  end
33
-
34
117
  end
@@ -1,4 +1,4 @@
1
- # Copyright (c) 2013-2014 Snowplow Analytics Ltd. All rights reserved.
1
+ # Copyright (c) 2013-2021 Snowplow Analytics Ltd. All rights reserved.
2
2
  #
3
3
  # This program is licensed to you under the Apache License Version 2.0,
4
4
  # and you may not use this file except in compliance with the Apache License Version 2.0.
@@ -9,131 +9,354 @@
9
9
  # "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
10
10
  # See the Apache License Version 2.0 for the specific language governing permissions and limitations there under.
11
11
 
12
- # Author:: Alex Dean, Fred Blundun (mailto:support@snowplowanalytics.com)
13
- # Copyright:: Copyright (c) 2013-2014 Snowplow Analytics Ltd
12
+ # Author:: Snowplow Analytics Ltd
13
+ # Copyright:: Copyright (c) 2013-2021 Snowplow Analytics Ltd
14
14
  # License:: Apache License Version 2.0
15
15
 
16
+
16
17
  require 'contracts'
17
18
 
18
19
  module SnowplowTracker
19
-
20
+ # Subject objects store information about the user associated with the event,
21
+ # such as their `user_id`, what type of device they used, or what size screen
22
+ # that device had. Also, they store which platform the event occurred on -
23
+ # e.g. server-side app, mobile, games console, etc.
24
+ #
25
+ # Subject parameters are saved into the tracked event as part of the 'atomic'
26
+ # event properties, which have their own column in the eventual table of
27
+ # events. For example, a Subject's `user_id` parameter will be sent as `uid`
28
+ # in the raw event payload, ending up in the `user_id` column. These
29
+ # parameters represent part of the [Snowplow Tracker
30
+ # Protocol](https://docs.snowplowanalytics.com/docs/collecting-data/collecting-from-own-applications/snowplow-tracker-protocol),
31
+ # which defines a Snowplow event.
32
+ #
33
+ # Each {Tracker} is initialized with a Subject. This means that every event by
34
+ # default has the platform (`p` parameter in the raw event) `srv`: server-side
35
+ # app. Platform is the only preset Subject parameter, which can be overriden
36
+ # using the {#set_platform} method. All other parameters must be set manually.
37
+ # This can be done directly on the Subject, or, if it is associated with a
38
+ # Tracker, via the Tracker, which has access to all the methods of its
39
+ # Subject.
40
+ #
41
+ # Your server-side code may not have access to all these parameters, or they
42
+ # might not be useful to you. All the Subject parameters are optional, except
43
+ # `platform`.
44
+ #
45
+ # @example Subject methods can be called from their associated Tracker
46
+ # # Creating the components explicitly
47
+ # emitter = SnowplowTracker::Emitter.new(endpoint: 'localhost')
48
+ # subject = SnowplowTracker::Subject.new
49
+ # tracker = SnowplowTracker::Tracker.new(emitters: emitter, subject: subject)
50
+ #
51
+ # # These lines are equivalent
52
+ # subject.set_user_id('12345')
53
+ # tracker.set_user_id('12345')
54
+ #
55
+ # # This would also be equivalent
56
+ # emitter = SnowplowTracker::Emitter.new(endpoint: 'localhost')
57
+ # subject = SnowplowTracker::Subject.new
58
+ # subject.set_user_id('12345')
59
+ # tracker = SnowplowTracker::Tracker.new(emitters: emitter, subject: subject)
60
+ #
61
+ # @example Adding properties to the auto-generated Tracker-associated Subject
62
+ # # Creating the components
63
+ # emitter = SnowplowTracker::Emitter.new(endpoint: 'localhost')
64
+ # tracker = SnowplowTracker::Tracker.new(emitters: emitter)
65
+ #
66
+ # # Set Subject parameters via the Tracker
67
+ # tracker.set_user_id('12345')
68
+ #
69
+ # Since many of the Subject parameters describe the user, different Subject
70
+ # properties may often be desired for each event, if there are multiple users.
71
+ # This can be achieved in one of two ways:
72
+ #
73
+ # 1. the properties of the Tracker-associated Subject can be overriden by the
74
+ # properties of an event-specific Subject. A Subject can be added to any
75
+ # Tracker `#track_x_event` method call, as one of the arguments. Remember to
76
+ # set the platform for the event Subject if you're not using `srv`.
77
+ # 2. the Tracker-associated Subject can be swapped for another Subject, using
78
+ # the Tracker method {Tracker#set_subject}.
79
+ #
80
+ # @see Tracker#set_subject
81
+ # @see
82
+ # https://docs.snowplowanalytics.com/docs/collecting-data/collecting-from-own-applications/snowplow-tracker-protocol
83
+ # the Snowplow Tracker Protocol
84
+ # @api public
85
+ #
86
+ # @note All the Subject instance methods return the Subject object, allowing
87
+ # method chaining, e.g.
88
+ # `Subject.new.set_timezone('Europe/London').set_user_id('12345')`
20
89
  class Subject
21
-
22
90
  include Contracts
23
91
 
24
- @@default_platform = 'srv'
25
- @@supported_platforms = ['pc', 'tv', 'mob', 'cnsl', 'iot']
92
+ # @private
93
+ DEFAULT_PLATFORM = 'srv'
94
+
95
+ # @api public
96
+ #
97
+ # | `p` value | Platform |
98
+ # | ---- | ---- |
99
+ # | app | General App |
100
+ # | cnsl | Games Console |
101
+ # | iot | Internet of Things |
102
+ # | mob | Mobile/Tablet |
103
+ # | pc | Desktop/Laptop/Netbook |
104
+ # | srv [DEFAULT] | Server-side App |
105
+ # | tv | Connected TV |
106
+ # | web | Web (including Mobile Web) |
107
+ SUPPORTED_PLATFORMS = %w[app cnsl iot mob pc srv tv web]
26
108
 
27
- attr_reader :standard_nv_pairs
109
+ # Access the Subject parameters
110
+ # @example
111
+ # Subject.new.set_user_id('12345').details
112
+ # => {"p"=>"srv", "uid"=>"12345"}
113
+ # @api public
114
+ attr_reader :details
28
115
 
29
- Contract None => Subject
116
+ Contract None => Any
117
+ # @api public
30
118
  def initialize
31
- @standard_nv_pairs = {"p" => @@default_platform}
32
- self
119
+ @details = { 'p' => DEFAULT_PLATFORM }
33
120
  end
34
121
 
35
- # Specify the platform
36
- #
37
122
  Contract String => Subject
38
- def set_platform(value)
39
- if @@supported_platforms.include?(value)
40
- @standard_nv_pairs['p'] = value
41
- else
42
- raise "#{value} is not a supported platform"
43
- end
123
+ # Set the platform to one of the supported platform values.
124
+ # @note Value is sent in the event as `p` (raw event) or `platform` (processed event).
125
+ # @see Subject::SUPPORTED_PLATFORMS
126
+ # @param [String] platform a valid platform choice
127
+ # @return self
128
+ # @api public
129
+ def set_platform(platform)
130
+ raise "#{platform} is not a supported platform" unless SUPPORTED_PLATFORMS.include?(platform)
44
131
 
132
+ @details['p'] = platform
45
133
  self
46
134
  end
47
135
 
48
- # Set the business-defined user ID for a user
49
- #
50
136
  Contract String => Subject
137
+ # Set the unique business-defined user ID for a user.
138
+ # @note Value is sent in the event as `uid` (raw event) or `user_id` (processed event).
139
+ # For example, an email address.
140
+ # @example Example user IDs
141
+ # # an email address
142
+ # janet.bloggs@email.com
143
+ #
144
+ # # a username
145
+ # janetabloggs2021
146
+ #
147
+ # @param [String] user_id a unique user ID
148
+ # @return self
149
+ # @api public
51
150
  def set_user_id(user_id)
52
- @standard_nv_pairs['uid'] = user_id
151
+ @details['uid'] = user_id
53
152
  self
54
153
  end
55
154
 
56
- # Set fingerprint for the user
57
- #
58
155
  Contract Num => Subject
156
+ # Set a business-defined fingerprint for a user.
157
+ # @note Value is sent in the event as `fp` (raw event) or `user_fingerprint` (processed event).
158
+ # @param [Num] fingerprint a user fingerprint
159
+ # @return self
160
+ # @api public
59
161
  def set_fingerprint(fingerprint)
60
- @standard_nv_pairs['fp'] = fingerprint
162
+ @details['fp'] = fingerprint
61
163
  self
62
164
  end
63
165
 
64
- # Set the screen resolution for a device
65
- #
66
- Contract Num, Num => Subject
67
- def set_screen_resolution(width, height)
68
- @standard_nv_pairs['res'] = "#{width}x#{height}"
166
+ Contract KeywordArgs[width: Num, height: Num] => Subject
167
+ # Set the device screen resolution.
168
+ # @note Value is sent in the event as `res` (raw event) or `dvce_screenheight` and `dvce_screenwidth` (processed event).
169
+ # @param [Num] width the screen width, in pixels (must be a positive integer)
170
+ # @param [Num] height the screen height, in pixels (must be a positive integer)
171
+ # @return self
172
+ # @api public
173
+ def set_screen_resolution(width:, height:)
174
+ @details['res'] = "#{width}x#{height}"
69
175
  self
70
176
  end
71
177
 
72
- # Set the dimensions of the current viewport
73
- #
74
- Contract Num, Num => Subject
75
- def set_viewport(width, height)
76
- @standard_nv_pairs['vp'] = "#{width}x#{height}"
178
+ Contract KeywordArgs[width: Num, height: Num] => Subject
179
+ # Set the dimensions of the current viewport.
180
+ # @note Value is sent in the event as `vp` (raw event) or `br_viewwidth` and `br_viewheight` (processed event).
181
+ # @param [Num] width the viewport width, in pixels (must be a positive integer)
182
+ # @param [Num] height the viewport height, in pixels (must be a positive integer)
183
+ # @return self
184
+ # @api public
185
+ def set_viewport(width:, height:)
186
+ @details['vp'] = "#{width}x#{height}"
77
187
  self
78
188
  end
79
189
 
80
- # Set the color depth of the device in bits per pixel
81
- #
82
190
  Contract Num => Subject
191
+ # Set the color depth of the device, in bits per pixel.
192
+ # @note Value is sent in the event as `cd` (raw event) or `br_colordepth` (processed event).
193
+ # @param [Num] depth the colour depth
194
+ # @return self
195
+ # @api public
83
196
  def set_color_depth(depth)
84
- @standard_nv_pairs['cd'] = depth
197
+ @details['cd'] = depth
85
198
  self
86
199
  end
87
200
 
88
- # Set the timezone field
89
- #
90
201
  Contract String => Subject
202
+ # Set the timezone to that of the user's OS.
203
+ # @note Value is sent in the event as `tz` (raw event) or `os_timezone` (processed event).
204
+ # @example
205
+ # subject.set_timezone('Africa/Lagos')
206
+ # @param [String] timezone the timezone
207
+ # @return self
208
+ # @api public
91
209
  def set_timezone(timezone)
92
- @standard_nv_pairs['tz'] = timezone
210
+ @details['tz'] = timezone
93
211
  self
94
212
  end
95
213
 
96
- # Set the language field
97
- #
98
214
  Contract String => Subject
215
+ # Set the language.
216
+ # @note Value is sent in the event as `lang` (raw event) or `br_lang` (processed event).
217
+ # @example Setting the language to Spanish
218
+ # subject.set_lang('es')
219
+ # @param [String] lang the language being used on the device
220
+ # @return self
221
+ # @api public
99
222
  def set_lang(lang)
100
- @standard_nv_pairs['lang'] = lang
223
+ @details['lang'] = lang
101
224
  self
102
225
  end
103
226
 
104
- # Set the domain user ID
105
- #
106
227
  Contract String => Subject
228
+ # Set the domain user ID.
229
+ # @note Value is sent in the event as `duid` (raw event) or `domain_userid` (processed event).
230
+ # @see Subject#set_network_user_id
231
+ # @see Subject#set_domain_session_id
232
+ # @see Subject#set_domain_session_idx
233
+ # @see https://github.com/simplybusiness/snowplow_ruby_duid/ snowplow_ruby_duid, a third party gem
234
+ # @see https://github.com/snowplow-incubator/snowplow-ruby-tracker-examples
235
+ # Ruby tracker example Rails app
236
+ # @example
237
+ # subject.set_domain_user_id('aeb1691c5a0ee5a6')
238
+ # @param [String] duid the unique domain user ID
239
+ # @return self
240
+ # @api public
241
+ #
242
+ # The `domain_userid` is a client-side unique user ID, which is set by the
243
+ # browser-based JavaScript tracker, and stored in a first party cookie
244
+ # (cookie name: `_sp_id`). For stitching together client-side and
245
+ # server-side events originating from the same user, the domain user ID can
246
+ # be extracted from the cookie and set using this method. A third party gem,
247
+ # [snowplow_ruby_duid](https://github.com/simplybusiness/snowplow_ruby_duid/),
248
+ # has been created to help with this.
249
+ #
250
+ # @example Ruby on Rails: getting the domain_user_id from the cookie
251
+ # # Assuming the Snowplow JavaScript has also been incorporated
252
+ # # cookies are accessible only within a Controller
253
+ # def snowplow_domain_userid
254
+ # sp_cookie = cookies.find { |key, _value| key =~ /^_sp_id/ }
255
+ # sp_cookie.last.split(".").first if sp_cookie.present?
256
+ # end
257
+ #
107
258
  def set_domain_user_id(duid)
108
- @standard_nv_pairs['duid'] = duid
259
+ @details['duid'] = duid
109
260
  self
110
261
  end
111
262
 
112
- # Set the IP address field
263
+ Contract String => Subject
264
+ # Set the domain session ID.
265
+ # @note Value is sent in the event as `sid` (raw event) or `domain_sessionid` (processed event).
266
+ # @see Subject#set_network_user_id
267
+ # @see Subject#set_domain_user_id
268
+ # @see Subject#set_domain_session_idx
269
+ # @example
270
+ # subject.set_domain_session_id('9c65e7f3-8e8e-470d-b243-910b5b300da0')
271
+ # @param [String] sid the unique domain session ID
272
+ # @return self
273
+ # @api public
113
274
  #
275
+ # The `domain_sessionid` is a client-side unique ID for a user's current
276
+ # session. It is set by the browser-based JavaScript trackers, and stored in
277
+ # a first party cookie (cookie name: `_sp_id`), along with other parameters
278
+ # such as `domain_userid`. For stitching together client-side and
279
+ # server-side events originating from the same user and session, the domain
280
+ # session ID can be extracted from the cookie and set using this method.
281
+ def set_domain_session_id(sid)
282
+ @details['sid'] = sid
283
+ self
284
+ end
285
+
286
+ Contract Num => Subject
287
+ # Set the domain session index.
288
+ # @note Value is sent in the event as `vid` (raw event) or `domain_sessionidx` (processed event).
289
+ # @see Subject#set_network_user_id
290
+ # @see Subject#set_domain_user_id
291
+ # @see Subject#set_domain_session_id
292
+ # @example
293
+ # subject.set_domain_session_idx(3)
294
+ # @param [Num] vid the number of sessions
295
+ # @return self
296
+ # @api public
297
+ #
298
+ # The `domain_sessionidx` is a client-side property that records how many
299
+ # visits (unique `domain_sessionid`s) a user (a unique `domain_userid`) has
300
+ # made to the site. It is stored in the first party cookie set by the
301
+ # JavaScript tracker, along with other parameters such as `domain_userid`.
302
+ # For stitching together client-side and server-side events originating from
303
+ # the same user and session, the domain session index can be extracted from
304
+ # the cookie and set using this method.
305
+ def set_domain_session_idx(vid)
306
+ @details['vid'] = vid
307
+ self
308
+ end
309
+
114
310
  Contract String => Subject
311
+ # Set the user's IP address.
312
+ # @note Value is sent in the event as `ip` (raw event) or `user_ipaddress` (processed event).
313
+ # @param [String] ip the IP address
314
+ # @return self
315
+ # @api public
115
316
  def set_ip_address(ip)
116
- @standard_nv_pairs['ip'] = ip
317
+ @details['ip'] = ip
117
318
  self
118
319
  end
119
320
 
120
- # Set the user agent
121
- #
122
321
  Contract String => Subject
123
- def set_useragent(ua)
124
- @standard_nv_pairs['ua'] = ua
322
+ # Set the browser user agent.
323
+ # @note Value is sent in the event as `ua` (raw event) or `useragent` (processed event).
324
+ # @example
325
+ # subject.set_useragent('Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:92.0) Gecko/20100101 Firefox/92.0')
326
+ # @param [String] useragent the user agent string
327
+ # @return self
328
+ # @api public
329
+ def set_useragent(useragent)
330
+ @details['ua'] = useragent
125
331
  self
126
332
  end
127
333
 
128
- # Set the network user ID field
129
- # This overwrites the nuid field set by the collector
130
- #
131
334
  Contract String => Subject
335
+ # Set the network user ID.
336
+ # @note Value is sent in the event as `tnuid` (raw event) and `network_userid` (processed event).
337
+ # @see Subject#set_domain_user_id
338
+ #
339
+ # The network user ID is, like the `domain_userid`, a cookie-based unique
340
+ # user ID. It is stored in a third party cookie set by the event collector,
341
+ # hence the name "network" as it is set at a network level. It is the
342
+ # server-side user identifier. The raw event does not contain a `nuid`
343
+ # value; the `network_userid` property is added when the event is processed.
344
+ #
345
+ # The default behaviour is for the collector to provide a new cookie/network
346
+ # user ID for each event it receives. This method provides the ability to
347
+ # override the collector cookie's value with your own generated ID.
348
+ #
349
+ # Domain user IDs set on the Subject in this way are sent as `tnuid` in the
350
+ # raw event.
351
+ #
352
+ # @example
353
+ # subject.set_network_user_id('ecdff4d0-9175-40ac-a8bb-325c49733607')
354
+ # @param [String] nuid the network user ID
355
+ # @return self
356
+ # @api public
132
357
  def set_network_user_id(nuid)
133
- @standard_nv_pairs['tnuid'] = nuid
358
+ @details['tnuid'] = nuid
134
359
  self
135
360
  end
136
-
137
361
  end
138
-
139
362
  end