preact 0.5.1 → 0.6.1

data/lib/preact.rb

@@ -7,6 +7,8 @@ require 'preact/objects/event'
 require 'preact/objects/action_event'
 require 'preact/objects/message'
 
+require 'logger'
+
 module Preact
 
   class << self
@@ -16,12 +18,17 @@ module Preact
     
     attr_accessor :default_client
 
+    attr_accessor :logger
+
     # Call this method to modify the configuration in your initializers
     def configure
       self.configuration ||= Configuration.new
 
       yield(configuration) if block_given?
       
+      # Configure logger.  Default to use Rails
+      self.logger = Logger.new(STDOUT) # ||= configuration.logger || (defined?(Rails) ? Rails.logger : Logger.new(STDOUT))
+
       raise StandardError.new "Must specify project code and secret when configuring the Preact api client" unless configuration.valid?
 
       if defined? Rails
@@ -29,25 +36,50 @@ module Preact
         configuration.disabled = true if Rails.env.test?
       end
     end
-    
-    def log_event(user, event_name, extras = {})
+
+    def log_event(user, event, account = nil)
       # Don't send requests when disabled
-      return if configuration.disabled?
-      return if user.nil?
+      if configuration.disabled?
+        logger.info "[Preact] Logging is disabled, not logging event"
+        return nil
+      elsif user.nil?
+        logger.error "[Preact] No person specified, not logging event"
+        return nil
+      elsif event.nil?
+        logger.error "[Preact] No event specified, not logging event"
+        return nil
+      end
  
       person = configuration.convert_to_person(user).as_json
-      event = ActionEvent.new({
-          :name => event_name,
-          :timestamp => Time.now.to_f
-        }.merge(extras)).as_json
 
-      send_log(person, event)
+      if event.is_a?(String)
+        preact_event = ActionEvent.new({
+            :name => event,
+            :timestamp => Time.now.to_f
+          }).as_json
+      elsif event.is_a?(Hash)
+        preact_event = ActionEvent.new(event)
+      elsif !event.is_a?(ActionEvent)
+        raise StandardError.new "Unknown event class, must pass a string event name, event hash or ActionEvent object"
+      end
+
+      if account
+        # attach the account info to the event
+        preact_event.account = configuration.convert_to_account(account).as_json
+      end
+      
+      send_log(person, preact_event)
     end
       
     def update_person(user)
       # Don't send requests when disabled
-      return if configuration.disabled?
-      return if user.nil?
+      if configuration.disabled?
+        logger.info "[Preact] Logging is disabled, not logging event"
+        return nil
+      elsif user.nil?
+        logger.info "[Preact] No person specified, not logging event"
+        return nil
+      end
       
       person = configuration.convert_to_person(user).as_json
 
@@ -58,10 +90,16 @@ module Preact
     #           :subject - subject of the message
     #           :body - body of the message
     #           * any additional keys are used as extra options for the message (:note, etc.)
+    # DEPRECATED - DO NOT USE
     def message(user, message = {})
       # Don't send requests when disabled
-      return if configuration.disabled?
-      return if user.nil?
+      if configuration.disabled?
+        logger.info "[Preact] Logging is disabled, not logging event"
+        return nil
+      elsif user.nil?
+        logger.info "[Preact] No person specified, not logging event"
+        return nil
+      end
       
       person = configuration.convert_to_person(user).as_json
       message_obj = Message.new(message).as_json

data/lib/preact/client.rb

@@ -1,14 +1,14 @@
 require 'multi_json'
 require 'rest_client'
 
-class Preact::Client
+module Preact
+  class Client
     
     def create_event(person, action_event)
     	params = {
         :person => person,
         :event => action_event
       }
-
       data = post_request("/events", params)
     end
 
@@ -25,7 +25,7 @@ class Preact::Client
     def post_request(method, params={})
       params = prepare_request_params(params)
       
