isc_analytics 0.5.4 → 0.6.0

data/README.md

@@ -2,7 +2,7 @@
 A simple client-side & server-side analytics library for Rails. It currently supports only KISSmetrics for more advanced
 analytics features (trackEvent / setProperties) and Google Analytics just for tracking pageviews.
 
-## Installation 
+## Installation
 
 Just add the `isc_analytics` gem into your Gemfile
 
@@ -18,20 +18,26 @@ ISC Analytics currently supports the following configuration options:
 
 
 ```ruby
-IscAnalytics.config.accounts = ANALYTIC_ACCOUNTS # an accounts object (preferably using ConfigReader)
-IscAnalytics.config.namespace = 'App' # an alias which will gain all the analytics behivour in the clientside.
+IscAnalytics.config.providers = ANALYTIC_PROVIDERS # a providers object (preferably using ConfigReader)
+IscAnalytics.config.namespace = 'App' # an alias which will gain all the analytics behaviour in the clientside.
 ```
 
-We highly recommend you to use our other gem [ConfigReader](https://github.com/TheGiftsProject/configreader) to load the analytics_accounts data from a YML.
+We highly recommend you to use our other gem
+[ConfigReader](https://github.com/TheGiftsProject/configreader) to load the analytics_providers data from YML.
 
-The accounts hash / EnvConfigReader should contain the following sub keys:
+The providers hash / EnvConfigReader should contain the following sub keys:
 
 ```yml
-kissmetrics_key: "KEY"
-google_analytics_key: "KEY"
-ipinfodb_key: "KEY"
-optimizely_key: "KEY"
-``` 
+kissmetrics:
+  key: "KEY"
+  dryrun: false # see http://support.kissmetrics.com/apis/ruby for more details
+google_analytics:
+  key: "KEY"
+ipinfodb:
+  key: "KEY"
+optimizely:
+  key: "KEY"
+```
 
 Currently only the KISSMetrics and Google Analytics keys are mandatory although the gem isn't fully tested without the ipinfodb and optimizely options.
 
@@ -84,11 +90,25 @@ For example if I set my namespace as `App` then I'll be able to access the track
 
 ## Server Side
 
-All the **client side event tracking is available from the server side** as well. Once you've included isc_analytics you can access the `analytics` object which will have methods identical to the client-side analytics methods.  
+All the **client side event tracking is available from the server side** as well. Once you've included isc_analytics you can access the `analytics` object which will have methods identical to the client-side analytics methods.
 For example you can call `analytics.trackEvent('user-visit')` and it will be persisted in the current user session and flushed into the user's browser next time he visits a page (via add_analytics). This mechanism is similar in behaviour to Rails' flash object.
- 
+
+There is also support for purely server-side analytics (currently only for KISSMetrics) that send the data directly to KM, without going through the user's browser.
+It is accessible through `IscAnalytics.server` with the following interface:
+```ruby
+IscAnalytics.server.track_event(identity, name, properties={})
+IscAnalytics.server.set_properties(identity, properties)
+IscAnalytics.server.alias(identity, new_identity)
+```
+
 ### Opt out
 
-One very cool feature **isc_analytics** has is a built in opt_out feature to be used when testing the system or when doing admin actions. 
-To enter opt_out for the current browsing session just call `analytics.opt_out!` from the controller.  
+One very cool feature **isc_analytics** has is a built in opt_out feature to be used when testing the system or when doing admin actions.
+To enter opt_out for the current browsing session just call `analytics.opt_out!` from the controller.
 Once opt-ted out, a dummy implementation of the analytics js will be sent to the client meaning that no calls will actually be sent to the analytics service.
+
+## Notes
+### KISSMetrics URL api
+After including IscAnalytics::ControllerSupport into your controller, you can override the [KISSMetrics URL api](http://support.kissmetrics.com/apis/url) by adding `before_filter keep_km_url_event` to your controller.
+This records the url events manually as soon as the request comes in and allows you to use `redirect_to` without worrying about losing analytics data.
+If you intend to use this, you should disable the URL api in your kissmetrics settings in order to avoid duplicate events.

data/lib/isc_analytics.rb

@@ -4,6 +4,7 @@ require "#{File.dirname(__FILE__)}/isc_analytics/client_api"
 require "#{File.dirname(__FILE__)}/isc_analytics/exceptions"
 require "#{File.dirname(__FILE__)}/isc_analytics/bootstrap"
 require "#{File.dirname(__FILE__)}/isc_analytics/controller_support"
+require "#{File.dirname(__FILE__)}/isc_analytics/server"
 
 module IscAnalytics
 
@@ -13,5 +14,9 @@ module IscAnalytics
     @configuration ||= IscAnalytics::Config.default
   end
 
+  def self.server
+    @server ||= IscAnalytics::Server.new(config.providers)
+  end
+
 end
 

data/lib/isc_analytics/bootstrap.rb

@@ -6,7 +6,7 @@ module IscAnalytics
     include KISSMetricsClientAPI
 
     def initialize(options = {})
-      validate_accounts_config
+      validate_providers_config
       @session = options[:session] || {}
       @opt_out = false
     end
@@ -23,35 +23,44 @@ module IscAnalytics
       Tags.scripts(analytics_scripts)
     end
 
+    def provider_script_tags
+      Tags.scripts(provider_scripts)
+    end
+
+    def queued_events
+      return nil if opt_out?
+      generate_queue_js
+    end
+
     private
 
     def analytics_scripts
       scripts = []
-      scripts.concat Services.scripts(config.accounts) unless opt_out?
+      scripts.concat provider_scripts
       scripts << isc_analytics_tag
       scripts << extend_analytics(config.namespace)
-      scripts << queued_events unless opt_out?
-      scripts
+      scripts << Tags.script_tag(queued_events) unless queued_events.blank?
+      scripts.compact
+    end
+
+    def provider_scripts
+      opt_out? ? [] : Services.scripts(config.providers)
     end
 
     def config
       IscAnalytics.config
     end
 
-    def validate_accounts_config
-      raise IscAnalytics::NoConfigSpecified.new('You have specified a nil config, you must specify an EnvConfigReader of your Analytics Accounts keys') if config.accounts.nil?
-
-      if config.accounts.kissmetrics_key.nil?
-        raise IscAnalytics::MissingConfigParams.new('KISSMetrics configuration key isn\'t specified in your config.')
-      elsif config.accounts.google_analytics_key.nil?
-        raise IscAnalytics::MissingConfigParams.new('Google Analytics configuration key isn\'t specified in your config.')
+    def validate_providers_config
+      if config.providers.nil?
+        raise IscAnalytics::NoConfigSpecified.new('You have specified a nil config, you must specify an EnvConfigReader of your Analytics providers keys')
       end
-    end
 
-    def queued_events
-      queue_js = generate_queue_js
-      return nil if queue_js.blank?
-      Tags.script_tag(queue_js)
+      if config.providers.kissmetrics.nil?
+        raise IscAnalytics::MissingConfigParams.new('KISSMetrics configuration isn\'t specified in your config.')
+      elsif config.providers.google_analytics.nil?
+        raise IscAnalytics::MissingConfigParams.new('Google Analytics configuration isn\'t specified in your config.')
+      end
     end
 
     def extend_analytics(namespace)
@@ -80,4 +89,4 @@ module IscAnalytics
     end
 
   end
-end
+end

data/lib/isc_analytics/client_api.rb

@@ -43,6 +43,22 @@ module IscAnalytics
       buffer
     end
 
+    def keep_km_url_event(params)
+      kme = params["kme"]
+
+      if kme
+        props = {}
+        params.each do |key, value|
+          if key.to_s.start_with?("km_")
+            prop_name = key[3..-1]
+            props[prop_name] = value
+          end
+        end
+
+        track_event(kme, props)
+      end
+    end
+
     private
 
     def enqueue(name, *args)
@@ -76,4 +92,4 @@ module IscAnalytics
     end
 
   end
-end
+end

data/lib/isc_analytics/config.rb

@@ -1,15 +1,15 @@
 module IscAnalytics
   class Config
 
-    attr_accessor :accounts, :namespace
+    attr_accessor :providers, :namespace
 
-    def self.default
-      new.instance_eval {
-        @accounts = nil
-        @namespace = nil
+    def initialize(providers, namespace, amd=false)
+      @providers = providers
+      @namespace = namespace
+    end
 
-        self
-      }
+    def self.default
+      new(nil, nil)
     end
   end
-end
+end

data/lib/isc_analytics/controller_support.rb

@@ -27,6 +27,10 @@ module IscAnalytics
       isc_analytics
     end
 
+    def keep_km_url_event
+      analytics.keep_km_url_event(params)
+    end
+
     private
 
     def isc_analytics

data/lib/isc_analytics/engine.rb

@@ -5,4 +5,4 @@ module IscAnalytics
       app.config.assets.precompile += %w(isc_analytics.js isc_analytics/session.js isc_analytics/opt_out_analytics.js)
     end
   end
-end
+end

data/lib/isc_analytics/mail/config/routes.rb

@@ -0,0 +1,3 @@
+IscAnalytics::Engine.routes.draw do
+  get "track_mail" => "mail_analytics_controller#track"
+end

data/lib/isc_analytics/mail/controllers/mail_analytics_controller.rb

@@ -0,0 +1,16 @@
+module IscAnalytics
+  class MailAnalyticsController < ActionController::Base
+    def track
+      strategy = IscAnalytics::Mail.strategy
+      begin
+        if strategy.should_record_analytics?(params)
+          strategy.track(params[:identity], params[:kme], params[:props])
+        end
+      rescue => e
+        strategy.on_failure(e)
+      ensure
+        redirect_to params[:url]
+      end
+    end
+  end
+end

data/lib/isc_analytics/mail/mail.rb

@@ -0,0 +1,7 @@
+module IscAnalytics
+  class Mail
+    def track_url(url, event, props)
+      track_mail_analytics_url(url: url, event: event, props: props)
+    end
+  end
+end

data/lib/isc_analytics/server.rb

@@ -0,0 +1,33 @@
+require "isc_analytics/server_apis/kissmetrics"
+
+module IscAnalytics
+  class Server
+    def initialize(providers_config)
+      @providers = []
+      @providers << init_kissmetrics(providers_config.kissmetrics)
+    end
+
+    def track_event(identity, name, properties={})
+      @providers.each do |provider|
+        provider.track_event(identity, name, properties)
+      end
+    end
+
+    def set_properties(identity, properties)
+      @providers.each do |provider|
+        provider.set_properties(identity, properties)
+      end
+    end
+
+    def alias(identity, new_identity)
+      @providers.each do |provider|
+        provider.alias(identity, new_identity)
+      end
+    end
+
+    private
+    def init_kissmetrics(config)
+      IscAnalytics::ServerApis::Kissmetrics.new(config["key"], config["dryrun"])
+    end
+  end
+end

data/lib/isc_analytics/server_apis/kissmetrics.rb

@@ -0,0 +1,33 @@
+require 'km'
+
+module IscAnalytics
+  module ServerApis
+    class Kissmetrics
+      def initialize(key, dryrun=false)
+        raise ArgumentError.new("IscAnalytics::ServerApis::Kissmetrics requires a key") if key.blank?
+        KM.init(key, { :dryrun => dryrun })
+      end
+
+      def track_event(identity, event_name, properties={})
+        identify(identity)
+        KM.record(event_name, properties)
+      end
+
+      def set_properties(identity, properties)
+        identify(identity)
+        KM.set(properties)
+      end
+
+      def alias(original_identity, alias_identity)
+        identify(original_identity)
+        KM.alias(original_identity, alias_identity)
+      end
+
+      private
+      def identify(identity)
+        raise ArgumentError.new("identity must be provided") if identity.blank?
+        KM.identify(identity)
+      end
+    end
+  end
+end

data/lib/isc_analytics/services.rb

@@ -4,13 +4,13 @@ require 'active_support/core_ext/object/blank'
 module IscAnalytics
   class Services
 
-    def self.scripts(accounts)
-      [
-          kissmetrics_tag(accounts.kissmetrics_key),
-          google_tag(accounts.google_analytics_key),
-          optimizely_tag(accounts.optimizely_key),
-          ipinfodb_tag(accounts.ipinfodb_key)
-      ]
+    def self.scripts(providers_config)
+      scripts = []
+      scripts << kissmetrics_tag(providers_config.kissmetrics["key"]) if providers_config.kissmetrics
+      scripts << google_tag(providers_config.google_analytics["key"]) if providers_config.google_analytics
+      scripts << optimizely_tag(providers_config.optimizely["key"]) if providers_config.optimizely
+      scripts << ipinfodb_tag(providers_config.ipinfodb["key"]) if providers_config.ipinfodb
+      scripts
     end
 
     def self.kissmetrics_tag(key)
@@ -57,4 +57,4 @@ module IscAnalytics
     end
 
   end
-end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: isc_analytics
 version: !ruby/object:Gem::Version
-  version: 0.5.4
+  version: 0.6.0
   prerelease: 
 platform: ruby
 authors:
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-01-01 00:00:00.000000000 Z
+date: 2013-02-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: controller_support
@@ -60,6 +60,22 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: km
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: A simple client-side & server-side analytics library
 email:
 - itayadler@gmail.com
@@ -68,26 +84,31 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- lib/assets/javascripts/isc_analytics/index.js.coffee
+- lib/assets/javascripts/isc_analytics.js
 - lib/assets/javascripts/isc_analytics/isc_analytics.js.coffee
-- lib/assets/javascripts/isc_analytics/opt_out_analytics.js.coffee
 - lib/assets/javascripts/isc_analytics/visitor_analytics.coffee.erb
-- lib/assets/javascripts/isc_analytics.js
-- lib/isc_analytics/bootstrap.rb
-- lib/isc_analytics/client_api.rb
+- lib/assets/javascripts/isc_analytics/opt_out_analytics.js.coffee
+- lib/assets/javascripts/isc_analytics/index.js.coffee
+- lib/isc_analytics.rb
 - lib/isc_analytics/config.rb
-- lib/isc_analytics/controller_support.rb
-- lib/isc_analytics/engine.rb
 - lib/isc_analytics/exceptions.rb
-- lib/isc_analytics/services.rb
 - lib/isc_analytics/tags.rb
-- lib/isc_analytics.rb
-- vendor/assets/javascripts/isc_analytics/session/index.js
-- vendor/assets/javascripts/isc_analytics/session/session-0.4.js
+- lib/isc_analytics/mail/config/routes.rb
+- lib/isc_analytics/mail/controllers/mail_analytics_controller.rb
+- lib/isc_analytics/mail/mail.rb
+- lib/isc_analytics/services.rb
+- lib/isc_analytics/bootstrap.rb
+- lib/isc_analytics/server.rb
+- lib/isc_analytics/server_apis/kissmetrics.rb
+- lib/isc_analytics/engine.rb
+- lib/isc_analytics/client_api.rb
+- lib/isc_analytics/controller_support.rb
 - vendor/assets/javascripts/isc_analytics/session.js
-- vendor/assets/javascripts/isc_analytics/yepnope/css_prefix.js
 - vendor/assets/javascripts/isc_analytics/yepnope/index.js
 - vendor/assets/javascripts/isc_analytics/yepnope/yepnope.js
+- vendor/assets/javascripts/isc_analytics/yepnope/css_prefix.js
+- vendor/assets/javascripts/isc_analytics/session/index.js
+- vendor/assets/javascripts/isc_analytics/session/session-0.4.js
 - Rakefile
 - Gemfile
 - README.md