Class: Segment::Analytics::Client

Inherits:
Object
  • Object
show all
Includes:
Logging, Utils
Defined in:
lib/segment/analytics/client.rb

Constant Summary

Constants included from Utils

Utils::UTC_OFFSET_WITHOUT_COLON, Utils::UTC_OFFSET_WITH_COLON

Instance Method Summary collapse

Methods included from Logging

included, #logger

Methods included from Utils

#date_in_iso8601, #datetime_in_iso8601, #formatted_offset, #isoify_dates, #isoify_dates!, #seconds_to_utc_offset, #stringify_keys, #symbolize_keys, #symbolize_keys!, #time_in_iso8601, #uid

Constructor Details

#initialize(opts = {}) ⇒ Client

Returns a new instance of Client.

Parameters:

  • opts (Hash) (defaults to: {})

Options Hash (opts):

  • :write_key (String) —

    Your project’s write_key

  • :max_queue_size (FixNum) —

    Maximum number of calls to be remain queued.

  • :on_error (Proc) —

    Handles error calls from the API.



20
21
22
23
24
25
26
27
28
29
30
31
32
33
 
# File 'lib/segment/analytics/client.rb', line 20

def initialize(opts = {})
  symbolize_keys!(opts)

  @queue = Queue.new
  @write_key = opts[:write_key]
  @max_queue_size = opts[:max_queue_size] || Defaults::Queue::MAX_SIZE
  @options = opts
  @worker_mutex = Mutex.new
  @worker = Worker.new(@queue, @write_key, @options)

  check_write_key!

  at_exit { @worker_thread && @worker_thread[:should_exit] = true }
end

Instance Method Details

#alias(attrs) ⇒ Object

Aliases a user from one id to another

Parameters:

  • attrs (Hash)

Options Hash (attrs):

  • :context (Hash) — default: {}
  • :integrations (Hash) —

    What integrations this must be sent to (optional)

  • :options (Hash) —

    Options such as user traits (optional)

  • :previous_id (String) —

    The ID to alias from

  • :timestamp (Time) —

    When the alias occurred (optional)

  • :user_id (String) —

    The ID to alias to

  • :message_id (String) —

    ID that uniquely identifies a message across the API. (optional)

See Also:



161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
 
# File 'lib/segment/analytics/client.rb', line 161

def alias(attrs)
  symbolize_keys! attrs

  from = attrs[:previous_id]
  to = attrs[:user_id]
  timestamp = attrs[:timestamp] || Time.new
  context = attrs[:context] || {}
  message_id = attrs[:message_id].to_s if attrs[:message_id]

  check_presence! from, 'previous_id'
  check_presence! to, 'user_id'
  check_timestamp! timestamp
  add_context context

  enqueue({
    :previousId => from,
    :userId => to,
    :integrations => attrs[:integrations],
    :context => context,
    :options => attrs[:options],
    :messageId => message_id,
    :timestamp => datetime_in_iso8601(timestamp),
    :type => 'alias'
  })
end

#flush ⇒ Object

Synchronously waits until the worker has flushed the queue.

Use only for scripts which are not long-running, and will specifically exit



39
40
41
42
43
44
 
# File 'lib/segment/analytics/client.rb', line 39

def flush
  while !@queue.empty? || @worker.is_requesting?
    ensure_worker_running
    sleep(0.1)
  end
end

#group(attrs) ⇒ Object

Associates a user identity with a group.

Parameters:

  • attrs (Hash)

