isc_analytics 0.5

data/Gemfile

@@ -0,0 +1,10 @@
+source "http://rubygems.org"
+
+gemspec
+
+group :test, :development do
+  gem "rspec-rails"
+  gem "sqlite3"
+  #gem "capybara"
+  #gem 'ruby-debug19'
+end

data/README.md

@@ -0,0 +1,84 @@
+# ISC Analytics
+A simple client-side & server-side analytics library for Rails
+
+## Installation 
+
+Just add the `isc_analytics` gem into your Gemfile
+
+```ruby
+gem 'isc_analytics'
+```
+
+Then create an initializer file in your `config/initialize` directory containing the initial config of your analytics.
+
+## Configuration
+
+ISC Analytics current supports the following configurations:
+
+
+```ruby
+IscAnalytics.config.accounts = ANALYTIC_ACCOUNTS # an accounts objects (preferably using ConfigReader)
+IscAnalytics.config.namespace = 'App' # an alias which will gain all the analytics behivour in the clientside.
+```
+
+We recommend our other gem [ConfigReader](https://github.com/TheGiftsProject/configreader) to load the analytics_accounts data from a YML.
+
+The analytics accounts should contain the following sub keys:
+
+```yml
+kissmetrics_key: "KEY"
+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.
+
+## Usage
+
+There are three points of usage for the isc_analytics gem, the first is including and starting to use the gem in your app. The second is Client side analytics events and the third is server side analytics events.
+
+### Including
+
+To include isc_analytics in your app, after you install the gem.
+Add the following line inside your ApplicationController:
+
+```ruby
+include IscAnalytics::ControllerSupport
+```
+This will enable you to use the analytics object from your controllers and views.
+
+And the following line to your main application layout
+
+```erb
+<%= add_analytics %>
+```
+
+This will embed all the needed html for the analytics to run (including the code for all the required services.)
+
+### Client Side
+
+After your install and include the isc_gem you can use the following functions in your client side javascript.
+
+```js
+Analytics.trackEvent(<event name>, [<properties_hash>]);
+Analytics.setProperty(<property_key>, <property_value>);
+Analytics.setProperties(<properties_hash>);
+Analytics.identify(<identity>, [<properties_hash>]);
+Analytics.clearIdentity()
+```
+
+#### Namespacing
+The cool thing is that if you configure a Namespace in the configuration then we'll automatically alias all the functions to the Namespace of your choice for easy access.
+For example if I set my namespace as `App` then I'll be able to access the trackEvent function from `App.trackEvent`
+
+### Server Side
+
+All the **client side event tracking is available from the server side** as well. Once you inlcude 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 users browser next time he visits a page (via add_analytics). This mechanism is similar in behaivour to Rails' flash object.
+ 
+### 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.  
+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.

data/Rakefile

@@ -0,0 +1,16 @@
+# encoding: UTF-8
+require 'rubygems'
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rake'
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/lib/assets/javascripts/isc_analytics/index.js.coffee

@@ -0,0 +1,2 @@
+#= require ./isc_analytics
+#= require ./visitor_analytics

data/lib/assets/javascripts/isc_analytics/isc_analytics.js.coffee

@@ -0,0 +1,77 @@
+class window.Analytics
+
+# check if the Kissmetrics async queue is loaded
+  @isLoaded: ->
+    window._kmq?
+
+  ###
+  Push a call asynchronously to Kissmetrics API
+  @param callData - array to push
+  ###
+  @push: (callData) ->
+    if _.isArray(callData) and @isLoaded()
+      _kmq.push callData
+
+  ###
+  Track Event
+  @param eventName - event name string
+  @param properties - JSON with custom data
+  ###
+  @trackEvent: (eventName, properties) ->
+    if @isValid eventName
+      properties = properties or {}
+      @push ["record", eventName, properties]
+
+  ###
+  Set properties
+  @param properties - JSON with custom data
+  ###
+  @setProperties: (properties) ->
+    unless _.isEmpty(properties)
+      @push ["set", properties]
+
+
+  ###
+  Set a single property
+  @param property
+  @param value
+  ###
+  @setProperty: (property, value) ->
+    if @isValid property
+      properties = {}
+      properties[property] = value
+      @setProperties properties
+
+
+  ###
+  Identify a user with a unique id
+  @param identifier - could be either username or email (currently email)
+  @param properties - JSON with custom data
+  ###
+  @identify: (identifier, properties) ->
+    if @isValid identifier
+      @push ["identify", identifier]
+      @setProperties(properties)
+
+
+  ###
+  Clear the user's identity
+  @see http://support.kissmetrics.com/advanced/identity-management
+  ###
+  @clearIdentity: ->
+    @push ["clearIdentity"]
+
+
+  ###
+  alias simply takes two arguments which are the two identities that you need
+  to tie together. So if you call alias with the identities bob and bob@bob.com
+  KISSmetrics will tie together the two records and will treat the identities bob
+  and bob@bob.com as the same person.
+  @param name
+  ###
+  @setAlias: (name, identifier) ->
+    if @isValid(identifier) and @isValid(name)
+      @push ["alias", name, identifier]
+
+  @isValid: (str)->
+    !_.isEmpty(str) and _.isString(str)

data/lib/assets/javascripts/isc_analytics/opt_out_analytics.js.coffee

@@ -0,0 +1,19 @@
+class window.Analytics
+
+  @isLoaded: ->
+
+  @push: (callData) ->
+
+  @trackEvent: (eventName, properties) ->
+
+  @setProperties: (properties) ->
+
+  @setProperty: (property, value) ->
+
+  @identify: (identifier, properties) ->
+
+  @clearIdentity: ->
+
+  @setAlias: (name, identifier) ->
+
+  @isValid: (str)->

data/lib/assets/javascripts/isc_analytics/visitor_analytics.coffee.erb

@@ -0,0 +1,66 @@
+#= require isc_analytics/yepnope
+
+class window.VisitorAnalytics
+
+  ###
+  Save visitor data
+  @param {Object} sessionData - session data from session.js
+  ###
+  @save: (sessionData) ->
+    @sessionData = sessionData
+    @_saveAnalyticsData sessionData
+
+
+  ###
+  Has Location Data - checks to see the call to IPInfoDB didn't fail
+  @return {Boolean}
+  ###
+  @hasLocationData: ->
+    @sessionData.location and (@sessionData.location.statusCode is "OK")
+
+
+  ###
+  Save Analytics Data
+  ###
+  @_saveAnalyticsData: ->
+    if @sessionData
+      data = @sessionData
+      properties = {}
+      properties["Locale"] = data.locale.country + " " + data.locale.lang  if data.locale
+      if data.browser
+        properties["Browser"] = data.browser.browser + " " + data.browser.version
+        properties["OS"] = data.browser.os
+      if data.device
+        properties["Resolution"] = data.device.screen.width + " " + data.device.screen.height
+        properties["Is Tablet"] = data.device.is_tablet
+        properties["Is Phone"] = data.device.is_phone
+        properties["Is Mobile"] = data.device.is_mobile
+      if @hasLocationData()
+        properties["Country"] = @niceName(data.location.countryName)
+        properties["Region"] = @niceName(data.location.regionName)
+        properties["City"] = @niceName(data.location.cityName)
+        properties["Latitude"] = data.location.latitude
+        properties["Longitude"] = data.location.longitude
+      Analytics.setProperties properties
+
+  #niceName("one_two") //-> "One Two"
+  @niceName: (s) ->
+    parts = s.split(/_|-/)
+    for i in [0..parts.length-1]
+      parts[i] = @capitalize(parts[i])
+
+    parts.join(' ')
+
+  @capitalize: (str)->
+    str.charAt(0).toUpperCase() + str.slice(1).toLowerCase()
+
+window.session =
+  options:
+    use_html5_location: false
+    gapi_location: false
+    ipinfodb_key: window.IPINFODB_KEY
+    location_cookie: ""
+    session_cookie: ""
+  start: (sessionData)->
+    VisitorAnalytics.save(sessionData)
+yepnope("<%= javascript_path("isc_analytics/session") %>")

data/lib/isc_analytics.rb

@@ -0,0 +1,17 @@
+require "#{File.dirname(__FILE__)}/isc_analytics/engine"
+require "#{File.dirname(__FILE__)}/isc_analytics/config"
+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"
+
+module IscAnalytics
+
+  mattr_accessor :app
+
+  def self.config
+    @configuration ||= IscAnalytics::Config.default
+  end
+
+end
+

data/lib/isc_analytics/bootstrap.rb

@@ -0,0 +1,83 @@
+require 'isc_analytics/tags'
+require 'isc_analytics/services'
+
+module IscAnalytics
+  class Bootstrap
+    include KISSMetricsClientAPI
+
+    def initialize(options = {})
+      validate_accounts_config
+      @session = options[:session] || {}
+      @opt_out = false
+    end
+
+    def opt_out?
+      !!@opt_out
+    end
+
+    def opt_out!
+      @opt_out = true
+    end
+
+    def analytics_script_tags
+      Tags.scripts(analytics_scripts)
+    end
+
+    private
+
+    def analytics_scripts
+      scripts = []
+      scripts.concat Services.scripts(config.accounts) unless opt_out?
+      scripts << isc_analytics_tag
+      scripts << extend_analytics(config.namespace)
+      scripts << queued_events unless opt_out?
+      scripts
+    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.')
+      end
+    end
+
+    def queued_events
+      queue_js = generate_queue_js
+      return nil if queue_js.blank?
+      Tags.script_tag(queue_js)
+    end
+
+    def extend_analytics(namespace)
+      return nil if namespace.nil?
+      Tags.script_tag <<-SCRIPT
+        (function() {
+          _.extend(window.#{namespace}, window.Analytics)
+        })();
+      SCRIPT
+    end
+
+    def isc_analytics_tag
+      prefix = ''
+      if IscAnalytics.app.config.assets.prefix.present?
+        prefix = IscAnalytics.app.config.assets.prefix + '/'
+      end
+      Tags.script_link_tag(prefix + isc_analytics_asset + '.js')
+    end
+
+    def isc_analytics_asset
+      if opt_out?
+        'isc_analytics/opt_out_analytics'
+      else
+        'isc_analytics'
+      end
+    end
+
+  end
+end

data/lib/isc_analytics/client_api.rb

@@ -0,0 +1,79 @@
+module IscAnalytics
+  module KISSMetricsClientAPI
+
+    def identify(identifier, properties = {})
+      unless identifier.blank? || is_identified(identifier)
+        remove_duplicated_identify
+        if properties.blank?
+          enqueue 'identify', identifier
+        else
+          enqueue 'identify', identifier, properties
+        end
+        set_identity(identifier)
+      end
+    end
+
+    def clear_identify
+      set_identity(nil) # removed identity from session
+      enqueue 'clearIdentity'
+    end
+
+    def track_event(name, properties = {})
+      unless name.blank?
+        if properties.blank?
+          enqueue 'trackEvent', name
+        else
+          enqueue 'trackEvent', name, properties
+        end
+      end
+    end
+
+    def set_properties(properties = {})
+      enqueue('setProperties', properties) unless properties.blank?
+    end
+
+    def set_property(property, value = nil)
+      enqueue('setProperty', property, value) unless property.blank?
+    end
+
+    # reset_queue makes sure that subsequent calls will not send events that have already been sent.
+    def generate_queue_js(reset_queue = true)
+      buffer = get_parsed_queue_string
+      queue.clear if reset_queue
+      buffer
+    end
+
+    private
+
+    def enqueue(name, *args)
+      call = "#{name}(#{args.map(&:as_json).map(&:to_json).join(',')});"
+      queue << call unless queue.include?(call)
+    end
+
+    def queue
+      session[:analytics_queue] ||= []
+    end
+
+    def session
+      @session
+    end
+
+    # Parse the queue by adding the JS class name and newlines to each call
+    def get_parsed_queue_string
+      queue.map{ |api_call| "Analytics.#{api_call}" }.join("\n")
+    end
+
+    def is_identified(identifier)
+      session[:analytics_identity] == identifier
+    end
+
+    def set_identity(identifier)
+      session[:analytics_identity] = identifier
+    end
+
+    def remove_duplicated_identify
+      queue.delete_if { |api_call| !(/identify/ =~ api_call).nil? }
+    end
+
+  end
+end

data/lib/isc_analytics/config.rb

@@ -0,0 +1,15 @@
+module IscAnalytics
+  class Config
+
+    attr_accessor :accounts, :namespace
+
+    def self.default
+      new.instance_eval {
+        @accounts = nil
+        @namespace = nil
+
+        self
+      }
+    end
+  end
+end

data/lib/isc_analytics/controller_support.rb

@@ -0,0 +1,36 @@
+require 'controller_support/base'
+
+module IscAnalytics
+  ## A mixin that provides access to isc_analytics API in the controller.
+  module ControllerSupport
+    extend ::ControllerSupport::Base
+
+    helper_method :add_analytics, :analytics, :opt_out!, :opt_out?
+
+    ##Is the analytics tracking disabled for the current page?
+    def opt_opt?
+      analytics.opt_out?
+    end
+
+    ##This method will disable the analytics tracking of the user
+    def opt_out!
+      analytics.opt_out!
+    end
+
+    ##This method will generate all the javascript needed for client-side analytics tracking.
+    ##This also includes server-side analytics events that were queued to the client during the current request.
+    def add_analytics
+      analytics.analytics_script_tags
+    end
+
+    def analytics
+      isc_analytics
+    end
+
+    private
+
+    def isc_analytics
+      @isc_analytics_bootstrap ||= IscAnalytics::Bootstrap.new(:session => session)
+    end
+  end
+end

data/lib/isc_analytics/engine.rb

@@ -0,0 +1,12 @@
+if defined?(::Rails::Engine)
+  module IscAnalytics
+    module Rails
+      class Engine < ::Rails::Engine
+        initializer :assets do |app|
+          IscAnalytics.app = app
+          app.config.assets.precompile += %w(isc_analytics isc_analytics/session isc_analytics/opt_out_analytics)
+        end
+      end
+    end
+  end
+end

data/lib/isc_analytics/exceptions.rb

@@ -0,0 +1,5 @@
+module IscAnalytics
+  class ConfigReaderNotDefined < StandardError; end
+  class NoConfigSpecified < StandardError; end
+  class MissingConfigParams < StandardError; end
+end

data/lib/isc_analytics/services.rb

@@ -0,0 +1,59 @@
+require 'isc_analytics/tags'
+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)
+      ]
+    end
+
+    def self.kissmetrics_tag(key)
+      Tags.script_tag <<-SCRIPT
+      var _kmq = _kmq || [];
+      function _kms(u){
+        setTimeout(function(){
+          var s = document.createElement('script'); var f = document.getElementsByTagName('script')[0];
+          s.type = 'text/javascript'; s.async = true;
+          s.src = u; f.parentNode.insertBefore(s, f);
+        }, 1);
+      }
+      _kms('//i.kissmetrics.com/i.js');
+      _kms('//doug1izaerwt3.cloudfront.net/#{key}.1.js');
+      SCRIPT
+    end
+
+    def self.google_tag(key)
+      Tags.script_tag <<-SCRIPT
+        var _gaq = _gaq || [];
+        _gaq.push(['_setAccount', '#{key}']);
+        (function() {
+          var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+          ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+          var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+        })();
+      SCRIPT
+    end
+
+    def self.optimizely_tag(key)
+      return nil if key.blank?
+      <<-HTML
+        <script src='//cdn.optimizely.com/js/#{key}.js\'></script>
+        <script type="text/javascript">
+          window['optimizely'] = optimizely || [];
+        </script>
+      HTML
+    end
+
+    def self.ipinfodb_tag(key)
+      return nil if key.blank?
+      Tags.script_tag "window.IPINFODB_KEY = '#{key}';"
+    end
+
+  end
+end

data/lib/isc_analytics/tags.rb

@@ -0,0 +1,18 @@
+require 'active_support/core_ext/string/output_safety'
+
+module IscAnalytics
+  module Tags
+
+    def self.scripts(scripts_array)
+      scripts_array.compact.join().html_safe
+    end
+
+    def self.script_tag(script)
+      "<script type='text/javascript'>#{script}</script>"
+    end
+
+    def self.script_link_tag(link)
+      "<script type='text/javascript' src='#{link}'></script>"
+    end
+  end
+end

metadata

@@ -0,0 +1,111 @@
+--- !ruby/object:Gem::Specification
+name: isc_analytics
+version: !ruby/object:Gem::Version
+  version: '0.5'
+  prerelease: 
+platform: ruby
+authors:
+- Itay Adler
+- Yonatan Bergman
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-12-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: controller_support
+  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'
+- !ruby/object:Gem::Dependency
+  name: configreader
+  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'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  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
+- yonbergman@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/assets/javascripts/isc_analytics/index.js.coffee
+- 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/isc_analytics/bootstrap.rb
+- lib/isc_analytics/client_api.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
+- Rakefile
+- Gemfile
+- README.md
+homepage: https://github.com/TheGiftsProject/isc_analytics
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: A simple Analytics Library
+test_files: []