Class: Mixpanel::Events

Inherits:
Object
  • Object
show all
Defined in:
lib/mixpanel-ruby/events.rb

Overview

Handles formatting Mixpanel event tracking messages and sending them to the consumer. Mixpanel::Tracker is a subclass of this class, and the best way to track events is to instantiate a Mixpanel::Tracker

tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN) # Has all of the methods of Mixpanel::Event
tracker.track(...)

Direct Known Subclasses

Tracker

Instance Method Summary collapse

Constructor Details

#initialize(token, error_handler = nil, credentials: nil, &block) ⇒ Events

You likely won't need to instantiate an instance of Mixpanel::Events directly. The best way to get an instance is to use Mixpanel::Tracker

# tracker has all of the methods of Mixpanel::Events
tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN)


25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
 
# File 'lib/mixpanel-ruby/events.rb', line 25

def initialize(token, error_handler=nil, credentials: nil, &block)
  @token = token
  @error_handler = error_handler || ErrorHandler.new
  @credentials = credentials

  if block && credentials
    warn '[WARNING] credentials passed to Events/Tracker are ignored when a custom sink block is provided. Pass credentials to your consumer directly.'
  end

  if block
    @sink = block
  else
    consumer = Consumer.new(credentials: credentials)
    @sink = consumer.method(:send!)
  end
end

Instance Method Details

#import(api_key, distinct_id, event, properties = {}, ip = nil) ⇒ Object

Imports an event that has occurred in the past, along with a distinct_id representing the source of that event (for example, a user id), an event name describing the event and a set of properties describing that event. Properties are provided as a Hash with string keys and strings, numbers or booleans as values. By default, we pass the time of the method call as the time the event occured, if you wish to override this pass a timestamp in the properties hash.

# Recommended: Use import_events() instead
credentials = Mixpanel::ServiceAccountCredentials.new(username, secret, project_id)
tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN, credentials: credentials)
tracker.import_events("12345", "Welcome Email Sent", {
    'Email Template' => 'Pretty Pink Welcome',
    'User Sign-up Cohort' => 'July 2013',
    'time' => 1369353600,
})

# Legacy: Pass API key as first parameter (deprecated)
tracker.import("API_KEY", "12345", "Credit Card Declined")


107
108
109
110
111
112
113
114
115
116
117
118
119
120
 
# File 'lib/mixpanel-ruby/events.rb', line 107

def import(api_key, distinct_id, event, properties={}, ip=nil)
  # Warn about deprecated API key usage
  if api_key && !api_key.to_s.empty?
    warn '[DEPRECATION] Passing api_key to import() is deprecated. Use ServiceAccountCredentials in the constructor instead. See https://docs.mixpanel.com/docs/tracking-methods/sdks/ruby#service-account-authentication'
  end

  # Warn when using import(nil, ...) - recommend import_events instead
  if api_key.nil? && @credentials
    warn '[DEPRECATION] Using import(nil, ...) is deprecated. Use import_events(...) instead for cleaner API.'
  end

  # Delegate to internal implementation
  import_internal(api_key, distinct_id, event, properties, ip)
end

#import_events(distinct_id, event, properties = {}, ip = nil) ⇒ Object

Import an event using service account credentials from the constructor. This is the recommended method for importing historical events with service accounts.

Credentials must be provided in the Tracker/Events constructor. This method is cleaner than import() as it doesn't require passing nil as the first parameter.

credentials = Mixpanel::ServiceAccountCredentials.new(username, secret, project_id)
tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN, credentials: credentials)

tracker.import_events('user123', 'Past Event', {
    'time' => 1369353600,
    'Source' => 'Import'
})


136
137
138
139
140
141
142
143
 
# File 'lib/mixpanel-ruby/events.rb', line 136

def import_events(distinct_id, event, properties={}, ip=nil)
  unless @credentials
    raise ArgumentError, 'import_events requires credentials in constructor. Use: Tracker.new(token, credentials: credentials)'
  end

  # Delegate to internal implementation with nil api_key (uses constructor credentials)
  import_internal(nil, distinct_id, event, properties, ip)
end

#track(distinct_id, event, properties = {}, ip = nil) ⇒ Object

Notes that an event has occurred, along with a distinct_id representing the source of that event (for example, a user id), an event name describing the event and a set of properties describing that event. Properties are provided as a Hash with string keys and strings, numbers or booleans as values.

tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN)

# Track that user "12345"'s credit card was declined
tracker.track("12345", "Credit Card Declined")

# Properties describe the circumstances of the event,
# or aspects of the source or user associated with the event
tracker.track("12345", "Welcome Email Sent", {
    'Email Template' => 'Pretty Pink Welcome',
    'User Sign-up Cohort' => 'July 2013'
})


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
 
# File 'lib/mixpanel-ruby/events.rb', line 59

def track(distinct_id, event, properties={}, ip=nil)
  properties = {
    'distinct_id' => distinct_id,
    'token' => @token,
    'time' => (Time.now.to_f * 1000).to_i,
    'mp_lib' => 'ruby',
    '$lib_version' => Mixpanel::VERSION,
  }.merge(properties)
  properties['ip'] = ip if ip

  data = {
    'event' => event,
    'properties' => properties,
  }

  message = {'data' => data}

  ret = true
  begin
    @sink.call(:event, message.to_json)
  rescue MixpanelError => e
    @error_handler.handle(e)
    ret = false
  end

  ret
end