ga_events 0.1.0

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in ga_events.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Nix-wie-weg GmbH & Co. KG
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,93 @@
+# GaEvents
+
+Use Google Analytics' Event Tracking everywhere in your Rails app!
+
+This gem alllows you to annotate events everywhere in the code of your Rails
+app.
+A rack middleware is automatically inserted into the stack. It transports
+the event data to the client. Normal requests get a DIV injected, Ajax requests
+get a data-pounded custom HTTP header appended.
+The asset pipeline-ready CoffeeScript extracts this data on the client-side and
+pushes it to Google Analytics via ga.js or Google Tag Manager.
+
+## Installation
+
+GaEvents works with Rails 3.1 onwards. You can add it to your `Gemfile` with:
+
+```ruby
+gem 'ga_events'
+```
+
+Run the `bundle` command to install it.
+
+Add to the top of your `application.js`:
+
+```javascript
+//= require ga_events.js
+```
+
+After requiring `ga_events.js`, choose an adapter.
+
+For stock Google Analytics (ga.js) use:
+
+```javascript
+GaEvents.Event.adapter = function() {
+  return new GaEvents.GoogleAnalyticsAdapter();
+}
+```
+
+If you are using Google Tag Manager you can add custom events which are then passed through to Google Analytics.
+
+```javascript
+GaEvents.Event.adapter = function() {
+  return new GaEvents.GoogleTagManagerAdapter("event_name"); // defaults to ga_event
+}
+  ```
+
+## Usage
+
+On the server-side a new event is added to a list, serialized into a container
+element and then added to your HTML response. On Ajax requests a custom
+HTTP header is added to the response.
+
+You can create a new event like this:
+
+```ruby
+GaEvents::Event.new(category, action, label, value)
+```
+
+On the client-side there is a similar interface to GaEvents:
+
+```javascript
+new GaEvents.Event(category, action, label, value)
+```
+
+We have taken special care of tracking events while the DOM is loading.
+Events get collected until the DOM is ready and flushed afterwards.
+
+### Too many events
+
+Use something like this snippet to get informed of bloating HTTP headers with
+event data:
+
+```ruby
+class ApplicationController < ActionController::Base
+  after_filter :too_many_ga_events?
+  private
+  def too_many_ga_events?
+    if (serialized = GaEvents::List.to_s).length > 1_024
+      notify("GaEvents too big: #{serialized}")
+    end
+    true
+  end
+end
+```
+
+## Contributing
+
+Yes please! Use pull requests.
+
+## More docs
+
+* [Google Analytics: Event Tracking](https://developers.google.com/analytics/devguides/collection/gajs/eventTrackerGuide)
+* [Google Tag Manager: Custom Events](http://support.google.com/tagmanager/answer/2574372#GoogleAnalytics)

data/REVIEW

@@ -0,0 +1,2 @@
+Flo:  2013-01-28 17:40
+Sven: 2013-01-29 10:10

data/Rakefile

@@ -0,0 +1,2 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"

data/TODO

@@ -0,0 +1,4 @@
+v0.2
+* Remove REVIEW, use Barkeep
+* Tests
+* Announcement

data/app/assets/javascripts/ga_events.js.coffee

@@ -0,0 +1,64 @@
+# This file should be required as soon a possible to allow for
+# early event tracking.
+
+window.GaEvents = {}
+
+class GaEvents.Event
+  adapter: null
+  @list: []
+  @may_flush: false
+  @header_key: "X-GA-Events"
+  @html_key: "ga-events"
+  klass: @
+
+  # Decompose a dom-string (ruby side) into an event object.
+  @from_string: (string) ->
+    $.map string.split("$"), (part) =>
+      [category, action, label, value] = part.split("|")
+      new @(category, action, label, value)
+
+  # Events should not be send to an adapter unless the DOM has finished loading.
+  @flush: ->
+    if @list.length > 0 and @may_flush
+      $.map @list, (event) -> event.push_to_adapter()
+      @list = []
+
+  # Add all events to a queue to flush them later
+  constructor: (@category, @action, @label, @value) ->
+    @klass.list.push @
+    @klass.flush()
+
+  push_to_adapter: ->
+    data =
+      action: @action
+      category: @category
+    data.label = @label if @is_valid_value(@label)
+    data.value = @value if @is_valid_value(@value)
+    @klass.adapter().push data
+
+  is_valid_value: (value) -> value? and value != ''
+
+  jQuery =>
+    @may_flush = true
+    @flush()
+
+    $(document).ajaxComplete (event, xhr) =>
+      xhr_events = xhr.getResponseHeader(@header_key)
+      @from_string(xhr_events) if xhr_events?
+
+    dom_events = $("div[data-#{@html_key}]").data(@html_key)
+    @from_string(dom_events) if dom_events?
+
+class GaEvents.GoogleTagManagerAdapter
+  constructor: (@event = "ga_event") ->
+  push: (data) ->
+    data["event"] = @event
+    data["non_interaction"] = true
+    window.dataLayer.push(data)
+
+class GaEvents.GoogleAnalyticsAdapter
+  push: (obj) ->
+    data = ["_trackEvent", obj["action"], obj["category"]]
+    data.push(obj["label"]) if obj.label?
+    data.push(obj["value"]) if obj.value?
+    window._qaq.push(data)

data/ga_events.gemspec

@@ -0,0 +1,29 @@
+# encoding: utf-8
+require File.expand_path('../lib/ga_events/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ['Florian Dütsch', 'Sven Winkler']
+  gem.email         = ['florian.duetsch@nix-wie-weg.de',
+                       'sven.winkler@nix-wie-weg.de']
+  gem.description   =
+    %q{Google Analytics' Event Tracking everywhere in your Rails app}
+  gem.summary       = 'This gem alllows you to annotate events everywhere in ' \
+                      'the code of your Rails app.  A rack middleware is ' \
+                      'automatically inserted into the stack. It transports ' \
+                      'the event data to the client. Normal requests get a ' \
+                      'DIV injected, AJAX requests get a data-pounded custom ' \
+                      'HTTP header appended.  The asset pipeline-ready ' \
+                      'CoffeeScript extracts this data on the client side ' \
+                      'and pushes it to Google Analytics via ga.js or Google ' \
+                      'Tag Manager.'
+  gem.homepage      = 'https://github.com/Nix-wie-weg/ga_events'
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "ga_events"
+  gem.require_paths = ["lib"]
+  gem.version       = GaEvents::VERSION
+
+  gem.add_dependency 'rails', '~> 3.1'
+end

data/lib/ga_events.rb

@@ -0,0 +1 @@
+%w(middleware engine event list version).each { |f| require "ga_events/#{f}" }

data/lib/ga_events/engine.rb

@@ -0,0 +1,5 @@
+module GaEvents
+  class Engine < ::Rails::Engine
+    config.app_middleware.use GaEvents::Middleware
+  end
+end

data/lib/ga_events/event.rb

@@ -0,0 +1,13 @@
+module GaEvents
+  class Event < Struct.new(:category, :action, :label, :value)
+    def initialize(category, action, label = nil, value = nil)
+      super
+      GaEvents::List << self
+    end
+
+    def to_s
+      [category, action, label, value].join('|')
+    end
+  end
+end
+

data/lib/ga_events/list.rb

@@ -0,0 +1,26 @@
+# NOTE: Collecting the events is thread-safe, but will cause problems in an
+#       asynchronous environment.
+
+module GaEvents::List
+  def self.<<(event)
+    data << event
+  end
+
+  def self.to_s
+    data.collect(&:to_s).join('$')
+  end
+
+  def self.present?
+    data.present?
+  end
+
+  def self.init
+    Thread.current[:ga_events] = []
+  end
+
+  def self.data
+    Thread.current[:ga_events]
+  end
+
+  private_class_method :data
+end

data/lib/ga_events/middleware.rb

@@ -0,0 +1,43 @@
+require 'rack/utils'
+
+module GaEvents
+  class Middleware
+
+    def initialize(app)
+      @app = app
+    end
+    def call(env)
+      GaEvents::List.init
+      status, headers, response = @app.call(env)
+      headers = Rack::Utils::HeaderHash.new(headers)
+
+      if GaEvents::List.present?
+        request = Rack::Request.new(env)
+
+        # Can outgrow, headers might get too big
+        serialized = GaEvents::List.to_s
+
+        if request.xhr?
+          headers['X-GA-Events'] = serialized
+        elsif is_html?(status, headers)
+          new_body = response.body.sub('</body>',
+            "<div data-ga-events='#{serialized}'></div>\\0")
+          response = [new_body]
+        end
+      end
+
+      [status, headers, response]
+    end
+
+    private
+
+    # Taken from:
+    # https://github.com/rack/rack-contrib/blob/master/lib/rack/contrib/jsonp.rb
+    def is_html?(status, headers)
+      !Rack::Utils::STATUS_WITH_NO_ENTITY_BODY.include?(status.to_i) &&
+        headers.key?('Content-Type') &&
+        headers['Content-Type'].include?('text/html')
+    end
+  end
+end
+

data/lib/ga_events/version.rb

@@ -0,0 +1,3 @@
+module GaEvents
+  VERSION = "0.1.0"
+end

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: ga_events
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Florian Dütsch
+- Sven Winkler
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-01-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.1'
+description: Google Analytics' Event Tracking everywhere in your Rails app
+email:
+- florian.duetsch@nix-wie-weg.de
+- sven.winkler@nix-wie-weg.de
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE
+- README.md
+- REVIEW
+- Rakefile
+- TODO
+- app/assets/javascripts/ga_events.js.coffee
+- ga_events.gemspec
+- lib/ga_events.rb
+- lib/ga_events/engine.rb
+- lib/ga_events/event.rb
+- lib/ga_events/list.rb
+- lib/ga_events/middleware.rb
+- lib/ga_events/version.rb
+homepage: https://github.com/Nix-wie-weg/ga_events
+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: This gem alllows you to annotate events everywhere in the code of your Rails
+  app.  A rack middleware is automatically inserted into the stack. It transports
+  the event data to the client. Normal requests get a DIV injected, AJAX requests
+  get a data-pounded custom HTTP header appended.  The asset pipeline-ready CoffeeScript
+  extracts this data on the client side and pushes it to Google Analytics via ga.js
+  or Google Tag Manager.
+test_files: []