-      puts "post_request to #{Preact.configuration.base_uri + method} with #{params.inspect}"
+      Preact.logger.debug "[Preact] post_request to #{Preact.configuration.base_uri + method} with #{params.inspect}"
       
       res = RestClient.post Preact.configuration.base_uri + method, params.to_json, :content_type => :json, :accept => :json
       data = MultiJson.decode(res.body)
@@ -33,18 +33,18 @@ class Preact::Client
 
     def get_request(method, params={})
       params = prepare_request_params(params)
-      
+
+      Preact.logger.debug "[Preact] get_request to #{Preact.configuration.base_uri + method} with #{params.inspect}"
+
       res = RestClient.get Preact.configuration.base_uri + method, { :params => params }
       data = MultiJson.decode(res.body)
     end
     
     def prepare_request_params(params = {})
       params.merge({
-        # :user => Preact.configuration.code,
-        # :password => Preact.configuration.secret,
         :format => "json"
       })
     end
     
-
+  end
 end

data/lib/preact/configuration.rb

@@ -10,11 +10,15 @@ module Preact
     # Default option settings
     attr_accessor :disabled
     attr_accessor :person_builder
+    attr_accessor :account_builder
+    
+    # Logger settings
+    attr_accessor :logger
     
     # The URL of the API server
-    attr_accessor :scheme
-    attr_accessor :host
-    attr_accessor :base_path
+    attr_reader :scheme
+    attr_reader :host
+    attr_reader :base_path
     
     def initialize
       @scheme = 'https'
@@ -54,18 +58,34 @@ module Preact
         else
           raise "person_builder must be callable"
         end
-      elsif user.respond_to?(:to_person)
-        Person.new(user.to_person)
+      elsif user.respond_to?(:to_preact)
+        Person.new(user.to_preact)
       elsif user.is_a? Hash
         Person.new(user)
       else
-        Person.new(default_user_to_person_hash(user))
+        Person.new(default_user_to_preact_hash(user))
+      end
+    end
+
+    def convert_to_account(account)
+      if account_builder
+        if account_builder.respond_to?(:call)
+          Account.new(account_builder.call(account))
+        else
+          raise "account_builder must be callable"
+        end
+      elsif account.respond_to?(:to_preact)
+        Account.new(account.to_preact)
+      elsif account.is_a? Hash
+        Account.new(account)
+      else
+        Account.new(default_account_to_preact_hash(account))
       end
     end
     
     private
     
-    def default_user_to_person_hash(user)
+    def default_user_to_preact_hash(user)
       {
         :name => user.name,
         :email => user.email,
@@ -76,5 +96,12 @@ module Preact
       }
     end
 
+    def default_account_to_preact_hash(account)
+      {
+        :id => account.id,
+        :name => (account.name if account.respond_to?(:name))
+      }
+    end
+
   end
 end

data/lib/preact/objects/account.rb

@@ -0,0 +1,12 @@
+class Preact::Account < Preact::ApiObject
+    
+  attr_accessor :id, :name
+    
+  def as_json(options={})
+    {
+      :name               => self.name,
+      :id                 => self.id
+    }
+  end
+    
+end

data/lib/preact/objects/event.rb

@@ -1,12 +1,12 @@
 class Preact::Event < Preact::ApiObject
   
-  attr_accessor :name, :magnitude, :timestamp
+  attr_accessor :name, :timestamp, :account
 
   def as_json(options={})
     {
       :name      => self.name,
-      :magnitude => self.magnitude,
       :timestamp => self.timestamp,
+      :account   => self.account,
       :source    => Preact.configuration.user_agent # version of this logging library
     }
   end

data/lib/preact/version.rb

@@ -1,3 +1,3 @@
 module Preact
-  VERSION = "0.5.1"
+  VERSION = "0.6.1"
 end

data/readme.md

@@ -25,14 +25,25 @@ Preact.configure do |config|
   # config.disabled = Rails.env.development?
   
   # Uncomment this this line to customize the data sent with your Person objects.
-  # Your procedure should return a Hash of attributes
+  # Your custom procedure should return a Hash of attributes
   # config.person_builder = lambda {|user| {:keys => :values}}
