greenfinch-ruby 0.1.0

data/lib/greenfinch-ruby/events.rb

@@ -0,0 +1,140 @@
+require 'time'
+
+require 'greenfinch-ruby/consumer'
+require 'greenfinch-ruby/error'
+
+module Greenfinch
+
+  # Handles formatting Greenfinch event tracking messages
+  # and sending them to the consumer. Greenfinch::Tracker
+  # is a subclass of this class, and the best way to
+  # track events is to instantiate a Greenfinch::Tracker
+  #
+  #     tracker = Greenfinch::Tracker.new(YOUR_GREENFINCH_TOKEN) # Has all of the methods of Greenfinch::Event
+  #     tracker.track(...)
+  #
+  class Events
+
+    # You likely won't need to instantiate an instance of
+    # Greenfinch::Events directly. The best way to get an instance
+    # is to use Greenfinch::Tracker
+    #
+    #     # tracker has all of the methods of Greenfinch::Events
+    #     tracker = Greenfinch::Tracker.new(YOUR_GREENFINCH_TOKEN)
+    #
+    def initialize(token, service_name, debug, error_handler=nil, &block)
+      @token = token
+      @service_name = service_name
+      @debug = debug
+      @error_handler = error_handler || ErrorHandler.new
+
+      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 = 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)
+      properties = {
+        'user_id' => distinct_id,
+        'time' => Time.now.to_i,
+        'mp_lib' => 'ruby',
+        '$lib_version' => Greenfinch::VERSION,
+      }.merge(properties)
+      properties['ip'] = ip if ip
+
+      data = {
+        'event' => event,
+        'prop' => properties,
+      }
+
+      message = {
+        'data' => data,
+        'jwt_token' => @token,
+        'service_name' => @service_name,
+        'debug' => @debug
+      }
+
+      ret = true
+
+      begin
+        @sink.call(:event, message.to_json)
+      rescue GreenfinchError => e
+        @error_handler.handle(e)
+        ret = false
+      end
+
+      ret
+    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.  By default,
+    # we pass the time of the method call as the time the event occured, if you
+    # wish to override this pass a timestamp in the properties hash.
+    #
+    #     tracker = Greenfinch::Tracker.new(YOUR_GREENFINCH_TOKEN)
+    #
+    #     # 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',
+    #         'time' => 1369353600,
+    #     })
+    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' => Greenfinch::VERSION,
+      }.merge(properties)
+      properties['ip'] = ip if ip
+
+      data = {
+        'event' => event,
+        'properties' => properties,
+      }
+
+      message = {
+        'data' => data,
+        'api_key' => api_key,
+      }
+
+      ret = true
+      begin
+        @sink.call(:import, message.to_json)
+      rescue GreenfinchError => e
+        @error_handler.handle(e)
+        ret = false
+      end
+
+      ret
+    end
+  end
+end

data/lib/greenfinch-ruby/groups.rb

@@ -0,0 +1,201 @@
+require 'date'
+require 'json'
+require 'time'
+
+require 'greenfinch-ruby/consumer'
+require 'greenfinch-ruby/error'
+
+module Greenfinch
+
+  # Handles formatting Greenfinch group updates and
+  # sending them to the consumer. You will rarely need
+  # to instantiate this class directly- to send
+  # group updates, use Greenfinch::Tracker#groups
+  #
+  #     tracker = Greenfinch::Tracker.new(YOUR_GREENFINCH_TOKEN)
+  #     tracker.groups.set(...) or .set_once(..), or .delete(...) etc.
+  class Groups
+
+    # You likely won't need to instantiate instances of Greenfinch::Groups
+    # directly. The best way to get an instance of Greenfinch::Groups is
+    #
+    #     tracker = Greenfinch::Tracker.new(YOUR_GREENFINCH_TOKEN)
+    #     tracker.groups # An instance of Greenfinch::Groups
+    #
+    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
+
+    # Sets properties on a group record. Takes a Hash with string
+    # keys, and values that are strings, numbers, booleans, or
+    # DateTimes
+    #
+    #    tracker = Greenfinch::Tracker.new(YOUR_GREENFINCH_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, \Greenfinch will use that
+    # ip address for geolocation (rather than the ip of your server)
+    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 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 = Greenfinch::Tracker.new(YOUR_GREENFINCH_TOKEN)
+    #    tracker.groups.set_once("GROUP KEY", "1234", {
+    #        'First Login Date': DateTime.now
+    #    });
+    #
+    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
+
+    # Removes a specific value in a list property
+    #
+    #    tracker = Greenfinch::Tracker.new(YOUR_GREENFINCH_TOKEN)
+    #
+    #    # removes "socks" from the "Items purchased" list property
+    #    # for the specified group
+    #    tracker.groups.remove("GROUP KEY", "1234", { 'Items purchased' => 'socks' })
+    #
+    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 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 = Greenfinch::Tracker.new(YOUR_GREENFINCH_TOKEN)
+    #    tracker.groups.union("GROUP KEY", "1234", {
+    #        'Levels Completed' => ['Suffragette City']
+    #    });
+    #
+    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
+
+    # Removes properties and their values from a group.
+    #
+    #    tracker = Greenfinch::Tracker.new(YOUR_GREENFINCH_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"])
+    #
+    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
+
+    # Permanently delete a group from \Greenfinch groups analytics (all group
+    # properties on events stay)
+    def delete_group(group_key, group_id, optional_params={})
+      update({
+        '$group_key' => group_key,
+        '$group_id' => group_id,
+        '$delete' => '',
+      }.merge(optional_params))
+    end
+
+    # Send a generic update to \Greenfinch groups analytics.
+    # Caller is responsible for formatting the update message, as
+    # documented in the \Greenfinch 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 \Greenfinch HTTP tracking API is documented at
+    # https://greenfinch.com/help/reference/http
+    def update(message)
+      data = {
+        '$token' => @token,
+        '$time' =>  ((Time.now.to_f) * 1000.0).to_i,
+      }.merge(message)
+
+      message = {'data' => data}
+
+      ret = true
+      begin
+        @sink.call(:group_update, message.to_json)
+      rescue GreenfinchError => e
+        @error_handler.handle(e)
+        ret = false
+      end
+
+      ret
+    end
+
+    private
+
+    def fix_property_dates(properties)
+      properties.inject({}) do |ret, (key, value)|
+        value = value.respond_to?(:new_offset) ? value.new_offset('0') : value
+        value = value.respond_to?(:utc) ? value.utc : value  # Handle ActiveSupport::TimeWithZone
+
+        ret[key] = value.respond_to?(:strftime) ? value.strftime('%Y-%m-%dT%H:%M:%S') : value
+        ret
+      end
+    end
+  end
+end

data/lib/greenfinch-ruby/people.rb

@@ -0,0 +1,254 @@
+require 'date'
+require 'json'
+require 'time'
+
+require 'greenfinch-ruby/consumer'
+require 'greenfinch-ruby/error'
+
+module Greenfinch
+
+  # Handles formatting Greenfinch profile updates and
+  # sending them to the consumer. You will rarely need
+  # to instantiate this class directly- to send
+  # profile updates, use Greenfinch::Tracker#people
+  #
+  #     tracker = Greenfinch::Tracker.new(YOUR_GREENFINCH_TOKEN)
+  #     tracker.people.set(...) # Or .append(..), or track_charge(...) etc.
+  class People
+
+    # You likely won't need to instantiate instances of Greenfinch::People
+    # directly. The best way to get an instance of Greenfinch::People is
+    #
+    #     tracker = Greenfinch::Tracker.new(YOUR_GREENFINCH_TOKEN)
+    #     tracker.people # An instance of Greenfinch::People
+    #
+    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
+
+    # Sets properties on a user record. Takes a Hash with string
+    # keys, and values that are strings, numbers, booleans, or
+    # DateTimes
+    #
+    #    tracker = Greenfinch::Tracker.new(YOUR_GREENFINCH_TOKEN)
+    #    # 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, \Greenfinch 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)
+      message['$ip'] = ip if ip
+
+      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 = Greenfinch::Tracker.new(YOUR_GREENFINCH_TOKEN)
+    #    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)
+      message['$ip'] = ip if ip
+
+      update(message)
+    end
+
+    # Changes the value of properties by a numeric amount.  Takes a
+    # hash with string keys and numeric properties. \Greenfinch 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 = Greenfinch::Tracker.new(YOUR_GREENFINCH_TOKEN)
+    #    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)
+      message['$ip'] = ip if ip
+
+      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 = Greenfinch::Tracker.new(YOUR_GREENFINCH_TOKEN)
+    #    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 = Greenfinch::Tracker.new(YOUR_GREENFINCH_TOKEN)
+    #    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)
+      message['$ip'] = ip if ip
+
+      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 = Greenfinch::Tracker.new(YOUR_GREENFINCH_TOKEN)
+    #    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)
+      message['$ip'] = ip if ip
+
+      update(message)
+    end
+
+    # Removes properties and their values from a profile.
+    #
+    #    tracker = Greenfinch::Tracker.new(YOUR_GREENFINCH_TOKEN)
+    #
+    #    # 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)
+      message['$ip'] = ip if ip
+
+      update(message)
+    end
+
+    # Records a payment to you to a profile. Charges recorded with
+    # #track_charge will appear in the \Greenfinch revenue report.
+    #
+    #    tracker = Greenfinch::Tracker.new(YOUR_GREENFINCH_TOKEN)
+    #
+    #    # 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,
+    #    greenfinch.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 \Greenfinch people profile
+    def clear_charges(distinct_id, ip=nil, optional_params={})
+      unset(distinct_id, '$transactions', ip, optional_params)
+    end
+
+    # Permanently delete a profile from \Greenfinch people analytics
+    # To delete a user and ignore alias pass into optional params
+    #   {"$ignore_alias"=>true}
+    def delete_user(distinct_id, optional_params={})
+      update({
+        '$distinct_id' => distinct_id,
+        '$delete' => '',
+      }.merge(optional_params))
+    end
+
+    # Send a generic update to \Greenfinch people analytics.
+    # Caller is responsible for formatting the update message, as
+    # documented in the \Greenfinch 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 \Greenfinch HTTP tracking API is documented at
+    # https://greenfinch.com/help/reference/http
+    def update(message)
+      data = {
+        '$token' => @token,
+        '$time' =>  ((Time.now.to_f) * 1000.0).to_i,
+      }.merge(message)
+
+      message = {'data' => data}
+
+      ret = true
+      begin
+        @sink.call(:profile_update, message.to_json)
+      rescue GreenfinchError => e
+        @error_handler.handle(e)
+        ret = false
+      end
+
+      ret
+    end
+
+    private
+
+    def fix_property_dates(properties)
+      properties.inject({}) do |ret, (key, value)|
+        value = value.respond_to?(:new_offset) ? value.new_offset('0') : value
+        value = value.respond_to?(:utc) ? value.utc : value  # Handle ActiveSupport::TimeWithZone
+
+        ret[key] = value.respond_to?(:strftime) ? value.strftime('%Y-%m-%dT%H:%M:%S') : value
+        ret
+      end
+    end
+  end
+end