snowplow-tracker 0.7.0.pre.alpha.0 → 0.8.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,54 @@
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
- require 'contracts'
20
20
 
21
21
  module SnowplowTracker
22
-
22
+ # @private
23
+ # Every`track_x_event` method creates a new Payload object. The Tracker then
24
+ # uses the Payload instance methods to add properties to the Payload `@data`
25
+ # hash. These properties form the raw event, after the completed hash is
26
+ # given to the Emitter.
23
27
  class Payload
28
+ attr_reader :data
24
29
 
25
- include Contracts
26
-
27
- attr_reader :context
28
-
29
- Contract nil => Payload
30
30
  def initialize
31
- @context = {}
32
- self
31
+ @data = {}
33
32
  end
34
33
 
35
- # Add a single name-value pair to @context
36
- #
37
- Contract String, Or[String, Bool, Num, nil] => Or[String, Bool, Num, nil]
34
+ # Add a single name-value pair to @data.
38
35
  def add(name, value)
39
- if value != "" and not value.nil?
40
- @context[name] = value
41
- end
36
+ @data[name] = value if (value != '') && !value.nil?
42
37
  end
43
-
44
- # Add each name-value pair in dict to @context
45
- #
46
- Contract Hash => Hash
47
- def add_dict(dict)
48
- for f in dict
49
- self.add(f[0], f[1])
50
- end
38
+
39
+ # Add each name-value pair in a hash to @data.
40
+ def add_hash(hash)
41
+ hash.each { |key, value| add(key, value) }
51
42
  end
52
43
 
53
- # Stringify a JSON and add it to @context
44
+ # Stringify a JSON and add it to @data.
54
45
  #
55
- 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)
46
+ # In practice, the JSON provided will be a SelfDescribingJson. This method
47
+ # is used to add context to events, or for `track_self_describing_event`.
48
+ # @see Tracker#track_unstruct_event
49
+ # @see Tracker#finalise_payload
50
+ def add_json(json, encode_base64, type_when_encoded, type_when_not_encoded)
51
+ return if json.nil?
52
+
53
+ stringified = JSON.generate(json)
63
54
 
64
55
  if encode_base64
65
- self.add(type_when_encoded, Base64.strict_encode64(dict_string))
56
+ add(type_when_encoded, Base64.strict_encode64(stringified))
66
57
  else
67
- self.add(type_when_not_encoded, dict_string)
58
+ add(type_when_not_encoded, stringified)
68
59
  end
69
-
70
60
  end
71
-
72
61
  end
73
62
  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
+ # SnowplowTracker::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,352 @@
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
- require 'contracts'
17
16
 
18
17
  module SnowplowTracker
