greenfinch-ruby 0.1.0

data/lib/greenfinch-ruby/tracker.rb

@@ -0,0 +1,184 @@
+require 'greenfinch-ruby/events.rb'
+require 'greenfinch-ruby/people.rb'
+require 'greenfinch-ruby/groups.rb'
+
+module Greenfinch
+  # Use Greenfinch::Tracker to track events and profile updates in your application.
+  # To track an event, call
+  #
+  #     tracker = Greenfinch::Tracker.new(YOUR_GREENFINCH_TOKEN)
+  #     Greenfinch::Tracker.track(a_distinct_id, an_event_name, {properties})
+  #
+  # To send people updates, call
+  #
+  #     tracker = Greenfinch::Tracker.new(YOUR_GREENFINCH_TOKEN)
+  #     tracker.people.set(a_distinct_id, {properties})
+  #
+  # To send groups updates, call
+  #
+  #     tracker = Greenfinch::Tracker.new(YOUR_GREENFINCH_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 Greenfinch web application.
+  #
+  # Greenfinch::Tracker is a subclass of Greenfinch::Events, and exposes
+  # an instance of Greenfinch::People as Tracker#people
+  # and an instance of Greenfinch::Groups as Tracker#groups
+  class Tracker < Events
+    # An instance of Greenfinch::People. Use this to
+    # send profile updates
+    attr_reader :people
+
+    # An instance of Greenfinch::Groups. Use this to send groups updates
+    attr_reader :groups
+
+    # Takes your Greenfinch project token, as a string.
+    #
+    #    tracker = Greenfinch::Tracker.new(YOUR_GREENFINCH_TOKEN)
+    #
+    # By default, the tracker will send an message to Greenfinch
+    # synchronously with each call, using an instance of Greenfinch::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 Greenfinch)
+    #
+    #    tracker = Greenfinch::Tracker.new(YOUR_GREENFINCH_TOKEN) do |type, message|
+    #        @kestrel.set(MY_GREENFINCH_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 Greenfinch::Consumer#send!
+    # and Greenfinch::BufferedConsumer#send!
+    def initialize(token, service_name, debug, error_handler=nil, &block)
+      super(token, service_name, debug, error_handler, &block)
+      @token = token
+      @service_name = service_name
+      @debug = debug
+    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 = Greenfinch::Tracker.new(YOUR_GREENFINCH_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'
+    #     })
+    def track(distinct_id, event, properties={}, ip=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 = Greenfinch::Tracker.new(YOUR_GREENFINCH_TOKEN)
+    #
+    #     # Import event that user "12345"'s credit card was declined
+    #     tracker.import("API_KEY", "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 greenfinch 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 \Greenfinch service, regardless of how the tracker is configured.
+    # def alias(alias_id, real_id, events_endpoint=nil)
+    #   consumer = Greenfinch::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 GreenfinchError => e
+    #     @error_handler.handle(e)
+    #     ret = false
+    #   end
+    #
+    #   ret
+    # end
+
+    # 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://greenfinch.com/docs/api-documentation/pixel-based-event-tracking
+    #
+    #     tracker = Greenfinch::Tracker.new(YOUR_GREENFINCH_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.greenfinch.com/track/?data=[BASE_64_JSON_EVENT]&ip=1&img=1'
+    # def generate_tracking_url(distinct_id, event, properties={}, endpoint=nil)
+    #   properties = {
+    #     'distinct_id' => distinct_id,
+    #     'token' => @token,
+    #     'time' => Time.now.to_i,
+    #     'mp_lib' => 'ruby',
+    #     '$lib_version' => Greenfinch::VERSION,
+    #   }.merge(properties)
+    #
+    #   raw_data = {
+    #     'event' => event,
+    #     'properties' => properties,
+    #   }
+    #
+    #   endpoint = endpoint || 'https://api.greenfinch.com/track/'
+    #   data = Base64.urlsafe_encode64(raw_data.to_json)
+    #
+    #   "#{endpoint}?data=#{data}&ip=1&img=1"
+    # end
+  end
+end

data/lib/greenfinch-ruby/version.rb

@@ -0,0 +1,3 @@
+module Greenfinch
+  VERSION = '0.1.0'
+end

data/spec/mixpanel-ruby/consumer_spec.rb

@@ -0,0 +1,208 @@
+require 'base64'
+require 'spec_helper'
+require 'webmock'
+
+require 'mixpanel-ruby/consumer'
+
+describe Mixpanel::Consumer do
+  before { WebMock.reset! }
+
+  shared_examples_for 'consumer' do
+    it 'should send a request to api.mixpanel.com/track on events' do
+      stub_request(:any, 'https://api.mixpanel.com/track').to_return({:body => '{"status": 1, "error": null}'})
+      subject.send!(:event, {'data' => 'TEST EVENT MESSAGE'}.to_json)
+      expect(WebMock).to have_requested(:post, 'https://api.mixpanel.com/track').
+        with(:body => {'data' => 'IlRFU1QgRVZFTlQgTUVTU0FHRSI=', 'verbose' => '1' })
+    end
+
+    it 'should send a request to api.mixpanel.com/people on profile updates' do
+      stub_request(:any, 'https://api.mixpanel.com/engage').to_return({:body => '{"status": 1, "error": null}'})
+      subject.send!(:profile_update, {'data' => 'TEST EVENT MESSAGE'}.to_json)
+      expect(WebMock).to have_requested(:post, 'https://api.mixpanel.com/engage').
+        with(:body => {'data' => 'IlRFU1QgRVZFTlQgTUVTU0FHRSI=', 'verbose' => '1' })
+    end
+
+    it 'should send a request to api.mixpanel.com/groups on groups updates' do
+      stub_request(:any, 'https://api.mixpanel.com/groups').to_return({:body => '{"status": 1, "error": null}'})
+      subject.send!(:group_update, {'data' => 'TEST EVENT MESSAGE'}.to_json)
+      expect(WebMock).to have_requested(:post, 'https://api.mixpanel.com/groups').
+        with(:body => {'data' => 'IlRFU1QgRVZFTlQgTUVTU0FHRSI=', 'verbose' => '1' })
+    end
+
+    it 'should send a request to api.mixpanel.com/import on event imports' do
+      stub_request(:any, 'https://api.mixpanel.com/import').to_return({:body => '{"status": 1, "error": null}'})
+      subject.send!(:import, {'data' => 'TEST EVENT MESSAGE', 'api_key' => 'API_KEY','verbose' => '1' }.to_json)
+      expect(WebMock).to have_requested(:post, 'https://api.mixpanel.com/import').
+        with(:body => {'data' => 'IlRFU1QgRVZFTlQgTUVTU0FHRSI=', 'api_key' => 'API_KEY', 'verbose' => '1' })
+    end
+
+    it 'should encode long messages without newlines' do
+      stub_request(:any, 'https://api.mixpanel.com/track').to_return({:body => '{"status": 1, "error": null}'})
+      subject.send!(:event, {'data' => 'BASE64-ENCODED VERSION OF BIN. THIS METHOD COMPLIES WITH RFC 2045. LINE FEEDS ARE ADDED TO EVERY 60 ENCODED CHARACTORS. IN RUBY 1.8 WE NEED TO JUST CALL ENCODE64 AND REMOVE THE LINE FEEDS, IN RUBY 1.9 WE CALL STRIC_ENCODED64 METHOD INSTEAD'}.to_json)
+      expect(WebMock).to have_requested(:post, 'https://api.mixpanel.com/track').
+        with(:body => {'data' => 'IkJBU0U2NC1FTkNPREVEIFZFUlNJT04gT0YgQklOLiBUSElTIE1FVEhPRCBDT01QTElFUyBXSVRIIFJGQyAyMDQ1LiBMSU5FIEZFRURTIEFSRSBBRERFRCBUTyBFVkVSWSA2MCBFTkNPREVEIENIQVJBQ1RPUlMuIElOIFJVQlkgMS44IFdFIE5FRUQgVE8gSlVTVCBDQUxMIEVOQ09ERTY0IEFORCBSRU1PVkUgVEhFIExJTkUgRkVFRFMsIElOIFJVQlkgMS45IFdFIENBTEwgU1RSSUNfRU5DT0RFRDY0IE1FVEhPRCBJTlNURUFEIg==', 'verbose' => '1'})
+    end
+
+    it 'should provide thorough information in case mixpanel fails' do
+      stub_request(:any, 'https://api.mixpanel.com/track').to_return({:status => 401, :body => "nutcakes"})
+      expect { subject.send!(:event, {'data' => 'TEST EVENT MESSAGE'}.to_json) }.to raise_exception('Could not write to Mixpanel, server responded with 401 returning: \'nutcakes\'')
+    end
+
+    it 'should still respond to send' do
+      stub_request(:any, 'https://api.mixpanel.com/track').to_return({:body => '{"status": 1, "error": null}'})
+      subject.send(:event, {'data' => 'TEST EVENT MESSAGE'}.to_json)
+      expect(WebMock).to have_requested(:post, 'https://api.mixpanel.com/track').
+        with(:body => {'data' => 'IlRFU1QgRVZFTlQgTUVTU0FHRSI=', 'verbose' => '1' })
+    end
+
+    it 'should raise server error if response body is empty' do
+      stub_request(:any, 'https://api.mixpanel.com/track').to_return({:body => ''})
+      expect { subject.send!(:event, {'data' => 'TEST EVENT MESSAGE'}.to_json) }.to raise_exception(Mixpanel::ServerError, /Could not interpret Mixpanel server response: ''/)
+      expect(WebMock).to have_requested(:post, 'https://api.mixpanel.com/track').
+        with(:body => {'data' => 'IlRFU1QgRVZFTlQgTUVTU0FHRSI=', 'verbose' => '1' })
+    end
+
+    it 'should raise server error when verbose is disabled', :skip => true do
+      stub_request(:any, 'https://api.mixpanel.com/track').to_return({:body => '0'})
+      expect { subject.send!(:event, {'data' => 'TEST EVENT MESSAGE'}.to_json) }.to raise_exception(Mixpanel::ServerError, /Could not interpret Mixpanel server response: '0'/)
+      expect(WebMock).to have_requested(:post, 'https://api.mixpanel.com/track').
+        with(:body => {'data' => 'IlRFU1QgRVZFTlQgTUVTU0FHRSI=', 'verbose' => '1' })
+    end
+  end
+
+  context 'raw consumer' do
+    it_behaves_like 'consumer'
+  end
+
+  context 'custom request consumer' do
+    subject do
+      ret = Mixpanel::Consumer.new
+      class << ret
+        attr_reader :called
+        def request(*args)
+          @called = true
+          super(*args)
+        end
+      end
+
+      ret
+    end
+
+    after(:each) do
+      expect(subject.called).to be_truthy
+    end
+
+    it_behaves_like 'consumer'
+  end
+
+end
+
+describe Mixpanel::BufferedConsumer do
+  let(:max_length) { 10 }
+  before { WebMock.reset! }
+
+  context 'Default BufferedConsumer' do
+    subject { Mixpanel::BufferedConsumer.new(nil, nil, nil, max_length) }
+
+    it 'should not send a request for a single message until flush is called' do
+      stub_request(:any, 'https://api.mixpanel.com/track').to_return({:body => '{"status": 1, "error": null}'})
+      subject.send!(:event, {'data' => 'TEST EVENT 1'}.to_json)
+      expect(WebMock).to have_not_requested(:post, 'https://api.mixpanel.com/track')
+
+      subject.flush()
+      expect(WebMock).to have_requested(:post, 'https://api.mixpanel.com/track').
+        with(:body => {'data' => 'WyJURVNUIEVWRU5UIDEiXQ==', 'verbose' => '1' })
+    end
+
+    it 'should still respond to send' do
+      stub_request(:any, 'https://api.mixpanel.com/track').to_return({:body => '{"status": 1, "error": null}'})
+      subject.send(:event, {'data' => 'TEST EVENT 1'}.to_json)
+      expect(WebMock).to have_not_requested(:post, 'https://api.mixpanel.com/track')
+    end
+
+    it 'should send one message when max_length events are tracked' do
+      stub_request(:any, 'https://api.mixpanel.com/track').to_return({:body => '{"status": 1, "error": null}'})
+
+      max_length.times do |i|
+        subject.send!(:event, {'data' => "x #{i}"}.to_json)
+      end
+
+      expect(WebMock).to have_requested(:post, 'https://api.mixpanel.com/track').
+        with(:body => {'data' => 'WyJ4IDAiLCJ4IDEiLCJ4IDIiLCJ4IDMiLCJ4IDQiLCJ4IDUiLCJ4IDYiLCJ4IDciLCJ4IDgiLCJ4IDkiXQ==', 'verbose' => '1' })
+    end
+
+    it 'should send one message per api key on import' do
+      stub_request(:any, 'https://api.mixpanel.com/import').to_return({:body => '{"status": 1, "error": null}'})
+      subject.send!(:import, {'data' => 'TEST EVENT 1', 'api_key' => 'KEY 1'}.to_json)
+      subject.send!(:import, {'data' => 'TEST EVENT 1', 'api_key' => 'KEY 2'}.to_json)
+      subject.send!(:import, {'data' => 'TEST EVENT 2', 'api_key' => 'KEY 1'}.to_json)
+      subject.send!(:import, {'data' => 'TEST EVENT 2', 'api_key' => 'KEY 2'}.to_json)
+      subject.flush
+
+      expect(WebMock).to have_requested(:post, 'https://api.mixpanel.com/import').
+        with(:body => {'data' => 'IlRFU1QgRVZFTlQgMSI=', 'api_key' => 'KEY 1', 'verbose' => '1' })
+
+      expect(WebMock).to have_requested(:post, 'https://api.mixpanel.com/import').
+        with(:body => {'data' => 'IlRFU1QgRVZFTlQgMSI=', 'api_key' => 'KEY 2', 'verbose' => '1' })
+    end
+  end
+
+  context 'BufferedConsumer with block' do
+    let(:messages_seen) { [] }
+    subject do
+      Mixpanel::BufferedConsumer.new(nil, nil, nil, 3) do |type, message|
+        messages_seen << [type, message]
+      end
+    end
+
+    it 'should call block instead of making default requests on flush' do
+      3.times do |i|
+        subject.send!(:event, {'data' => "x #{i}"}.to_json)
+      end
+
+      expect(messages_seen).to match_array(
+        [[:event, "{\"data\":[\"x 0\",\"x 1\",\"x 2\"]}"]]
+      )
+    end
+
+  end
+
+  context 'with failing requests' do
+    let(:sent_messages) { [] }
+    let(:submission_queue) { [] }
+    subject do
+      Mixpanel::BufferedConsumer.new(nil, nil, nil, 2) do |type, message|
+        raise Mixpanel::ServerError if submission_queue.shift == :fail
+        sent_messages << [type, message]
+      end
+    end
+
+    it 'clears any slices that complete on flush' do
+      # construct a consumer that is backed up and has a multi-slice buffer
+      3.times { submission_queue << :fail }
+      4.times do |i|
+        begin
+          subject.send!(:event, {'data' => i}.to_json)
+        rescue Mixpanel::ServerError
+        end
+      end
+      expect(sent_messages).to match_array([])
+
+      submission_queue << :pass
+      submission_queue << :fail
+
+      expect { subject.flush }.to raise_error Mixpanel::ServerError
+      expect(sent_messages).to match_array([
+        [:event, '{"data":[0,1]}']
+      ])
+
+      submission_queue << :pass
+      subject.flush
+      expect(sent_messages).to match_array([
+        [:event, '{"data":[0,1]}'],
+        [:event, '{"data":[2,3]}'],
+      ])
+    end
+  end
+
+end

data/spec/mixpanel-ruby/error_spec.rb

@@ -0,0 +1,76 @@
+require 'spec_helper'
+
+require 'mixpanel-ruby/error.rb'
+require 'mixpanel-ruby/events.rb'
+
+class TestErrorHandler < Mixpanel::ErrorHandler
+  def initialize(log)
+    @log = log
+  end
+
+  def handle(error)
+    @log << error.to_s
+  end
+end
+
+describe Mixpanel::ErrorHandler do
+  it "should respond to #handle`" do
+    error_handler = Mixpanel::ErrorHandler.new
+    expect(error_handler.respond_to?(:handle)).to be true
+  end
+
+  context 'without a customer error_handler' do
+
+    before(:each) do
+      @tracker = Mixpanel::Tracker.new('TEST TOKEN') do |type, message|
+        raise Mixpanel::MixpanelError
+      end
+    end
+
+    it "should silence errors in track calls" do
+      expect {
+        expect(@tracker.track('TEST ID', 'Test Event')).to be false
+      }.to_not raise_error
+    end
+
+    it "should handle errors in import calls" do
+      expect {
+        expect(@tracker.import('TEST API KEY', 'TEST DISTINCT_ID', 'Test Event')).to be false
+      }.to_not raise_error
+    end
+
+    it "should handle errors in people calls" do
+      expect {
+        expect(@tracker.people.set('TEST ID', {})).to be false
+      }.to_not raise_error
+    end
+
+  end
+
+  context 'with a custom error_handler' do
+
+    before(:each) do
+      @log = []
+      @error_handler = TestErrorHandler.new(@log)
+      @tracker = Mixpanel::Tracker.new('TEST TOKEN', @error_handler) do |type, message|
+        raise Mixpanel::MixpanelError
+      end
+    end
+
+    it "should handle errors in track calls" do
+      @tracker.track('TEST ID', 'Test Event', {})
+      expect(@log).to eq(['Mixpanel::MixpanelError'])
+    end
+
+    it "should handle errors in import calls" do
+      @tracker.import('TEST API KEY', 'TEST DISTINCT_ID', 'Test Event')
+      expect(@log).to eq(['Mixpanel::MixpanelError'])
+    end
+
+    it "should handle errors in people calls" do
+      @tracker.people.set('TEST ID', {})
+      expect(@log).to eq(['Mixpanel::MixpanelError'])
+    end
+
+  end
+end