mixpanel-ruby 0.2.0 → 0.3.0

data/.gitignore

@@ -1,3 +1,4 @@
+*~
 Gemfile.lock
 html
 mixpanel-ruby*.gem

data/lib/mixpanel-ruby/consumer.rb

@@ -51,6 +51,11 @@ module Mixpanel
   # Mixpanel::Consumer is the default consumer. It sends each message,
   # as the message is recieved, directly to Mixpanel.
   class Consumer
+
+    # Create a Mixpanel::Consumer. If you provide endpoint arguments,
+    # they will be used instead of the default Mixpanel endpoints.
+    # This can be useful for proxying, debugging, or if you prefer
+    # not to use SSL for your events.
     def initialize(events_endpoint=nil, update_endpoint=nil)
       @events_endpoint = events_endpoint || 'https://api.mixpanel.com/track'
       @update_endpoint = update_endpoint || 'https://api.mixpanel.com/engage'
@@ -58,6 +63,10 @@ module Mixpanel
 
     # Send the given string message to Mixpanel. Type should be
     # one of :event or :profile_update, which will determine the endpoint.
+    #
+    # Mixpanel::Consumer#send sends messages to Mixpanel immediately on
+    # each call. To reduce the overall bandwidth you use when communicating
+    # with Mixpanel, you can also use Mixpanel::BufferedConsumer
     def send(type, message)
       type = type.to_sym
       endpoint = {
@@ -106,6 +115,15 @@ module Mixpanel
   class BufferedConsumer
     MAX_LENGTH = 50
 
+    # Create a Mixpanel::BufferedConsumer. If you provide endpoint arguments,
+    # they will be used instead of the default Mixpanel endpoints.
+    # This can be useful for proxying, debugging, or if you prefer
+    # not to use SSL for your events.
+    #
+    # You can also change the preferred buffer size before the
+    # consumer automatically sends its buffered events. The Mixpanel
+    # endpoints have a limit of 50 events per HTTP request, but
+    # you can lower the limit if your individual events are very large.
     def initialize(events_endpoint=nil, update_endpoint=nil, max_buffer_length=MAX_LENGTH)
       @max_length = [ max_buffer_length, MAX_LENGTH ].min
       @consumer = Consumer.new(events_endpoint, update_endpoint)

data/lib/mixpanel-ruby/people.rb

@@ -10,7 +10,7 @@ module Mixpanel
   # to instantiate this class directly- to send
   # profile updates, use Mixpanel::Tracker#people
   #
-  #     tracker = Mixpanel::Tracker.new
+  #     tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN)
   #     tracker.people.set(...) # Or .append(..), or track_charge(...) etc.
   class People
 
@@ -42,7 +42,7 @@ module Mixpanel
     #        'Sign-Up Date' => DateTime.now
     #    });
     #
-    # If you provide an ip argument, Mixpanel will use that
+    # If you provide an ip argument, \Mixpanel will use that
     # ip address for geolocation (rather than the ip of your server)
     def set(distinct_id, properties, ip=nil)
       properties = fix_property_dates(properties)
@@ -83,7 +83,7 @@ module Mixpanel
     end
 
     # Changes the value of properties by a numeric amount.  Takes a
-    # hash with string keys and numeric properties.  Mixpanel will add
+    # hash with string keys and numeric properties. \Mixpanel will add
     # the given amount to whatever value is currently assigned to the
     # property. If no property exists with a given name, the value
     # will be added to zero.
@@ -167,7 +167,7 @@ module Mixpanel
     end
 
     # Records a payment to you to a profile. Charges recorded with
-    # #track_charge will appear in the Mixpanel revenue report.
+    # #track_charge will appear in the \Mixpanel revenue report.
     #
     #    tracker = Mixpanel::Tracker.new
     #
@@ -185,12 +185,12 @@ module Mixpanel
       append(distinct_id, { '$transactions' => charge_properties }, ip)
     end
 
-    # Clear all charges from a Mixpanel people profile
+    # Clear all charges from a \Mixpanel people profile
     def clear_charges(distinct_id)
       unset(distinct_id, '$transactions')
     end
 
-    # Permanently delete a profile from Mixpanel people analytics
+    # Permanently delete a profile from \Mixpanel people analytics
     def delete_user(distinct_id)
       update({
           '$distinct_id' => distinct_id,
@@ -198,12 +198,13 @@ module Mixpanel
       })
     end
 
-    # Send a generic update to Mixpanel people analytics.
-    # Caller is responsible for formatting the update, as
-    # documented in the Mixpanel HTTP specification. This
+    # Send a generic update to \Mixpanel people 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 people analytics from Ruby
-    # The Mixpanel HTTP tracking API is documented at
+    # The \Mixpanel HTTP tracking API is documented at
     # http://joe.dev.mixpanel.org/help/reference/http
     def update(message)
       message = {

data/lib/mixpanel-ruby/tracker.rb

@@ -13,6 +13,9 @@ module Mixpanel
   #     tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN)
   #     tracker.people.set(a_distinct_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
   class Tracker < Events
@@ -45,6 +48,30 @@ module Mixpanel
       @people = People.new(token, &block)
     end
 
+    # 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
+    #
+    #     # 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'
+    #     })
+    def track(distinct_id, event, properties={}, ip=nil)
+      # This is here strictly to allow rdoc to include the relevant
+      # documentation
+      super
+    end
+
     # 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.

data/lib/mixpanel-ruby/version.rb

@@ -1,3 +1,3 @@
 module Mixpanel
-  VERSION = '0.2.0'
+  VERSION = '0.3.0'
 end

data/spec/mixpanel-ruby/events_spec.rb

@@ -1,5 +1,6 @@
 require 'spec_helper'
 require 'mixpanel-ruby/events.rb'
+require 'mixpanel-ruby/version.rb'
 require 'time'
 
 describe Mixpanel::Events do
@@ -22,6 +23,8 @@ describe Mixpanel::Events do
         'properties' => {
             'Circumstances' => 'During a test',
             'distinct_id' => 'TEST ID',
+            'mp_lib' => 'ruby',
+            '$lib_version' => Mixpanel::VERSION,
             'token' => 'TEST TOKEN',
             'time' => 76695784
         }

data/spec/mixpanel-ruby/tracker_spec.rb

@@ -39,6 +39,8 @@ describe Mixpanel::Tracker do
         'properties' => {
             'Circumstances' => 'During test',
             'distinct_id' => 'TEST ID',
+            'mp_lib' => 'ruby',
+            '$lib_version' => Mixpanel::VERSION,
             'token' => 'TEST TOKEN',
             'time' => 76695784
         }
@@ -59,6 +61,8 @@ describe Mixpanel::Tracker do
           { 'event' => 'Event',
             'properties' => {
               'distinct_id' => 'ID',
+              'mp_lib' => 'ruby',
+              '$lib_version' => Mixpanel::VERSION,
               'token' => 'TEST TOKEN',
               'time' => 76695784
             }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mixpanel-ruby
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
   prerelease: 
 platform: ruby
 authors: