Class: Itly

Inherits:
Object
  • Object
show all
Includes:
Plugins
Defined in:
lib/itly/itly.rb,
lib/itly/event.rb,
lib/itly/plugin.rb,
lib/itly/loggers.rb,
lib/itly/options.rb,
lib/itly/plugins.rb,
lib/itly/version.rb,
lib/itly/exceptions.rb,
lib/itly/plugin_options.rb,
lib/itly/options/validation.rb,
lib/itly/options/environment.rb,
lib/itly/plugin_call_options.rb,
lib/itly/validation_response.rb

Overview

Itly main class

Defined Under Namespace

Modules: Plugins Classes: Event, InitializationError, Loggers, Options, Plugin, PluginCallOptions, PluginOptions, RemoteError, ValidationError, ValidationResponse

Constant Summary collapse

VERSION = 
'0.1.1'

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Itly

Create a new Itly object.

The is_initialized instance variable is a True/False flag indicating if the load method was called on the object.



15
16
17
 
# File 'lib/itly/itly.rb', line 15

def initialize
  @is_initialized = false
end

Instance Attribute Details

#options ⇒ Object (readonly)

Returns the value of attribute options.



7
8
9
 
# File 'lib/itly/options.rb', line 7

def options
  @options
end

Instance Method Details

#alias(user_id:, previous_id:, options: {}) ⇒ Object

Associate one user ID with another (typically a known user ID with an anonymous one).

Call alias on all plugins and call post_alias on all plugins.

Parameters:

  • user_id: (String) —

    The ID that the user will be identified by going forward. This is typically the user’s database ID (as opposed to an anonymous ID), or their updated ID (for example, if the ID is an email address which the user just updated).

  • previous_id: (String) —

    The ID the user has been identified by so far.

  • options: (Hash) (defaults to: {}) —

    plugin specific option. The keys must correspond to a plugin id, and the values will be passed only to the plugin identified by the key.



254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
 
# File 'lib/itly/itly.rb', line 254

def alias(user_id:, previous_id:, options: {})
  # Run only if the object is enabled and was initialized
  return unless was_initialized? && enabled?

  # Log
  log = Itly::Loggers.vars_to_log user_id: user_id, previous_id: previous_id, options: options
  logger&.info "alias(#{log})"

  # Run on all plugins
  run_on_plugins do |plugin|
    plugin.alias user_id: user_id, previous_id: previous_id, options: options[plugin.id]
  end
  run_on_plugins do |plugin|
    plugin.post_alias user_id: user_id, previous_id: previous_id
  end
end

#flush ⇒ Object

Send flush to your plugins.

Call flush on all plugins.



276
277
278
279
280
281
282
283
284
285
 
# File 'lib/itly/itly.rb', line 276

def flush
  # Run only if the object is enabled and was initialized
  return unless was_initialized? && enabled?

  # Log
  logger&.info 'flush()'

  # Run on all plugins
  run_on_plugins(&:flush)
end

#group(user_id:, group_id:, properties: {}, options: {}) ⇒ Object

Associate a user with their group (for example, their department or company), or to set the group’s traits.

Validates the properties with all registered plugins first. Raises a Itly::ValidationError if one of the validations failed and if your set the options.validation value to ERROR_ON_INVALID.

Call group on all plugins and call post_group on all plugins.

Example:

itly.group user_id: 'MyUser123', group_id: 'MyGroup456', name: 'Iteratively, Inc.'

Parameters:

  • user_id: (String) —

    the id of the user in your application

  • group_id: (String) —

    the id of the group in your application

  • properties: (Hash) (defaults to: {}) —

    The list of properties to pass to your application

  • options: (Hash) (defaults to: {}) —

    plugin specific option. The keys must correspond to a plugin id, and the values will be passed only to the plugin identified by the key.



117
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
 
# File 'lib/itly/itly.rb', line 117

