mixpanel-ruby-with-pixel-tracking 1.4.0

data/lib/mixpanel-ruby/events.rb

@@ -0,0 +1,116 @@
+require 'mixpanel-ruby/consumer'
+require 'time'
+
+module Mixpanel
+
+  # 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 # Has all of the methods of Mixpanel::Event
+  #     tracker.track(...)
+  #
+  class 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(...)
+    #
+    def initialize(token, &block)
+      @token = token
+      if block
+        @sink = block
+      else
+        consumer = Consumer.new
+        @sink = consumer.method(:send)
+      end
+    end
+
+    # 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
+    #
+    #     # 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, as_pixel=nil)
+      properties = {
+          'distinct_id' => distinct_id,
+          'token' => @token,
+          'time' => Time.now.to_i,
+          'mp_lib' => 'ruby',
+          '$lib_version' => Mixpanel::VERSION
+      }.merge(properties)
+      if ip
+        properties['ip'] = ip
+      end
+
+      data = {
+        'event' => event,
+        'properties' => properties
+      }
+
+      message = {
+        'data' => data
+      }
+
+      @sink.call(:event, message.to_json, as_pixel)
+    end
+
+    # 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.
+    #
+    #     tracker = Mixpanel::Tracker.new
+    #
+    #     # Track that user "12345"'s credit card was declined
+    #     tracker.import("API_KEY", "12345", "Credit Card Declined")
+    #
+    #     # Properties describe the circumstances of the event,
+    #     # or aspects of the source or user associated with the event
+    #     tracker.import("API_KEY", "12345", "Welcome Email Sent", {
+    #         'Email Template' => 'Pretty Pink Welcome',
+    #         'User Sign-up Cohort' => 'July 2013'
+    #     })
+    def import(api_key, distinct_id, event, properties={}, ip=nil)
+      properties = {
+        'distinct_id' => distinct_id,
+        'token' => @token,
+        'time' => Time.now.to_i,
+        'mp_lib' => 'ruby',
+        '$lib_version' => Mixpanel::VERSION
+      }.merge(properties)
+      if ip
+        properties['ip'] = ip
+      end
+
+      data = {
+        'event' => event,
+        'properties' => properties
+      }
+
+      message = {
+        'data' => data,
+        'api_key' => api_key
+      }
+
+      @sink.call(:import, message.to_json)
+    end
+  end
+end

data/lib/mixpanel-ruby/people.rb