Options Hash (attrs):

  • :anonymous_id (String) —

    ID for a user when you don’t know who they are yet. (optional but you must provide either an ‘anonymous_id` or `user_id`)

  • :context (Hash) — default: {}
  • :group_id (String) —

    The ID of the group

  • :integrations (Hash) —

    What integrations this event goes to (optional)

  • :options (Hash) —

    Options such as user traits (optional)

  • :timestamp (Time) —

    When the event occurred (optional)

  • :user_id (String) —

    The ID for the user that is part of the group

  • :message_id (String) —

    ID that uniquely identifies a message across the API. (optional)

Raises:

  • (ArgumentError)

See Also:



205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
 
# File 'lib/segment/analytics/client.rb', line 205

def group(attrs)
  symbolize_keys! attrs
  check_user_id! attrs

  group_id = attrs[:group_id]
  user_id = attrs[:user_id]
  traits = attrs[:traits] || {}
  timestamp = attrs[:timestamp] || Time.new
  context = attrs[:context] || {}
  message_id = attrs[:message_id].to_s if attrs[:message_id]

  raise ArgumentError, '.traits must be a hash' unless traits.is_a? Hash
  isoify_dates! traits

  check_presence! group_id, 'group_id'
  check_timestamp! timestamp
  add_context context

  enqueue({
    :groupId => group_id,
    :userId => user_id,
    :traits => traits,
    :integrations => attrs[:integrations],
    :options => attrs[:options],
    :context => context,
    :messageId => message_id,
    :timestamp => datetime_in_iso8601(timestamp),
    :type => 'group'
  })
end

#identify(attrs) ⇒ Object

Identifies a user

Parameters:

  • attrs (Hash)

Options Hash (attrs):

  • :anonymous_id (String) —

    ID for a user when you don’t know who they are yet. (optional but you must provide either an ‘anonymous_id` or `user_id`)

  • :context (Hash) — default: {}
  • :integrations (Hash) —

    What integrations this event goes to (optional)

  • :options (Hash) —

    Options such as user traits (optional)

  • :timestamp (Time) —

    When the event occurred (optional)

  • :traits (Hash) —

    User traits (optional)

  • :user_id (String) —

    The ID for this user in your database (optional but you must provide either an ‘anonymous_id` or `user_id`)

  • :message_id (String) —

    ID that uniquely identifies a message across the API. (optional)

Raises:

  • (ArgumentError)

See Also:



118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
 
# File 'lib/segment/analytics/client.rb', line 118

def identify(attrs)
  symbolize_keys! attrs
  check_user_id! attrs

  traits = attrs[:traits] || {}
  timestamp = attrs[:timestamp] || Time.new
  context = attrs[:context] || {}
  message_id = attrs[:message_id].to_s if attrs[:message_id]

  check_timestamp! timestamp

  raise ArgumentError, 'Must supply traits as a hash' unless traits.is_a? Hash
  isoify_dates! traits

  add_context context

  enqueue({
    :userId => attrs[:user_id],
    :anonymousId => attrs[:anonymous_id],
    :integrations => attrs[:integrations],
    :context => context,
    :traits => traits,
    :options => attrs[:options],
    :messageId => message_id,
    :timestamp => datetime_in_iso8601(timestamp),
    :type => 'identify'
  })
end

#page(attrs) ⇒ Object

Records a page view

Parameters:

  • attrs (Hash)

Options Hash (attrs):

  • :anonymous_id (String) —

    ID for a user when you don’t know who they are yet. (optional but you must provide either an ‘anonymous_id` or `user_id`)

  • :category (String) —

    The page category (optional)

  • :context (Hash) — default: {}
  • :integrations (Hash) —

    What integrations this event goes to (optional)

  • :name (String) —

    Name of the page

  • :options (Hash) —

    Options such as user traits (optional)

  • :properties (Hash) —

    Page properties (optional)

  • :timestamp (Time) —

    When the pageview occurred (optional)

  • :user_id (String) —

    The ID of the user viewing the page

  • :message_id (String) —

    ID that uniquely identifies a message across the API. (optional)

Raises:

  • (ArgumentError)

See Also:



255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
 
# File 'lib/segment/analytics/client.rb', line 255

def page(attrs)
  symbolize_keys! attrs
  check_user_id! attrs

  name = attrs[:name].to_s
  properties = attrs[:properties] || {}
  timestamp = attrs[:timestamp] || Time.new
  context = attrs[:context] || {}
  message_id = attrs[:message_id].to_s if attrs[:message_id]

  raise ArgumentError, '.properties must be a hash' unless properties.is_a? Hash
  isoify_dates! properties

  check_timestamp! timestamp
  add_context context

  enqueue({
    :userId => attrs[:user_id],
    :anonymousId => attrs[:anonymous_id],
    :name => name,
    :category => attrs[:category],
    :properties => properties,
    :integrations => attrs[:integrations],
    :options => attrs[:options],
    :context => context,
    :messageId => message_id,
    :timestamp => datetime_in_iso8601(timestamp),
    :type => 'page'
  })