def group(user_id:, group_id:, properties: {}, options: {})
  # Run only if the object is enabled and was initialized
  return unless was_initialized? && enabled?

  # Log
  log = Itly::Loggers.vars_to_log user_id: user_id, group_id: group_id, properties: properties, options: options
  logger&.info "group(#{log})"

  # Validate and run on all plugins
  event = Event.new name: 'group', properties: properties

  action = ->(plugin, combined_event) {
    plugin.group(
      user_id: user_id, group_id: group_id, properties: combined_event.properties,
      options: options[plugin.id]
    )
  }

  post_action = ->(plugin, combined_event, validation_results) {
    plugin.post_group(
      user_id: user_id, group_id: group_id, properties: combined_event.properties,
      validation_results: validation_results
    )
  }

  validate_and_send_to_plugins event: event, action: action, post_action: post_action
end

#identify(user_id:, properties: {}, options: {}) ⇒ Object

Identify a user in your application and associate all future events with their identity, or to set their traits.

Validates the properties with all registered plugins first. Raises a Itly::ValidationError if one of the validations failed and if your set the options.validation value to ERROR_ON_INVALID.

Call identify on all plugins and call post_identify on all plugins.

Example:

itly.identify user_id: 'MyUser123', role: 'admin'

Parameters:

  • user_id: (String) —

    the id of the user in your application

  • properties: (Hash) (defaults to: {}) —

    the user’s traits to pass to your application

  • options: (Hash) (defaults to: {}) —

    plugin specific option. The keys must correspond to a plugin id, and the values will be passed only to the plugin identified by the key.



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
 
# File 'lib/itly/itly.rb', line 71

def identify(user_id:, properties: {}, options: {})
  # Run only if the object is enabled and was initialized
  return unless was_initialized? && enabled?

  # Log
  log = Itly::Loggers.vars_to_log user_id: user_id, properties: properties, options: options
  logger&.info "identify(#{log})"

  # Validate and run on all plugins
  event = Event.new name: 'identify', properties: properties

  action = ->(plugin, combined_event) {
    plugin.identify(
      user_id: user_id, properties: combined_event.properties, options: options[plugin.id]
    )
  }

  post_action = ->(plugin, combined_event, validation_results) {
    plugin.post_identify(
      user_id: user_id, properties: combined_event.properties, validation_results: validation_results
    )
  }

  validate_and_send_to_plugins event: event, action: action, post_action: post_action
end

#is_loaded? ⇒ Boolean

Returns:

  • (Boolean) 


339
340
341
 
# File 'lib/itly/itly.rb', line 339

def is_loaded?
  !!@is_initialized
end

#load(context: nil) {|@options| ... } ⇒ Object

Load options ans the plugins. It must be called only once on an object.