19
-
18
+ # Subject objects store information about the user associated with the event,
19
+ # such as their `user_id`, what type of device they used, or what size screen
20
+ # that device had. Also, they store which platform the event occurred on -
21
+ # e.g. server-side app, mobile, games console, etc.
22
+ #
23
+ # Subject parameters are saved into the tracked event as part of the 'atomic'
24
+ # event properties, which have their own column in the eventual table of
25
+ # events. For example, a Subject's `user_id` parameter will be sent as `uid`
26
+ # in the raw event payload, ending up in the `user_id` column. These
27
+ # parameters represent part of the [Snowplow Tracker
28
+ # Protocol](https://docs.snowplowanalytics.com/docs/collecting-data/collecting-from-own-applications/snowplow-tracker-protocol),
29
+ # which defines a Snowplow event.
30
+ #
31
+ # Each {Tracker} is initialized with a Subject. This means that every event by
32
+ # default has the platform (`p` parameter in the raw event) `srv`: server-side
33
+ # app. Platform is the only preset Subject parameter, which can be overriden
34
+ # using the {#set_platform} method. All other parameters must be set manually.
35
+ # This can be done directly on the Subject, or, if it is associated with a
36
+ # Tracker, via the Tracker, which has access to all the methods of its
37
+ # Subject.
38
+ #
39
+ # Your server-side code may not have access to all these parameters, or they
40
+ # might not be useful to you. All the Subject parameters are optional, except
41
+ # `platform`.
42
+ #
43
+ # @example Subject methods can be called from their associated Tracker
44
+ # # Creating the components explicitly
45
+ # emitter = SnowplowTracker::Emitter.new(endpoint: 'localhost')
46
+ # subject = SnowplowTracker::Subject.new
47
+ # tracker = SnowplowTracker::Tracker.new(emitters: emitter, subject: subject)
48
+ #
49
+ # # These lines are equivalent
50
+ # subject.set_user_id('12345')
51
+ # tracker.set_user_id('12345')
52
+ #
53
+ # # This would also be equivalent
54
+ # emitter = SnowplowTracker::Emitter.new(endpoint: 'localhost')
55
+ # subject = SnowplowTracker::Subject.new
56
+ # subject.set_user_id('12345')
57
+ # tracker = SnowplowTracker::Tracker.new(emitters: emitter, subject: subject)
58
+ #
59
+ # @example Adding properties to the auto-generated Tracker-associated Subject
60
+ # # Creating the components
61
+ # emitter = SnowplowTracker::Emitter.new(endpoint: 'localhost')
62
+ # tracker = SnowplowTracker::Tracker.new(emitters: emitter)
63
+ #
64
+ # # Set Subject parameters via the Tracker
65
+ # tracker.set_user_id('12345')
66
+ #
67
+ # Since many of the Subject parameters describe the user, different Subject
68
+ # properties may often be desired for each event, if there are multiple users.
69
+ # This can be achieved in one of three ways:
70
+ #
71
+ # 1. the properties of the Tracker-associated Subject can be overriden by the
72
+ # properties of an event-specific Subject. A Subject can be added to any
73
+ # Tracker `#track_x_event` method call, as one of the arguments. Remember to
74
+ # set the platform for the event Subject if you're not using `srv`.
75
+ # 2. the Tracker-associated Subject can be swapped for another Subject, using
76
+ # the Tracker method {Tracker#set_subject}.
77
+ # 3. the properties of the Tracker-associated Subject can be changed before
78
+ # every `#track_x_event`, by calling the Subject methods via the Tracker.
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
+ # @see
85
+ # https://docs.snowplowanalytics.com/docs/collecting-data/collecting-from-own-applications/ruby-tracker/enriching-your-events/
86
+ # the Snowplow docs page about adding context and other extra data to events
87
+ # @api public
88
+ #
89
+ # @note All the Subject instance methods return the Subject object, allowing
90
+ # method chaining, e.g.
91
+ # `SnowplowTracker::Subject.new.set_timezone('Europe/London').set_user_id('12345')`
20
92
  class Subject
93
+ # @private
94
+ DEFAULT_PLATFORM = 'srv'
21
95
 
22
- include Contracts
23
-
24
- @@default_platform = 'srv'
25
- @@supported_platforms = ['pc', 'tv', 'mob', 'cnsl', 'iot']
96
+ # @api public
97
+ #
98
+ # | `p` value | Platform |
99
+ # | ---- | ---- |
100
+ # | app | General App |
101
+ # | cnsl | Games Console |
102
+ # | iot | Internet of Things |
103
+ # | mob | Mobile/Tablet |
104
+ # | pc | Desktop/Laptop/Netbook |
105
+ # | srv [DEFAULT] | Server-side App |
106
+ # | tv | Connected TV |
107
+ # | web | Web (including Mobile Web) |
108
+ SUPPORTED_PLATFORMS = %w[app cnsl iot mob pc srv tv web]
26
109
 
27
- attr_reader :standard_nv_pairs
110
+ # Access the Subject parameters
111
+ # @example
112
+ # SnowplowTracker::Subject.new.set_user_id('12345').details
113
+ # => {"p"=>"srv", "uid"=>"12345"}
114
+ # @api public
115
+ attr_reader :details
28
116
 
29
- Contract None => Subject
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
- 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
122
+ # Set the platform to one of the supported platform values.
123
+ # @note Value is sent in the event as `p` (raw event) or `platform` (processed event).
124
+ # @see Subject::SUPPORTED_PLATFORMS
125
+ # @param [String] platform a valid platform choice
126
+ # @example
127
+ # subject.set_platform('app')
128
+ # @return self
129
+ # @api public
130
+ def set_platform(platform)
131
+ raise "#{platform} is not a supported platform" unless SUPPORTED_PLATFORMS.include?(platform)
44
132
 
133
+ @details['p'] = platform
45
134
  self
46
135
  end
47
136
 
48
- # Set the business-defined user ID for a user
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
49
146
  #
50
- Contract String => Subject
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
- Contract Num => Subject
155
+ # Set a business-defined fingerprint for a user.
156
+ # @note Value is sent in the event as `fp` (raw event) or `user_fingerprint` (processed event).
157
+ # @param [Num] fingerprint a user fingerprint
158
+ # @return self
159
+ # @example
160
+ # subject.set_fingerprint(4048966212)
161
+ # @api public
59
162
  def set_fingerprint(fingerprint)
