Class: Mixpanel::Groups

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

Overview

Handles formatting Mixpanel group updates and sending them to the consumer. You will rarely need to instantiate this class directly- to send group updates, use Mixpanel::Tracker#groups

tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN)
tracker.groups.set(...) or .set_once(..), or .delete(...) etc.

Instance Method Summary collapse

Constructor Details

#initialize(token, error_handler = nil, &block) ⇒ Groups

You likely won’t need to instantiate instances of Mixpanel::Groups directly. The best way to get an instance of Mixpanel::Groups is

tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN)
tracker.groups # An instance of Mixpanel::Groups



25
26
27
28
29
30
31
32
33
34
35
 
# File 'lib/mixpanel-ruby/groups.rb', line 25

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

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

Instance Method Details

#delete_group(group_key, group_id, optional_params = {}) ⇒ Object

Permanently delete a group from Mixpanel groups analytics (all group properties on events stay)



154
155
156
157
158
159
160
 
# File 'lib/mixpanel-ruby/groups.rb', line 154

def delete_group(group_key, group_id, optional_params={})
  update({
    '$group_key' => group_key,
    '$group_id' => group_id,
    '$delete' => '',
  }.merge(optional_params))
end

#remove(group_key, group_id, properties, ip = nil, optional_params = {}) ⇒ Object

Removes a specific value in a list property

tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN)

# removes "socks" from the "Items purchased" list property
# for the specified group
tracker.groups.remove("GROUP KEY", "1234", { 'Items purchased' => 'socks' })



93
94
95
96
97
98
99
100
101
102
103
 
# File 'lib/mixpanel-ruby/groups.rb', line 93

def remove(group_key, group_id, properties, ip=nil, optional_params={})
  properties = fix_property_dates(properties)
  message = {
    '$group_key' => group_key,
    '$group_id' => group_id,
    '$remove' => properties,
  }.merge(optional_params)
  message['$ip'] = ip if ip

  update(message)
end

#set(group_key, group_id, properties, ip = nil, optional_params = {}) ⇒ Object

Sets properties on a group record. Takes a Hash with string keys, and values that are strings, numbers, booleans, or DateTimes

tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN)
# Sets properties on group with id "1234"
tracker.groups.set("GROUP KEY", "1234", {
    'company' => 'Acme',
    'plan' => 'Premium',
    'Sign-Up Date' => DateTime.now
});

If you provide an ip argument, Mixpanel will use that ip address for geolocation (rather than the ip of your server)



51
52
53
54
55
56
57
58
59
60
61
 
# File 'lib/mixpanel-ruby/groups.rb', line 51

def set(group_key, group_id, properties, ip=nil, optional_params={})
  properties = fix_property_dates(properties)
  message = {
    '$group_key' => group_key,
    '$group_id' => group_id,
    '$set' => properties,
  }.merge(optional_params)
  message['$ip'] = ip if ip

  update(message)
end

#set_once(group_key, group_id, properties, ip = nil, optional_params = {}) ⇒ Object

set_once works just like #set, but will only change the value of properties if they are not already present in the group. That means you can call set_once many times without changing an original value.

tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN)
tracker.groups.set_once("GROUP KEY", "1234", {
    'First Login Date': DateTime.now
});



73
74
75
76
77
78
79
80
81
82
83
 
# File 'lib/mixpanel-ruby/groups.rb', line 73

def set_once(group_key, group_id, properties, ip=nil, optional_params={})
  properties = fix_property_dates(properties)
  message = {
    '$group_key' => group_key,
    '$group_id' => group_id,
    '$set_once' => properties,
  }.merge(optional_params)
  message['$ip'] = ip if ip

  update(message)
end

#union(group_key, group_id, properties, ip = nil, optional_params = {}) ⇒ Object

Set union on list valued properties. Associates a list containing all elements of a given list, and all elements currently in a list associated with the given property. After a union, every element in the list associated with a property will be unique.

tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN)
tracker.groups.union("GROUP KEY", "1234", {
    'Levels Completed' => ['Suffragette City']
});



116
117
118
119
120
121
122
123
124
125
126
 
# File 'lib/mixpanel-ruby/groups.rb', line 116

def union(group_key, group_id, properties, ip=nil, optional_params={})
  properties = fix_property_dates(properties)
  message = {
    '$group_key' => group_key,
    '$group_id' => group_id,
    '$union' => properties,
  }.merge(optional_params)
  message['$ip'] = ip if ip

  update(message)
end

#unset(group_key, group_id, properties, ip = nil, optional_params = {}) ⇒ Object

Removes properties and their values from a group.

tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN)

# removes a single property and its value from a group
tracker.groups.unset("GROUP KEY", "1234", "Overdue Since")

# removes multiple properties and their values from a group
tracker.groups.unset("GROUP KEY",
                     "1234",
                     ["Overdue Since", "Paid Date"])



140
141
142
143
144
145
146
147
148
149
150
 
# File 'lib/mixpanel-ruby/groups.rb', line 140

def unset(group_key, group_id, properties, ip=nil, optional_params={})
  properties = [properties] unless properties.is_a?(Array)
  message = {
    '$group_key' => group_key,
    '$group_id' => group_id,
    '$unset' => properties,
  }.merge(optional_params)
  message['$ip'] = ip if ip

  update(message)
end

#update(message) ⇒ Object

Send a generic update to Mixpanel groups analytics. Caller is responsible for formatting the update message, as documented in the Mixpanel HTTP specification, and passing the message as a dict to #update. This method might be useful if you want to use very new or experimental features of groups analytics from Ruby The Mixpanel HTTP tracking API is documented at mixpanel.com/help/reference/http



170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
 
# File 'lib/mixpanel-ruby/groups.rb', line 170

def update(message)
  data = {
    '$token' => @token,
    '$time' =>  Time.now.to_f,
  }.merge(message)

  message = {'data' => data}

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

  ret
end