Accept an optional block to define the options. The variable yielded in the block is of type ‘Itly::Options`.

Calls the load method of each plugin passing the options object as an argument.

Parameters:

  • context: (Hash, nil) (defaults to: nil) —

    to assign to the “context” Event object. Default to nil

Yields:

Raises:



29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
 
# File 'lib/itly/itly.rb', line 29

def load(context: nil)
  # Ensure #load was not already called on this object
  raise InitializationError, 'Itly is already initialized.' if @is_initialized

  # Create a new Options object and yield it is a block is provided
  @options = Itly::Options.new
  yield @options if block_given?

  # Create the context event
  @context = context.nil? ? nil : Itly::Event.new(name: 'context', properties: context)

  # Log
  logger&.info 'load()'
  logger&.info 'Itly is disabled!' unless enabled?
  logger&.warn 'No plugin enabled!' if options.plugins.empty?

  # pass options to plugins
  run_on_plugins { |plugin| plugin.load options: options.for_plugin } if enabled?

  # Mark that the #load method was called on this object
  @is_initialized = true
end

#page(user_id:, category: nil, name: nil, properties: {}, options: {}) ⇒ Object

The Page method lets you record page views, along with optional extra information about the page viewed by the user.

Validates the properties with all registered plugins first. Raises a Itly::ValidationError if one of the validations failed and if your set the options.validation value to ERROR_ON_INVALID.

Call page on all plugins and call post_page on all plugins.

Example:

itly.page user_id: 'MyUser123', category: 'Products', name: 'MyPage456', name: 'Iteratively, Inc.'

Parameters:

  • user_id: (String) —

    the id of the user in your application

  • category: (String) (defaults to: nil) —

    the category of the page

  • name: (String) (defaults to: nil) —

    the name of the page.

  • properties: (Hash) (defaults to: {}) —

    The list of properties to pass to your application

  • options: (Hash) (defaults to: {}) —

    plugin specific option. The keys must correspond to a plugin id, and the values will be passed only to the plugin identified by the key.



166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
 
# File 'lib/itly/itly.rb', line 166

def page(user_id:, category: nil, name: nil, properties: {}, options: {})
  # Run only if the object is enabled and was initialized
  return unless was_initialized? && enabled?

  # Log
  log = Itly::Loggers.vars_to_log(
    user_id: user_id, category: category, name: name, properties: properties, options: options
  )
  logger&.info "page(#{log})"

  # Validate and run on all plugins
  event = Event.new name: 'page', properties: properties

  action = ->(plugin, combined_event) {
    plugin.page(
      user_id: user_id, category: category, name: name, properties: combined_event.properties,
      options: options[plugin.id]
    )
  }

  post_action = ->(plugin, combined_event, validation_results) {
    plugin.post_page(
      user_id: user_id, category: category, name: name, properties: combined_event.properties,
      validation_results: validation_results
    )
  }

  validate_and_send_to_plugins event: event, action: action, post_action: post_action
end

#reset ⇒ Object

Reset the SDK’s (and all plugins’) state. This method is usually called when a user logs out.

Call reset on all plugins.



308
309
310
311
312
313
314
315
316
317
 
# File 'lib/itly/itly.rb', line 308

def reset
  # Run only if the object is enabled and was initialized
  return unless was_initialized? && enabled?

  # Log
  logger&.info 'reset()'

  # Run on all plugins
  run_on_plugins(&:reset)
end

#shutdown ⇒ Object

Send shutdown to your plugins.

Call shutdown on all plugins.



292
293
294
295
296
297
298
299
300
301
 
# File 'lib/itly/itly.rb', line 292

def shutdown
  # Run only if the object is enabled and was initialized
  return unless was_initialized? && enabled?

  # Log
  logger&.info 'shutdown()'

  # Run on all plugins
  run_on_plugins(&:shutdown)
end

#track(user_id:, event:, options: {}) ⇒ Object

Track an event, call the event’s corresponding function on plugins.

Validates the properties of the Event object passed as parameter with all registered plugins first. Raises a Itly::ValidationError if one of the validations failed and if your set the options.validation value to ERROR_ON_INVALID.

The properties of the context instance attribute passed when called #load are merged with the event parameter before validation and calling the event on your application.

Call track on all plugins and call post_track on all plugins.

Example:

event = Itly::Event.new name: 'watched_video', properties: {'video_id' => 'MyVider123', watch_time: '123456'}
itly.track user_id: 'MyUser123', event: event

Parameters:

  • user_id: (String) —

    the id of the user in your application

  • event: (Event) —

    the Event object to pass to your application

  • options: (Hash) (defaults to: {}) —

    plugin specific option. The keys must correspond to a plugin id, and the values will be passed only to the plugin identified by the key.



220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
 
# File 'lib/itly/itly.rb', line 220

def track(user_id:, event:, options: {})
  # Run only if the object is enabled and was initialized
  return unless was_initialized? && enabled?

  # Log
  log = Itly::Loggers.vars_to_log(
    user_id: user_id, event: event&.name, properties: event&.properties, options: options
  )
  logger&.info "track(#{log})"

  # Validate and run on all plugins
  action = ->(plugin, combined_event) {
    plugin.track user_id: user_id, event: combined_event, options: options[plugin.id]
  }

  post_action = ->(plugin, combined_event, validation_results) {
    plugin.post_track user_id: user_id, event: combined_event, validation_results: validation_results
  }

  validate_and_send_to_plugins event: event, context: @context, action: action, post_action: post_action
end

#validate(event:) ⇒ Array

Validate an Event

Call event on all plugins and collect their return values.

Parameters:

  • event: (Event) —

    the event to validate

Returns:

  • (Array) —

    array of Itly::ValidationResponse objects that were generated by the plugins



328
329
330
331
332
333
334
335
336
337
 
# File 'lib/itly/itly.rb', line 328

def validate(event:)
  return unless was_initialized? && validation_enabled?

  # Log
  log = Itly::Loggers.vars_to_log event: event
  logger&.info "validate(#{log})"

  # Run on all plugins
  run_on_plugins { |plugin| plugin.validate event: event }
end