60
- @standard_nv_pairs['fp'] = fingerprint
163
+ @details['fp'] = fingerprint
61
164
  self
62
165
  end
63
166
 
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}"
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 [Integer] width the screen width, in pixels (must be a positive integer)
170
+ # @param [Integer] height the screen height, in pixels (must be a positive integer)
171
+ # @return self
172
+ # @example
173
+ # subject.set_screen_resolution(width: 2880, height: 1800)
174
+ # @api public
175
+ def set_screen_resolution(width:, height:)
176
+ @details['res'] = "#{width}x#{height}"
69
177
  self
70
178
  end
71
179
 
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}"
180
+ # Set the dimensions of the current viewport.
181
+ # @note Value is sent in the event as `vp` (raw event) or `br_viewwidth` and `br_viewheight` (processed event).
182
+ # @param [Integer] width the viewport width, in pixels (must be a positive integer)
183
+ # @param [Integer] height the viewport height, in pixels (must be a positive integer)
184
+ # @return self
185
+ # @example
186
+ # subject.set_viewport(width: 1440, height: 762)
187
+ # @api public
188
+ def set_viewport(width:, height:)
189
+ @details['vp'] = "#{width}x#{height}"
77
190
  self
78
191
  end
79
192
 
80
- # Set the color depth of the device in bits per pixel
81
- #
82
- Contract Num => Subject
193
+ # Set the color depth of the browser, in bits per pixel.
194
+ # @note Value is sent in the event as `cd` (raw event) or `br_colordepth` (processed event).
195
+ # @param [Num] depth the colour depth
196
+ # @example
197
+ # subject.set_color_depth(24)
198
+ # @return self
199
+ # @api public
83
200
  def set_color_depth(depth)
84
- @standard_nv_pairs['cd'] = depth
201
+ @details['cd'] = depth
85
202
  self
86
203
  end
87
204
 
88
- # Set the timezone field
89
- #
90
- Contract String => Subject
205
+ # Set the timezone to that of the user's OS.
206
+ # @note Value is sent in the event as `tz` (raw event) or `os_timezone` (processed event).
207
+ # @example
208
+ # subject.set_timezone('Africa/Lagos')
209
+ # @param [String] timezone the timezone
210
+ # @return self
211
+ # @api public
91
212
  def set_timezone(timezone)
92
- @standard_nv_pairs['tz'] = timezone
213
+ @details['tz'] = timezone
93
214
  self
94
215
  end
95
216
 
96
- # Set the language field
97
- #
98
- Contract String => Subject
217
+ # Set the language.
218
+ # @note Value is sent in the event as `lang` (raw event) or `br_lang` (processed event).
219
+ # @example Setting the language to Spanish
220
+ # subject.set_lang('es')
221
+ # @param [String] lang the language being used on the device
222
+ # @return self
223
+ # @api public
99
224
  def set_lang(lang)
100
- @standard_nv_pairs['lang'] = lang
225
+ @details['lang'] = lang
101
226
  self
102
227
  end
103
228
 
104
- # Set the domain user ID
229
+ # Set the domain user ID.
230
+ # @note Value is sent in the event as `duid` (raw event) or `domain_userid` (processed event).
231
+ # @see Subject#set_network_user_id
232
+ # @see Subject#set_domain_session_id
233
+ # @see Subject#set_domain_session_idx
234
+ # @see https://github.com/simplybusiness/snowplow_ruby_duid/ snowplow_ruby_duid, a third party gem
235
+ # @see https://github.com/snowplow-incubator/snowplow-ruby-tracker-examples
236
+ # Ruby tracker example Rails app
237
+ # @example
238
+ # subject.set_domain_user_id('aeb1691c5a0ee5a6')
239
+ # @param [String] duid the unique domain user ID
240
+ # @return self
241
+ # @api public
242
+ #
243
+ # The `domain_userid` is a client-side unique user ID, which is set by the
244
+ # browser-based JavaScript tracker, and stored in a first party cookie
245
+ # (cookie name: `_sp_id`). For stitching together client-side and
246
+ # server-side events originating from the same user, the domain user ID can
247
+ # be extracted from the cookie and set using this method. A third party gem,
248
+ # [snowplow_ruby_duid](https://github.com/simplybusiness/snowplow_ruby_duid/),
249
+ # has been created to help with this.
250
+ #
251
+ # @example Ruby on Rails: getting the domain_user_id from the cookie
252
+ # # Assuming the Snowplow JavaScript has also been incorporated
253
+ # # cookies are accessible only within a Controller
254
+ # def snowplow_domain_userid
255
+ # sp_cookie = cookies.find { |key, _value| key =~ /^_sp_id/ }
256
+ # sp_cookie.last.split(".").first if sp_cookie.present?
257
+ # end
105
258
  #
