class Segment::Analytics::Client

Public Class Methods

new(attrs = {}) click to toggle source

public: Creates a new client

attrs - Hash

:app_id         - String of your project's app_id
:max_queue_size - Fixnum of the max calls to remain queued (optional)
:on_error       - Proc which handles error calls from the API
# File lib/segment/analytics/client.rb, line 18
def initialize attrs = {}
  symbolize_keys! attrs

  @queue = Queue.new
  @app_id = attrs[:app_id]
  @max_queue_size = attrs[:max_queue_size] || Defaults::Queue::MAX_SIZE
  @options = attrs
  @worker_mutex = Mutex.new
  @worker = Worker.new @queue, @app_id, @options

  check_app_id!

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

Public Instance Methods

alias(attrs) click to toggle source

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
# File lib/segment/analytics/client.rb, line 134
def alias(attrs)
  symbolize_keys! attrs

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

  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],
    :timestamp => datetime_in_iso8601(timestamp),
    :type => 'alias'
  })
end
flush() click to toggle source

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

Use only for scripts which are not long-running, and will
specifically exit
# 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) click to toggle source

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
# File lib/segment/analytics/client.rb, line 167
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] || {}

  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,
    :timestamp => datetime_in_iso8601(timestamp),
    :type => 'group'
  })
end
identify(attrs) click to toggle source

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
# File lib/segment/analytics/client.rb, line 98
def identify attrs
  symbolize_keys! attrs
  check_user_id! attrs

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

  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],
    :timestamp => datetime_in_iso8601(timestamp),
    :type => 'identify'
  })
end
page(attrs) click to toggle source

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
# File lib/segment/analytics/client.rb, line 208
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] || {}

  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,
    :timestamp => datetime_in_iso8601(timestamp),
    :type => 'page'
  })
end
queued_messages() click to toggle source

public: Returns the number of queued messages

returns Fixnum of messages in the queue

# File lib/segment/analytics/client.rb, line 280
def queued_messages
  @queue.length
end
screen(attrs) click to toggle source

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
# File lib/segment/analytics/client.rb, line 248
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] || {}

  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,
    :timestamp => timestamp.iso8601,
    :type => 'screen'
  })
end
track(attrs) click to toggle source

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.
# File lib/segment/analytics/client.rb, line 55
def track attrs
  symbolize_keys! attrs
  check_user_id! attrs

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

  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,
    :timestamp => datetime_in_iso8601(timestamp),
    :type => 'track'
  })
end

Private Instance Methods

add_context(context) click to toggle source

private: Adds contextual information to the call

context - Hash of call context

# File lib/segment/analytics/client.rb, line 313
def add_context(context)
  context[:library] =  { :name => "analytics-ruby", :version => Segment::Analytics::VERSION.to_s }
end
check_app_id!() click to toggle source

private: Checks that the app_id is properly initialized

# File lib/segment/analytics/client.rb, line 318
def check_app_id!
  fail ArgumentError, 'App id must be initialized' if @app_id.nil?
end
check_presence!(obj, name) click to toggle source

private: Ensures that a string is non-empty

obj - String|Number that must be non-blank name - Name of the validated value

# File lib/segment/analytics/client.rb, line 304
def check_presence!(obj, name)
  if obj.nil? || (obj.is_a?(String) && obj.empty?)
    fail ArgumentError, "#{name} must be given"
  end
end
check_timestamp!(timestamp) click to toggle source

private: Checks the timstamp option to make sure it is a Time.

# File lib/segment/analytics/client.rb, line 323
def check_timestamp!(timestamp)
  fail ArgumentError, 'Timestamp must be a Time' unless timestamp.is_a? Time
end
check_user_id!(attrs) click to toggle source
# File lib/segment/analytics/client.rb, line 340
def check_user_id! attrs
  fail ArgumentError, 'Must supply either user_id or anonymous_id' unless attrs[:user_id] || attrs[:anonymous_id]
end
enqueue(action) click to toggle source

private: Enqueues the action.

returns Boolean of whether the item was added to the queue.

# File lib/segment/analytics/client.rb, line 289
def enqueue(action)
  # add our request id for tracing purposes
  action[:messageId] = uid
  unless queue_full = @queue.length >= @max_queue_size
    ensure_worker_running
    @queue << action
  end
  !queue_full
end
ensure_worker_running() click to toggle source
# File lib/segment/analytics/client.rb, line 344
def ensure_worker_running
  return if worker_running?
  @worker_mutex.synchronize do
    return if worker_running?
    @worker_thread = Thread.new do
      @worker.run
    end
  end
end
event(attrs) click to toggle source
# File lib/segment/analytics/client.rb, line 327
def event attrs
  symbolize_keys! attrs

  {
    :userId => user_id,
    :name => name,
    :properties => properties,
    :context => context,
    :timestamp => datetime_in_iso8601(timestamp),
    :type => 'screen'
  }
end
worker_running?() click to toggle source
# File lib/segment/analytics/client.rb, line 354
def worker_running?
  @worker_thread && @worker_thread.alive?
end