Class: Segment::Analytics::Client

Inherits:
Object
  • Object
show all
Includes:
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 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(attrs = {}) ⇒ Client

public: Creates a new client

attrs - Hash

:write_key         - String of your project's write_key
:max_queue_size - Fixnum of the max calls to remain queued (optional)
:on_error       - Proc which handles error calls from the API



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

def initialize attrs = {}
  symbolize_keys! attrs

  @queue = Queue.new
  @write_key = attrs[:write_key]
  @max_queue_size = attrs[:max_queue_size] || Defaults::Queue::MAX_SIZE
  @options = attrs
  @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

public: Aliases a user from one id to another

attrs - Hash

:context     - Hash of context (optional)
:integrations - Hash specifying what integrations this event goes to. (optional)
:options      - Hash specifying options such as user traits. (optional)
:previous_id - String of the id to alias from
:timestamp   - Time of when the alias occured (optional)
:user_id     - String of the id to alias to
:message_id   - String of the message id that uniquely identified a message across the API. (optional)



141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
 
# File 'lib/segment/analytics/client.rb', line 141

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

public: Synchronously waits until the worker has flushed the queue.

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



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

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

#group(attrs) ⇒ Object

public: Associates a user identity with a group.

attrs - Hash

:context      - Hash of context (optional)
:integrations - Hash specifying what integrations this event goes to. (optional)
:options      - Hash specifying options such as user traits. (optional)
:previous_id  - String of the id to alias from
:timestamp    - Time of when the alias occured (optional)
:user_id      - String of the id to alias to
:message_id   - String of the message id that uniquely identified a message across the API. (optional)



177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
 
# File 'lib/segment/analytics/client.rb', line 177

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]

  fail 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

public: Identifies a user

attrs - Hash

:anonymous_id - String of the user's id when you don't know who they are yet. (optional but you must provide either an anonymous_id or user_id. See: https://segment.io/docs/tracking - api/track/#user - id)
:context      - Hash of context. (optional)
:integrations - Hash specifying what integrations this event goes to. (optional)
:options      - Hash specifying options such as user traits. (optional)
:timestamp    - Time of when the event occurred. (optional)
:traits       - Hash of user traits. (optional)
:user_id      - String of the user id
:message_id   - String of the message id that uniquely identified a message across the API. (optional)



102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
 
# File 'lib/segment/analytics/client.rb', line 102

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

  fail 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

public: Records a page view

attrs - Hash

:anonymous_id - String of the user's id when you don't know who they are yet. (optional but you must provide either an anonymous_id or user_id. See: https://segment.io/docs/tracking - api/track/#user - id)
:category     - String of the page category (optional)
:context      - Hash of context (optional)
:integrations - Hash specifying what integrations this event goes to. (optional)
:name         - String name of the page
:options      - Hash specifying options such as user traits. (optional)
:properties   - Hash of page properties (optional)
:timestamp    - Time of when the pageview occured (optional)
:user_id      - String of the id to alias from
:message_id   - String of the message id that uniquely identified a message across the API. (optional)



221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
 
# File 'lib/segment/analytics/client.rb', line 221

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]

  fail 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 ⇒ Object

public: Returns the number of queued messages

returns Fixnum of messages in the queue



297
298
299
 
# File 'lib/segment/analytics/client.rb', line 297

def queued_messages
  @queue.length
end

#screen(attrs) ⇒ Object

public: Records a screen view (for a mobile app)

attrs - Hash

:anonymous_id - String of the user's id when you don't know who they are yet. (optional but you must provide either an anonymous_id or user_id. See: https://segment.io/docs/tracking - api/track/#user - id)
:category     - String screen category (optional)
:context      - Hash of context (optional)
:integrations - Hash specifying what integrations this event goes to. (optional)
:name         - String name of the screen
:options      - Hash specifying options such as user traits. (optional)
:properties   - Hash of screen properties (optional)
:timestamp    - Time of when the screen occured (optional)
:user_id      - String of the id to alias from



263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
 
# File 'lib/segment/analytics/client.rb', line 263

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]

  fail 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

public: Tracks an event

attrs - Hash

:anonymous_id - String of the user's id when you don't know who they are yet. (optional but you must provide either an anonymous_id or user_id. See: https://segment.io/docs/tracking - api/track/#user - id)
:context      - Hash of context. (optional)
:event        - String of event name.
:integrations - Hash specifying what integrations this event goes to. (optional)
:options      - Hash specifying options such as user traits. (optional)
:properties   - Hash of event properties. (optional)
:timestamp    - Time of when the event occurred. (optional)
:user_id      - String of the user id.
:message_id   - String of the message id that uniquely identified a message across the API. (optional)



56
57
58
59
60
61
62
63
64
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
 
# File 'lib/segment/analytics/client.rb', line 56

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?
    fail ArgumentError, 'Must supply event as a non-empty string'
  end

  fail 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