Class: Itly::Plugin::Segment

Inherits:
Itly::Plugin show all
Defined in:
lib/itly/plugin/segment/segment.rb,
lib/itly/plugin/segment/options.rb,
lib/itly/plugin/segment/version.rb,
lib/itly/plugin/segment/call_options.rb

Overview

Segment plugin class for Itly SDK

Defined Under Namespace

Classes: CallOptions, Options

Constant Summary collapse

VERSION = 
'0.1.1'

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(write_key:, disabled: false) ⇒ Segment

Instantiate a new Plugin::Segment

Parameters:

  • write_key: (String) —

    specify the Segment write key

  • disabled: (TrueClass/FalseClass) (defaults to: false) —

    set to true to disable the plugin. Default to false



22
23
24
25
26
 
# File 'lib/itly/plugin/segment/segment.rb', line 22

def initialize(write_key:, disabled: false)
  super()
  @write_key = write_key
  @disabled = disabled
end

Instance Attribute Details

#client ⇒ Object (readonly)

Returns the value of attribute client.



14
15
16
 
# File 'lib/itly/plugin/segment/segment.rb', line 14

def client
  @client
end

#disabled ⇒ Object (readonly)

Returns the value of attribute disabled.



14
15
16
 
# File 'lib/itly/plugin/segment/segment.rb', line 14

def disabled
  @disabled
end

Instance Method Details

#alias(user_id:, previous_id:, options: nil) ⇒ Object

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

Raise an error if the client fails

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: (Itly::Plugin::Segment::AliasOptions) (defaults to: nil) —

    the plugin specific options



195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
 
# File 'lib/itly/plugin/segment/segment.rb', line 195

def alias(user_id:, previous_id:, options: nil)
  super
  return unless enabled?

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

  # Send through the client
  payload = { user_id: user_id, previous_id: previous_id }
  payload.merge! options.to_hash if options

  call_end_point(options&.callback) do
    @client.alias(**payload)
  end
end

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

Associate a user with their group

Raise an error if the client fails

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: nil) —

    the properties to pass to your application

  • options: (Itly::Plugin::Segment::GroupOptions) (defaults to: nil) —

    the plugin specific options



98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
 
# File 'lib/itly/plugin/segment/segment.rb', line 98

def group(user_id:, group_id:, properties: nil, options: nil)
  super
  return unless enabled?

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

  # Send through the client
  payload = { user_id: user_id, group_id: group_id }
  payload.merge! traits: properties.dup if properties
  payload.merge! options.to_hash if options

  call_end_point(options&.callback) do
    @client.group(**payload)
  end
end

#id ⇒ String

Get the plugin ID

Returns:

  • (String) —

    plugin id



219
220
221
 
# File 'lib/itly/plugin/segment/segment.rb', line 219

def id
  'segment'
end

#identify(user_id:, properties: nil, options: nil) ⇒ Object

Identify a user

Raise an error if the client fails

Parameters:

  • user_id: (String) —

    the id of the user in your application

  • properties: (Hash) (defaults to: nil) —

    the properties containing user’s traits to pass to your application

  • options: (Itly::Plugin::Segment::IdentifyOptions) (defaults to: nil) —

    the plugin specific options



70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
 
# File 'lib/itly/plugin/segment/segment.rb', line 70

def identify(user_id:, properties: nil, options: nil)
  super
  return unless enabled?

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

  # Send through the client
  payload = { user_id: user_id }
  payload.merge! traits: properties.dup if properties
  payload.merge! options.to_hash if options

  call_end_point(options&.callback) do
    @client.identify(**payload)
  end
end

#load(options:) ⇒ Object

Initialize Segment::Tracker client

Parameters:

  • options: (Itly::PluginOptions) —

    plugin options



33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
 
# File 'lib/itly/plugin/segment/segment.rb', line 33

def load(options:)
  super
  # Get options
  @logger = options.logger

  # Log
  @logger&.info "#{id}: load()"

  if @disabled
    @logger&.info "#{id}: plugin is disabled!"
    return
  end

  # Configure client
  error_handler = proc do |error_code, error_body, exception, _|
    message = 'The client returned an error.'
    message += " Error code: #{error_code}. " if error_code
    message += " Error body: #{error_body}. " if error_body
    message += " Exception #{exception.class.name}: #{exception.message}." if exception

    raise Itly::RemoteError, message
  end

  @client = ::SimpleSegment::Client.new \
    write_key: @write_key, logger: @logger,
    on_error: error_handler
end

#name ⇒ Object

Segment specific plugin options class for calls to plugin methods



54
55
56
57
58
59
60
61
 
# File 'lib/itly/plugin/segment/call_options.rb', line 54

%w[Identify Group Page Track Alias].each do |name|
  class_eval(
    <<-EVAL, __FILE__, __LINE__ + 1
      class #{name}Options < CallOptions         # class IdentifyOptions < CallOptions
      end                                        # end
    EVAL
  )
end

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

Record page views

Raise an error if the client fails

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: nil) —

    the properties to pass to your application

  • options: (Itly::Plugin::Segment::PageOptions) (defaults to: nil) —

    the plugin specific options



129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
 
# File 'lib/itly/plugin/segment/segment.rb', line 129

def page(user_id:, category: nil, name: nil, properties: nil, options: nil)
  super
  return unless enabled?

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

  # Send through the client
  payload = { user_id: user_id }
  payload.merge! name: name if name
  payload.merge! options.to_hash if options
  if properties && category
    payload.merge! properties: properties.dup.merge(category: category)
  elsif properties
    payload.merge! properties: properties.dup
  elsif category
    payload.merge! properties: { category: category }
  end

  call_end_point(options&.callback) do
    @client.page(**payload)
  end
end

#track(user_id:, event:, options: nil) ⇒ Object

Track an event

Raise an error if the client fails

Parameters:

  • user_id: (String) —

    the id of the user in your application

  • event: (Event) —

    the Event object to pass to your application

  • options: (Itly::Plugin::Segment::TrackOptions) (defaults to: nil) —

    the plugin specific options



165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
 
# File 'lib/itly/plugin/segment/segment.rb', line 165

def track(user_id:, event:, options: nil)
  super
  return unless enabled?

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

  # Send through the client
  payload = { user_id: user_id, event: event.name, properties: event.properties.dup }
  payload.merge! options.to_hash if options

  call_end_point(options&.callback) do
    @client.track(**payload)
  end
end