+  
+  # Defaults to Rails.logger or Logger.new(STDOUT). Set to Logger.new('/dev/null') to disable logging.
+  # config.logger = Logger.new('/dev/null')  
 end
 ```
 
 Usage
 ---
 
+The Preact.log_event method takes two required parameters and an optional third parameter.
+
+You must pass both a `person` and an `event`.
+
+The `person` parameter may be either a Hash or an ActiveRecord model (see below). 
+
+The `event` parameter may be either a String if you just are passing the event name, or it may be a Hash of the event object including other properties like `revenue`, `note` and a nested `extras` hash.
+
 ```ruby
 person = {
   :name => "Christopher Gooley",
@@ -49,10 +60,11 @@ person = {
 #common event examples:
 Preact.log_event(person, 'logged-in')
 Preact.log_event(person, 'upgraded')
-Preact.log_event(person, 'processed:payment', :revenue => 900) # revenue specified in cents
-Preact.log_event(person, "uploaded:file", :note => "awesome_resume.pdf")
+Preact.log_event(person, { :name => 'processed:payment', :revenue => 900 }) # revenue specified in cents
+Preact.log_event(person, { :name => 'uploaded:file', :note => "awesome_resume.pdf" })
 
-Preact.log_event(person, 'purchased:item', {
+Preact.log_event(person, {
+    :name => 'purchased:item',
     :note => "black shoes", 
     :revenue => 2500, 
     :extras => {
@@ -61,13 +73,23 @@ Preact.log_event(person, 'purchased:item', {
     })
 ```
 
+If you are a Preact B2B user, you should also log the `account` that this event occurred within. You can do that by passing a third parameter to Preact.log_event to specify the account information. The preferred method for `account` is to use the ActiveRecord integration outlined below.
+
+```ruby
+Preact.log_event(
+          { :email => "bob@honda.com", :name => "Bob Smith" }, # person
+          { :name => 'uploaded:file', :note => "awesome_resume.pdf" }, # event
+          { :id => 1234, :name => "Honda"} # account
+        )
+```
+
 ActiveRecord Integration
 ---
-In your `User` model, you can define a `to_person` method returning a Hash. Preact will detect and use this method on users passed to its logging events.
+In your `User` model, you can define a `to_preact` method returning a Hash. Preact will detect and use this method on users passed to its logging events.
 
 ```ruby
 class User < ActiveRecord::Base
-  def to_person
+  def to_preact
     {
       :name => self.name,
       :email => self.email,
@@ -83,8 +105,28 @@ end
 ```
 
 ```ruby
-Preact.log_event(User.find(1), 'restored_answer_data') 
-Preact.log_event(User.find(1), 'updated-profile', :extras => {:twitter => "@gooley"})
+Preact.log_event(@current_user, 'restored_answer_data') 
+Preact.log_event(@current_user, { :name => 'updated-profile', :extras => {:twitter => "@gooley"} })
+```
+
+Likewise, if you are a Preact B2B user, you can define the `to_preact` method on the model that defines your Account grouping. For instance, if you attach your Users into "Projects" you would add the `to_preact` method into your Project model.
+
+```ruby
+class Project < ActiveRecord::Base
+  def to_preact
+    {
+      :name => self.name,
+      :id => self.id
+    }
+  end
+end
+```
+
+Then, you just pass that model to the log_event method and we will associate the user's action with that account.
+
+```ruby
+Preact.log_event(@current_user, 'restored_answer_data', @current_user.project) 
+Preact.log_event(@current_user, { :name => 'updated-profile', :extras => {:twitter => "@gooley"} }, @current_user.project)
 ```
 
 Sidekiq Integration

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: preact
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.1
   prerelease: 
 platform: ruby
 authors:
@@ -118,6 +118,7 @@ extra_rdoc_files:
 files:
 - lib/preact/client.rb
 - lib/preact/configuration.rb
+- lib/preact/objects/account.rb
 - lib/preact/objects/action_event.rb
 - lib/preact/objects/api_object.rb
 - lib/preact/objects/event.rb