106
- Contract String => Subject
107
259
  def set_domain_user_id(duid)
108
- @standard_nv_pairs['duid'] = duid
260
+ @details['duid'] = duid
109
261
  self
110
262
  end
111
263
 
112
- # Set the IP address field
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
  #
114
- Contract String => Subject
115
- def set_ip_address(ip)
116
- @standard_nv_pairs['ip'] = ip
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
117
283
  self
118
284
  end
119
285
 
120
- # Set the user agent
286
+ # Set the domain session index.
287
+ # @note Value is sent in the event as `vid` (raw event) or `domain_sessionidx` (processed event).
288
+ # @see Subject#set_network_user_id
289
+ # @see Subject#set_domain_user_id
290
+ # @see Subject#set_domain_session_id
291
+ # @example
292
+ # subject.set_domain_session_idx(3)
293
+ # @param [Num] vid the number of sessions
294
+ # @return self
295
+ # @api public
121
296
  #
122
- Contract String => Subject
123
- def set_useragent(ua)
124
- @standard_nv_pairs['ua'] = ua
297
+ # The `domain_sessionidx` is a client-side property that records how many
298
+ # visits (unique `domain_sessionid`s) a user (a unique `domain_userid`) has
299
+ # made to the site. It is stored in the first party cookie set by the
300
+ # JavaScript tracker, along with other parameters such as `domain_userid`.
301
+ # For stitching together client-side and server-side events originating from
302
+ # the same user and session, the domain session index can be extracted from
303
+ # the cookie and set using this method.
304
+ def set_domain_session_idx(vid)
305
+ @details['vid'] = vid
125
306
  self
126
307
  end
127
308
 
128
- # Set the network user ID field
129
- # This overwrites the nuid field set by the collector
309
+ # Set the user's IP address.
310
+ # @note Value is sent in the event as `ip` (raw event) or `user_ipaddress` (processed event).
311
+ # @param [String] ip the IP address
312
+ # @return self
313
+ # @example
314
+ # subject.set_ip_address('37.157.33.178')
315
+ # @api public
316
+ def set_ip_address(ip)
317
+ @details['ip'] = ip
318
+ self
319
+ end
320
+
321
+ # Set the browser user agent.
322
+ # @note Value is sent in the event as `ua` (raw event) or `useragent` (processed event).
323
+ # @example
324
+ # subject.set_useragent('Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:92.0) Gecko/20100101 Firefox/92.0')
325
+ # @param [String] useragent the user agent string
326
+ # @return self
327
+ # @api public
328
+ def set_useragent(useragent)
329
+ @details['ua'] = useragent
330
+ self
331
+ end
332
+
333
+ # Set the network user ID.
334
+ # @note Value is sent in the event as `tnuid` (raw event) and `network_userid` (processed event).
335
+ # @see Subject#set_domain_user_id
336
+ #
337
+ # The network user ID is, like the `domain_userid`, a cookie-based unique
338
+ # user ID. It is stored in a third party cookie set by the event collector,
339
+ # hence the name "network" as it is set at a network level. It is the
340
+ # server-side user identifier. The raw event does not contain a `nuid`
341
+ # value; the `network_userid` property is added when the event is processed.
342
+ #
343
+ # The default behaviour is for the collector to provide a new cookie/network
344
+ # user ID for each event it receives. This method provides the ability to
345
+ # override the collector cookie's value with your own generated ID.
130
346
  #
131
- Contract String => Subject
347
+ # Domain user IDs set on the Subject in this way are sent as `tnuid` in the
348
+ # raw event.
349
+ #
350
+ # @example
351
+ # subject.set_network_user_id('ecdff4d0-9175-40ac-a8bb-325c49733607')
352
+ # @param [String] nuid the network user ID
353
+ # @return self
354
+ # @api public
132
355
  def set_network_user_id(nuid)
133
- @standard_nv_pairs['tnuid'] = nuid
356
+ @details['tnuid'] = nuid
134
357
  self
135
358
  end
136
-
137
359
  end
138
-
139
360
  end