end

#queued_messages ⇒ Fixnum

Returns number of messages in the queue.

Returns:

  • (Fixnum) —

    number of messages in the queue



335
336
337
 
# File 'lib/segment/analytics/client.rb', line 335

def queued_messages
  @queue.length
end

#screen(attrs) ⇒ Object

Records a screen view (for a mobile app)

Parameters:

  • attrs (Hash)

Options Hash (attrs):

  • :anonymous_id (String) —

    ID for a user when you don’t know who they are yet. (optional but you must provide either an ‘anonymous_id` or `user_id`)

  • :category (String) —

    The screen category (optional)

  • :context (Hash) — default: {}
  • :integrations (Hash) —

    What integrations this event goes to (optional)

  • :name (String) —

    Name of the screen

  • :options (Hash) —

    Options such as user traits (optional)

  • :properties (Hash) —

    Page properties (optional)

  • :timestamp (Time) —

    When the pageview occurred (optional)

  • :user_id (String) —

    The ID of the user viewing the screen

  • :message_id (String) —

    ID that uniquely identifies a message across the API. (optional)

Raises:

  • (ArgumentError) 


303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
 
# File 'lib/segment/analytics/client.rb', line 303

def screen(attrs)
  symbolize_keys! attrs
  check_user_id! attrs

  name = attrs[:name].to_s
  properties = attrs[:properties] || {}
  timestamp = attrs[:timestamp] || Time.new
  context = attrs[:context] || {}
  message_id = attrs[:message_id].to_s if attrs[:message_id]

  raise ArgumentError, '.properties must be a hash' unless properties.is_a? Hash
  isoify_dates! properties

  check_timestamp! timestamp
  add_context context

  enqueue({
    :userId => attrs[:user_id],
    :anonymousId => attrs[:anonymous_id],
    :name => name,
    :properties => properties,
    :category => attrs[:category],
    :options => attrs[:options],
    :integrations => attrs[:integrations],
    :context => context,
    :messageId => message_id,
    :timestamp => timestamp.iso8601,
    :type => 'screen'
  })
end

#track(attrs) ⇒ Object

Tracks an event

Parameters:

  • attrs (Hash)

Options Hash (attrs):

  • :anonymous_id (String) —

    ID for a user when you don’t know who they are yet. (optional but you must provide either an ‘anonymous_id` or `user_id`)

  • :context (Hash) — default: {}
  • :event (String) —

    Event name

  • :integrations (Hash) —

    What integrations this event goes to (optional)

  • :options (Hash) —

    Options such as user traits (optional)

  • :properties (Hash) —

    Event properties (optional)

  • :timestamp (Time) —

    When the event occurred (optional)

  • :user_id (String) —

    The ID for this user in your database (optional but you must provide either an ‘anonymous_id` or `user_id`)

  • :message_id (String) —

    ID that uniquely identifies a message across the API. (optional)

Raises:

  • (ArgumentError)

See Also:



65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
 
# File 'lib/segment/analytics/client.rb', line 65

def track(attrs)
  symbolize_keys! attrs
  check_user_id! attrs

  event = attrs[:event]
  properties = attrs[:properties] || {}
  timestamp = attrs[:timestamp] || Time.new
  context = attrs[:context] || {}
  message_id = attrs[:message_id].to_s if attrs[:message_id]

  check_timestamp! timestamp

  if event.nil? || event.empty?
    raise ArgumentError, 'Must supply event as a non-empty string'
  end

  raise ArgumentError, 'Properties must be a Hash' unless properties.is_a? Hash
  isoify_dates! properties

  add_context context

  enqueue({
    :event => event,
    :userId => attrs[:user_id],
    :anonymousId => attrs[:anonymous_id],
    :context => context,
    :options => attrs[:options],
    :integrations => attrs[:integrations],
    :properties => properties,
    :messageId => message_id,
    :timestamp => datetime_in_iso8601(timestamp),
    :type => 'track'
  })
end