@@ -0,0 +1,258 @@
+require 'mixpanel-ruby/consumer'
+require 'json'
+require 'date'
+require 'time'
+
+module Mixpanel
+
+  # Handles formatting Mixpanel profile updates and
+  # sending them to the consumer. You will rarely need
+  # to instantiate this class directly- to send
+  # profile updates, use Mixpanel::Tracker#people
+  #
+  #     tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN)
+  #     tracker.people.set(...) # Or .append(..), or track_charge(...) etc.
+  class People
+
+    # You likely won't need to instantiate instances of Mixpanel::People
+    # directly. The best way to get an instance of Mixpanel::People is
+    #
+    #     tracker = Mixpanel::Tracker.new(...)
+    #     tracker.people # An instance of Mixpanel::People
+    #
+    def initialize(token, &block)
+      @token = token
+
+      if block
+        @sink = block
+      else
+        consumer = Consumer.new
+        @sink = consumer.method(:send)
+      end
+    end
+
+    # Sets properties on a user record. Takes a Hash with string
+    # keys, and values that are strings, numbers, booleans, or
+    # DateTimes
+    #
+    #    tracker = Mixpanel::Tracker.new
+    #    # Sets properties on profile with id "1234"
+    #    tracker.people.set("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)
+    def set(distinct_id, properties, ip=nil, optional_params={})
+      properties = fix_property_dates(properties)
+      message = {
+          '$distinct_id' => distinct_id,
+          '$set' => properties,
+      }.merge(optional_params)
+
+      if ip
+        message['$ip'] = ip
+      end
+
+      update(message)
+    end
+
+    # set_once works just like #set, but will only change the
+    # value of properties if they are not already present
+    # in the profile. That means you can call set_once many times
+    # without changing an original value.
+    #
+    #    tracker = Mixpanel::Tracker.new
+    #    tracker.people.set_once("12345", {
+    #        'First Login Date': DateTime.now
+    #    });
+    #
+    def set_once(distinct_id, properties, ip=nil, optional_params={})
+      properties = fix_property_dates(properties)
+      message = {
+          '$distinct_id' => distinct_id,
+          '$set_once' => properties,
+      }.merge(optional_params)
+
+      if ip
+        message['$ip'] = ip
+      end
+
+      update(message)
+    end
+
+    # Changes the value of properties by a numeric amount.  Takes a
+    # 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.
+    #
+    #    tracker = Mixpanel::Tracker.new
+    #    tracker.people.increment("12345", {
+    #        'Coins Spent' => 7,
+    #        'Coins Earned' => -7, # Use a negative number to subtract
+    #    });
+    #
+    def increment(distinct_id, properties, ip=nil, optional_params={})
+      properties = fix_property_dates(properties)
+      message = {
+          '$distinct_id' => distinct_id,
+          '$add' => properties,
+      }.merge(optional_params)
+
+      if ip
+        message['$ip'] = ip
+      end
+
+      update(message)
+    end
+
+    # Convenience method- increases the value of a numeric property
+    # by one. Calling #plus_one(distinct_id, property_name) is the same as calling
+    # #increment(distinct_id, {property_name => 1})
+    #
+    #    tracker = Mixpanel::Tracker.new
+    #    tracker.people.plus_one("12345", "Albums Released")
+    #
+    def plus_one(distinct_id, property_name, ip=nil, optional_params={})
+      increment(distinct_id, {property_name => 1}, ip, optional_params)
+    end
+
+    # Appends a values to the end of list-valued properties.
+    # If the given properties don't exist, a new list-valued
+    # property will be created.
+    #
+    #    tracker = Mixpanel::Tracker.new
+    #    tracker.people.append("12345", {
+    #        'Login Dates' => DateTime.now,
+    #        'Alter Ego Names' => 'Ziggy Stardust'
+    #    });
+    #
+    def append(distinct_id, properties, ip=nil, optional_params={})
+      properties = fix_property_dates(properties)
+      message = {
+          '$distinct_id' => distinct_id,
+          '$append' => properties,
+      }.merge(optional_params)
+
+      if ip
+        message['$ip'] = ip
+      end
+
+      update(message)
+    end
+
+    # 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
+    #    tracker.people.union("12345", {
+    #        'Levels Completed' => ['Suffragette City']
+    #    });
+    #
+    def union(distinct_id, properties, ip=nil, optional_params={})
+      properties = fix_property_dates(properties)
+      message = {
+          '$distinct_id' => distinct_id,
+          '$union' => properties,
+      }.merge(optional_params)
+
+      if ip
+        message['$ip'] = ip
+      end
+
+      update(message)
+    end
+
+    # Removes properties and their values from a profile.
+    #
+    #    tracker = Mixpanel::Tracker.new
+    #
+    #    # removes a single property and its value from a profile
+    #    tracker.people.unset("12345", "Overdue Since")
+    #
+    #    # removes multiple properties and their values from a profile
+    #    tracker.people.unset("12345", ["Overdue Since", "Paid Date"])
+    #
+    def unset(distinct_id, properties, ip=nil, optional_params={})
+      properties = [properties] unless properties.is_a?(Array)
+      message = {
+          '$distinct_id' => distinct_id,
+          '$unset' => properties
+      }.merge(optional_params)
+
+      if ip
+        message['$ip'] = ip
+      end
+
+      update(message)
+    end
+
+    # Records a payment to you to a profile. Charges recorded with
+    # #track_charge will appear in the \Mixpanel revenue report.
+    #
+    #    tracker = Mixpanel::Tracker.new
+    #
+    #    # records a charge of $25.32 from user 12345
+    #    tracker.people.track_charge("12345", 25.32)
+    #
+    #    # records a charge of $30.50 on the 2nd of January,
+    #    mixpanel.people.track_charge("12345", 30.50, {
+    #        '$time' => DateTime.parse("Jan 2 2013")
+    #    })
+    #
+    def track_charge(distinct_id, amount, properties={}, ip=nil, optional_params={})
+      properties = fix_property_dates(properties)
+      charge_properties = properties.merge({'$amount' => amount})
+      append(distinct_id, {'$transactions' => charge_properties}, ip, optional_params)
+    end
+
+    # Clear all charges from a \Mixpanel people profile
+    def clear_charges(distinct_id, ip=nil, optional_params={})
+      unset(distinct_id, '$transactions', ip, optional_params)
+    end
+
+    # Permanently delete a profile from \Mixpanel people analytics
+    def delete_user(distinct_id)
+      update({
+          '$distinct_id' => distinct_id,
+          '$delete' => ''
+      })
+    end
+
+    # 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
+    # https://mixpanel.com/help/reference/http
+    def update(message)
+      data = {
+        '$token' => @token,
+        '$time' =>  ((Time.now.to_f) * 1000.0).to_i
+      }.merge(message)
+
+      message = {
+        'data' => data
+      }
+
+      @sink.call(:profile_update, message.to_json)
+    end
+
+    private
+
+    def fix_property_dates(h)
+      h.inject({}) do |ret,(k,v)|
+        ret[k] = v.respond_to?(:strftime) ? v.strftime('%Y-%m-%dT%H:%M:%S') : v
+        ret
+      end
+    end
+  end
+end

data/lib/mixpanel-ruby/tracker.rb

@@ -0,0 +1,137 @@
+require 'mixpanel-ruby/events.rb'
+require 'mixpanel-ruby/people.rb'
+
+module Mixpanel
+  # 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})
+  #
+  # 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
+    # An instance of Mixpanel::People. Use this to
+    # send profile updates
+    attr_reader :people
+
+    # 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
+    def initialize(token, &block)
+      super(token, &block)
+      @token = token
+      @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'
+    #     })
+    #
+    # Optionallly, #track can be used to generate a pixel tracking url
+    # by setting "as_pixel" to true. In this case, a call to #track will not
+    # report the event, but instead return the string representation of a URL
+    # that will report the event when requested. For more information, see:
+    # https://mixpanel.com/docs/api-documentation/pixel-based-event-tracking
+
+    def track(distinct_id, event, properties={}, ip=nil, as_pixel=nil)
+      # This is here strictly to allow rdoc to include the relevant
+      # documentation
+      super
+    end
+
+    # 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
+    #
+    #     # Import event that user "12345"'s credit card was declined
+    #     tracker.import("12345", "Credit Card Declined", {
+    #       'time' => 1310111365
+    #     })
+    #
+    #     # Properties describe the circumstances of the event,
+    #     # or aspects of the source or user associated with the event
+    #     tracker.import("API_KEY", "12345", "Welcome Email Sent", {
+    #         'Email Template' => 'Pretty Pink Welcome',
+    #         'User Sign-up Cohort' => 'July 2013',
+    #         'time' => 1310111365
+    #     })
+    def import(api_key, 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.
+    #
+    # 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.
+    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
+      }
+
+      consumer.send(:event, message.to_json)
+    end
+  end
+end