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.
- checksums.yaml +5 -5
- data/README.md +56 -37
- data/lib/snowplow-tracker/emitters.rb +355 -147
- data/lib/snowplow-tracker/page.rb +60 -0
- data/lib/snowplow-tracker/payload.rb +30 -34
- data/lib/snowplow-tracker/self_describing_json.rb +92 -9
- data/lib/snowplow-tracker/subject.rb +282 -59
- data/lib/snowplow-tracker/timestamp.rb +95 -23
- data/lib/snowplow-tracker/tracker.rb +547 -242
- data/lib/snowplow-tracker/version.rb +33 -4
- data/lib/snowplow-tracker.rb +5 -5
- metadata +15 -17
- data/lib/snowplow-tracker/contracts.rb +0 -29
@@ -1,4 +1,4 @@
|
|
1
|
-
# Copyright (c) 2013-
|
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::
|
13
|
-
# Copyright:: Copyright (c) 2013-
|
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 :
|
31
|
+
attr_reader :data
|
28
32
|
|
29
|
-
Contract nil =>
|
33
|
+
Contract nil => Any
|
30
34
|
def initialize
|
31
|
-
@
|
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 !=
|
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
|
-
|
48
|
-
|
49
|
-
|
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
|
-
|
57
|
-
|
58
|
-
|
59
|
-
|
60
|
-
|
61
|
-
|
62
|
-
|
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
|
-
|
63
|
+
add(type_when_encoded, Base64.strict_encode64(stringified))
|
66
64
|
else
|
67
|
-
|
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-
|
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::
|
13
|
-
# Copyright:: Copyright (c) 2013-
|
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
|
-
:
|
28
|
-
:
|
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-
|
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::
|
13
|
-
# Copyright:: Copyright (c) 2013-
|
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
|
-
|
25
|
-
|
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
|
-
|
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 =>
|
116
|
+
Contract None => Any
|
117
|
+
# @api public
|
30
118
|
def initialize
|
31
|
-
@
|
32
|
-
self
|
119
|
+
@details = { 'p' => DEFAULT_PLATFORM }
|
33
120
|
end
|
34
121
|
|
35
|
-
# Specify the platform
|
36
|
-
#
|
37
122
|
Contract String => Subject
|
38
|
-
|
39
|
-
|
40
|
-
|
41
|
-
|
42
|
-
|
43
|
-
|
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
|
-
@
|
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
|
-
@
|
162
|
+
@details['fp'] = fingerprint
|
61
163
|
self
|
62
164
|
end
|
63
165
|
|
64
|
-
|
65
|
-
#
|
66
|
-
|
67
|
-
|
68
|
-
|
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
|
-
|
73
|
-
#
|
74
|
-
|
75
|
-
|
76
|
-
|
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
|
-
@
|
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
|
-
@
|
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
|
-
@
|
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
|
-
@
|
259
|
+
@details['duid'] = duid
|
109
260
|
self
|
110
261
|
end
|
111
262
|
|
112
|
-
|
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
|
-
@
|
317
|
+
@details['ip'] = ip
|
117
318
|
self
|
118
319
|
end
|
119
320
|
|
120
|
-
# Set the user agent
|
121
|
-
#
|
122
321
|
Contract String => Subject
|
123
|
-
|
124
|
-
|
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
|
-
@
|
358
|
+
@details['tnuid'] = nuid
|
134
359
|
self
|
135
360
|
end
|
136
|
-
|
137
361
|
end
|
138
|
-
|
139
362
|
end
|