Class: Mixpanel::Tracker

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

Overview

Use Mixpanel::Tracker to track events and profile updates in your application. To track an event, call

tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN)
Mixpanel::Tracker.track(a_distinct_id, an_event_name, {properties})

To send people updates, call

tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN)
tracker.people.set(a_distinct_id, {properties})

To send groups updates, call

tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN)
tracker.groups.set(group_key, group_id, {properties})

You can find your project token in the settings dialog for your project, inside of the Mixpanel web application.

Mixpanel::Tracker is a subclass of Mixpanel::Events, and exposes an instance of Mixpanel::People as Tracker#people and an instance of Mixpanel::Groups as Tracker#groups

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(token, error_handler = nil, credentials: nil, local_flags_config: nil, remote_flags_config: nil, &block) ⇒ Tracker

Takes your Mixpanel project token, as a string.

tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN)

By default, the tracker will send an message to Mixpanel synchronously with each call, using an instance of Mixpanel::Consumer.

You can also provide a block to the constructor to specify particular consumer behaviors (for example, if you wanted to write your messages to a queue instead of sending them directly to Mixpanel)

tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN) do |type, message|
   @kestrel.set(MY_MIXPANEL_QUEUE, [type,message].to_json)
end

If a block is provided, it is passed a type (one of :event or :profile_update) and a string message. This same format is accepted by Mixpanel::Consumer#send! and Mixpanel::BufferedConsumer#send!

Optional parameters:

  • credentials: ServiceAccountCredentials for authentication (used for import and feature flags)
  • local_flags_config: Configuration hash for local feature flags
  • remote_flags_config: Configuration hash for remote feature flags


70
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
96
97
 
# File 'lib/mixpanel-ruby/tracker.rb', line 70

def initialize(token, error_handler=nil, credentials: nil, local_flags_config: nil, remote_flags_config: nil, &block)
  super(token, error_handler, credentials: credentials, &block)

  @people = People.new(token, error_handler, &block)
  @groups = Groups.new(token, error_handler, &block)

  # Initialize local flags if config provided
  if local_flags_config
    @local_flags = Flags::LocalFlagsProvider.new(
      token,
      local_flags_config,
      method(:track),  # Pass bound method as callback
      error_handler || ErrorHandler.new,
      credentials
    )
  end

  # Initialize remote flags if config provided
  if remote_flags_config
    @remote_flags = Flags::RemoteFlagsProvider.new(
      token,
      remote_flags_config,
      method(:track),  # Pass bound method as callback
      error_handler || ErrorHandler.new,
      credentials
    )
  end
end

Instance Attribute Details

#groups ⇒ Object (readonly)

An instance of Mixpanel::Groups. Use this to send groups updates



36
37
38
 
# File 'lib/mixpanel-ruby/tracker.rb', line 36

def groups
  @groups
end

#local_flags ⇒ Object (readonly)

An instance of Mixpanel::Flags::LocalFlagsProvider. Use this for client-side feature flag evaluation



40
41
42
 
# File 'lib/mixpanel-ruby/tracker.rb', line 40

def local_flags
  @local_flags
end

#people ⇒ Object (readonly)

An instance of Mixpanel::People. Use this to send profile updates



33
34
35
 
# File 'lib/mixpanel-ruby/tracker.rb', line 33

def people
  @people
end

#remote_flags ⇒ Object (readonly)

An instance of Mixpanel::Flags::RemoteFlagsProvider. Use this for server-side feature flag evaluation



44
45
46
 
# File 'lib/mixpanel-ruby/tracker.rb', line 44

def remote_flags
  @remote_flags
end

Instance Method Details

#alias(alias_id, real_id, events_endpoint = nil) ⇒ Object

Creates a distinct_id alias. Events and updates with an alias will be considered by mixpanel to have the same source, and refer to the same profile.

Multiple aliases can map to the same real_id, once a real_id is used to track events or send updates, it should never be used as an alias itself.

Alias requests are always sent synchronously, directly to the Mixpanel service, regardless of how the tracker is configured.



183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
 
# File 'lib/mixpanel-ruby/tracker.rb', line 183

def alias(alias_id, real_id, events_endpoint=nil)
  consumer = Mixpanel::Consumer.new(events_endpoint)
  data = {
    'event' => '$create_alias',
    'properties' => {
      'distinct_id' => real_id,
      'alias' => alias_id,
      'token' => @token,
    }
  }

  message = {'data' => data}

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

  ret
end

#generate_tracking_url(distinct_id, event, properties = {}, endpoint = nil) ⇒ Object

A call to #generate_tracking_url will return a formatted url for pixel based tracking. #generate_tracking_url takes 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. For more information, please see: https://mixpanel.com/docs/api-documentation/pixel-based-event-tracking

tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN)

# generate pixel tracking url in order to track that user
# "12345"'s credit card was declined
url = tracker.generate_tracking_url("12345", "Credit Card Declined", {
  'time' => 1310111365
})

url == 'https://api.mixpanel.com/track/?data=[BASE_64_JSON_EVENT]&ip=1&img=1'


224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
 
# File 'lib/mixpanel-ruby/tracker.rb', line 224

def generate_tracking_url(distinct_id, event, properties={}, endpoint=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)

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

  endpoint = endpoint || 'https://api.mixpanel.com/track/'
  data = Base64.urlsafe_encode64(raw_data.to_json)

  "#{endpoint}?data=#{data}&ip=1&img=1"
end

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

A call to #import is to import an event occurred in the past. #import takes 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)

# Using deprecated API key (still supported)
tracker.import("API_KEY", "12345", "Credit Card Declined", {
  'time' => 1310111365
})

# Using service account credentials (recommended)
credentials = Mixpanel::ServiceAccountCredentials.new(username, secret, project_id)
tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN, credentials: credentials)
tracker.import(nil, "12345", "Welcome Email Sent", {
    'Email Template' => 'Pretty Pink Welcome',
    'User Sign-up Cohort' => 'July 2013',
    'time' => 1310111365
})


145
146
147
148
149
 
# File 'lib/mixpanel-ruby/tracker.rb', line 145

def import(api_key, distinct_id, event, properties={}, ip=nil)
  # This is here strictly to allow rdoc to include the relevant
  # documentation
  super
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.

Service account credentials must be provided when creating the Tracker. This method provides a cleaner API 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)

# Import a historical event
tracker.import_events('user123', 'Past Event', {
    'Email Template' => 'Welcome Email',
    'time' => 1369353600
})


167
168
169
170
171
 
# File 'lib/mixpanel-ruby/tracker.rb', line 167

def import_events(distinct_id, event, properties={}, ip=nil)
  # This is here strictly to allow rdoc to include the relevant
  # documentation
  super
end

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

A call to #track is a report that an event has occurred. #track takes 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'
})


117
118
119
120
121
 
# File 'lib/mixpanel-ruby/tracker.rb', line 117

def track(distinct_id, event, properties={}, ip=nil)
  # This is here strictly to allow rdoc to include the relevant
  # documentation
  super
end