RubyGems - omniture_client - Versions diffs - 0.0.1 → 0.0.2 - Mend

omniture_client 0.0.1 → 0.0.2

Files changed (16) hide show

data/.gitignore +1 -0
data/MIT-LICENSE +22 -0
data/README.markdown +202 -0
data/VERSION +1 -1
data/lib/omniture_client.rb +17 -35
data/lib/omniture_client/base.rb +15 -11
data/lib/omniture_client/controller_methods.rb +13 -0
data/lib/omniture_client/{var_group.rb → meta_var.rb} +5 -9
data/lib/omniture_client/printer.rb +11 -18
data/lib/omniture_client/var.rb +3 -8
data/lib/rails.rb +37 -18
data/omniture_client.gemspec +9 -6
data/sample/omniture.yml +47 -0
metadata +9 -6
data/README +0 -0
data/omniture_client.rb +0 -7

data/.gitignore ADDED Viewed

	@@ -0,0 +1 @@
1	+ pkg

data/MIT-LICENSE ADDED Viewed

@@ -0,0 +1,22 @@
+Copyright (c) 2009 Alexandru Catighera
+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.markdown ADDED Viewed

@@ -0,0 +1,202 @@
+# OmnitureClient
+This gem integrates Omniture SiteCatalyst into your web app.
+## Installation
+    gem install omniture_client
+## Omniture on Rails
+This gem provides the ability to track a Rails application at the controller level. I prefer a completely sever-side implementation as opposed to using Omniture's s_code.js. This gem supports using both; however, the majority of the examples will be for a completely
+### File Structure
+You create reporters in 'app/reporters' directory, which correspond to your controllers. The example I will use is a `MoviesController`. Omniture client will first attempt to use `MoviesReporter`. If you have not defined the `MoviesReporter`, then it will use the `BasicReporter`, which is what all controllers that do not have any special functionality should use. If you have not yet defined a `BasicReporter`, then it will use a stub that tracks nothing. You will pretty much always at least want a basic reporter, and for controllers that need to track special events or custom variables you should use a custom reporter.
+    rails_project/
+    ..../app
+    ......../reporters
+    ............/movies_reporter.rb
+    ............/basic_reporter.rb
+    ..../config
+    ......../omniture.yml
+### Configuration
+You must configure the Omniture namespace, suite(s), version that you wish to use. Optionally, you can set up aliases to make things easier for yourself when coding reporters. Omniture uses `c1`, `e1`, `r`, etc to represent custom variables, e_vars, the referrer, etc. These param names are obscure and can be hard to remember so you can set up aliases for them. From the example below `movie_title` repersents custom varibale 2 (`c2`).
+    # config/omniture.yml
+    development:
+      base_url: http://102.112.2O7.net
+      ssl_url: https://102.112.2O7.net
+      suite: suite1
+      version: G.4--NS
+      aliases:
+        search_term: c1
+        movie_titles: e1
+        referrer: r
+As well as the omniture.yml you need to also add the `app/reporters` directory to your load path. So in your enviroment file add the 2 following lines:
+    # config/enviroment.rb
+    Rails::Initializer.run do |config|
+      config.load_paths += %W( #{RAILS_ROOT}/app/reporters )
+      config.gem "omniture_client"
+    end
+### View
+The view code is straight foward. This is img tag is what actually sends the information to Omniture. It should probably be the last element in the body tag.
+    # app/views/layouts/application.html.erb
+    <html>
+      <head>...</head>
+      <body>
+        ....
+        <img style='display:none' src="<%= @controller.omniture_url %>">
+      </body>
+    </html>
+### Controller
+Here is an example of a controller we would like to track:
+    # app/controller/movies_controller.rb
+    class MoviesController < ApplicationController
+      def index
+        @movies = Movie.all
+      end
+      def show
+        @movie = Movie.find(params[:id])
+      end
+      def search
+        @keyword = params[:keyword]
+        @movies = Movie.search(@keyword)
+      end
+    end
+### Reporter
+Reporters have access to all controller instance variables and methods. Below we use the `@movie` instance variable and `request` instance method which are from the controller instance. Also, be aware of the omniture.yml configuration, `:search_term` and `movie_titles` are aliases specific to this movies example. In your app you will want to use `c1` and `c2` or set up your own aliases in your omniture.yml.
+    class MoviesReporter < OmnitureClient::Base
+      var :pageName do
+        page_name = "Movie Page"
+      end
+      # We can use any instance methods from the controller, here we use the `request` method
+      var :r do
+        request.referrer
+      end
+      # trigger event5 if user is doing a search and trigger event6 if movie is R rated
+      var :events do
+        events = []
+        events << 'event5' if action_name == 'search' && @keyword
+        events << 'event6' if action_name == 'show' && @movie.rating == "R"
+        events
+      end
+      var :search_term do
+        @keyword if action_name == 'search'
+      end
+      # list prop that is delimited by |
+      var :movie_titles, '|' do
+        @movies.map{ |movie| movie.title } if action_name == 'index'
+      end
+    end
+The `pageName` param is an extremely important param, the most important in fact. The `r` param which represents the referrer is also very important. The page name will default the the URL if you do not specify it, which is probably what you do not want. For the purposes of simiplicity I made the page name simple but in reality you will want it to be something like this:
+    var :pageName do
+      case action_name
+        when 'show' : "Movie - #{@movie.title}"
+        else 'index' : "Movie List Page"
+      end
+    end
+That is it to get the basics up and running with Rails.
+## Additional Information
+### Server-side events
+Sometime there is a need to track events or other custom variables on the server side. To do this Omniture provides a SOAP API, however, I preferred an alternative method. I preferred to use Rails' flash to store the custom event or variable and append it to the img tag on the next page load. Here is an example of tracking a successful movie creation as an Omniture event (`event7`).
+    # app/controller/movies_controller.rb
+    class MoviesController < ApplicationController
+      def new
+        @movie = Movie.new
+      end
+      def create
+        @movie = Movie.new(params[:movie])
+        if @movie.save
+          flash[:notice] = 'Movie was successfully created.'
+          omniture_flash[:events] = 'event7'
+          redirect_to(@movie)
+        else
+          render :action => "new"
+        end
+      end
+    end
+## Omniture Client for Sinatra (or other ruby web framework)
+This gem works with any ruby web framework. However, some of the functionality like server-side tracking is only implemented for Rails. Here is an example using Omniture Client to track a Sinatra app.
+    # application.rb
+    require 'omniture_client'
+    OmnitureClient.config({
+      :base_url => 'http://102.112.2O7.net',
+      :ssl_url => 'https://102.112.2O7.net',
+      :suite => 'suite1',
+      :version=> 'G.4--NS',
+      :aliases => {
+        'search_terms' => 'c1'
+      }
+    })
+    helpers do
+      def reporter
+        SinatraReporter.new(self)
+      end
+    end
+    get '/' do
+      @title = "home"
+      haml :index
+    end
+    class SinatraReporter < OmnitureClient::Base
+      var :pageName do
+        @title
+      end
+    end
+You will also need to render the img tag in your views since this is the bit that actually sends the request to Omniture.
+    # view/index.html.haml
+    %img{ :style => 'display:none', :src => reporter.url }
+## Javascript Implementation
+A javascript implementation is slightly more obstrusive; however, there are a few extra reports you get access to in the Omniture web tool (ie. click map). So all the server-side code remains the same except for the the variable names. For example, instead of `c1` we use `s.prop1`. To have a javascript implementation, you also have to remove the img tag from your layout and add the reporter variables to the s_code.js. I will use a RJS for this example but you could can handle it a number of ways.
+    # config/omniture.yml
+    development:
+      base_url: http://102.112.2O7.net
+      ssl_url: https://102.112.2O7.net
+      suite: suite1
+      version: G.4--NS
+      aliases:
+        search_term: prop1
+        movie_titles: e_var1
+### Javascript
+Here are the following script tags you will need. If you includes these DO NOT render the img tag shown in the examples above.
+    <script language="javascript" src="//INSERT-DOMAIN-AND-PATH-TO-CODE-HERE/s_code.js"></script>
+    <script language="javascript">
+      //<![CDATA[
+        <% @controller.reporter.vars.each do |var| %>
+          s.<%= var.name %>="<%= var.value %>";
+        <% end %>
+        s.t();
+      //]]>
+    </script>
+##### Copyright (c) 2009 Alexandru Catighera, released under MIT license

data/VERSION CHANGED Viewed

	@@ -1 +1 @@
1	- 0.0.1
1	+ 0.0.2

data/lib/omniture_client.rb CHANGED Viewed

@@ -1,42 +1,24 @@
-module OmnitureClient
-  def import_aliases(alias_hash)
-    @alias_hash = alias_hash
-  end
-  attr_reader :alias_hash
-  module ControllerMethods
-    def self.included(base)
-      base.extend(ClassMethods)
-    end
+require File.dirname(__FILE__) + '/omniture_client/printer'
+require File.dirname(__FILE__) + '/omniture_client/base'
+require File.dirname(__FILE__) + '/omniture_client/var'
+require File.dirname(__FILE__) + '/omniture_client/meta_var'
+require File.dirname(__FILE__) + '/omniture_client/controller_methods'
+require 'cgi'
-    module ClassMethods
-      def report_to(reporter)
-        include InstanceMethods
-        @reporter = reporter
-      end
+class BasicReporter < OmnitureClient::Base; end
-      def reporter
-        @reporter
-      end
-    end
-    module InstanceMethods
-      def reporter
-        if self.class.reporter.is_a?(Class)
-          @reporter ||= reporter
-        elsif self.class.reporter.is_a?(Proc)
-          @reporter ||= reporter.call
-        end
-      end
-      def omniture_js
-        reporter.to_js
-      end
+module OmnitureClient
+  class << self
+    attr_accessor :aliases, :base_url, :ssl_url, :suite, :version
-      def omniture_url
-        reporter.to_query
+    def config(config_hash)
+      config_hash.each do |key, val|
+        send("#{key}=", val)
       end
     end
   end
 end
+if defined?(Rails)
+  require File.dirname(__FILE__) + '/rails'
+end

data/lib/omniture_client/base.rb CHANGED Viewed

@@ -5,7 +5,7 @@ module OmnitureClient
     attr_reader  :controller
-    @var_groups = []
+    @meta_vars = []
     def initialize(controller)
       @controller = controller
@@ -16,24 +16,28 @@ module OmnitureClient
     end
     def vars
-      @vars ||= self.class.var_groups.inject([]) do |vars, grp|
-        vars << grp.values(controller) if grp
+      meta_vars = self.class.meta_vars || []
+      @vars ||= meta_vars.inject([]) do |vars, meta_var|
+        vars << meta_var.value(controller) if meta_var
         vars
       end
     end
     def add_var(name, value)
-      vars << Var.new(name, value)
+      self.class.var(name) do
+        value
+      end
     end
     class << self
-      attr_reader :var_groups
-      def define_var(name, &block)
-        var_group = instance_eval("@#{name} ||= VarGroup.new(name)")
-        var_group.add_var(block)
-        var_groups << var_group unless var_groups.include?(var_group)
-        var_group
+      attr_reader :meta_vars
+      def var(name, delimiter = ',', &block)
+        @meta_vars ||= []
+        meta_var = instance_eval("@#{name} ||= OmnitureClient::MetaVar.new('#{name}', '#{delimiter}')")
+        meta_var.add_var(block)
+        meta_vars << meta_var unless meta_vars.include?(meta_var)
+        meta_var
       end
     end
   end

data/lib/omniture_client/controller_methods.rb ADDED Viewed

@@ -0,0 +1,13 @@
+module OmnitureClient
+  module ControllerMethods
+    attr_accessor :report
+    def omniture_js
+      reporter.to_js
+    end
+    def omniture_url
+      reporter.to_query
+    end
+  end
+end

data/lib/omniture_client/{var_group.rb → meta_var.rb} RENAMED Viewed

@@ -1,12 +1,12 @@
 module OmnitureClient
-  class VarGroup
-    attr_reader :name
+  class MetaVar
+    attr_reader :name, :delimiter
     attr_accessor :value_procs
-    def initialize(name)
+    def initialize(name, delimiter)
       @name = name
       @value_procs = []
-      @composite = composite
+      @delimiter = delimiter
     end
     def add_var(value_proc)
@@ -14,11 +14,7 @@ module OmnitureClient
     end
     def value(scope)
-      Var.new(name, value_procs.map{ |p| scope.instance_eval(p) })
+      Var.new(name, value_procs.map{ |p| scope.instance_eval(&p) }.flatten.uniq.join(delimiter))
     end
-    private
-    attr_reader :composite
   end
 end

data/lib/omniture_client/printer.rb CHANGED Viewed

@@ -1,30 +1,23 @@
 module OmnitureClient
   module Printer
-    def to_js
-      var_types.inject("") do |js, var_type|
-        send(var_type).each do |var|
-          js << var_to_js(var)
-        end
-      end
+    def url(ssl = false)
+      suite = OmnitureClient::suite.is_a?(Array) ? OmnitureClient::suite.join(',') : OmnitureClient::suite
+      base_url =  ssl == :ssl ? OmnitureClient::ssl_url : OmnitureClient::base_url
+      "#{base_url}/b/ss/#{suite}/#{OmnitureClient::version}/#{rand(9999999)}?#{query}"
     end
-    def to_query
-      var_types.inject("") do |query, var_type|
-        send(var_type).each do |var|
-          query << var_to_query(var)
-        end
-      end
+    def query
+      vars.inject([]) do |query, var|
+        query << var_to_query(var) if var.value && var.value != ""
+        query
+      end.join('&')
     end
     private
     def var_to_query(var)
-      send(var).to_query(var) + '&' if send(var)
-    end
-    def var_to_js(var)
-      "var #{var} = '#{send(var).gsub()}'; " if send(var)
+      "#{ CGI::escape(var.name) }=#{ CGI::escape(var.value) }" if var
     end
   end
 end

data/lib/omniture_client/var.rb CHANGED Viewed

@@ -2,17 +2,12 @@ module OmnitureClient
   class Var
     attr_reader :name, :value
     def initialize(name, value)
-      @name = name
-      if OmnitureClient::alias_hash && OmnitureClient::alias_hash[name]
-        @name = OmnitureClient::alias_hash[name]
+      if OmnitureClient::aliases && OmnitureClient::aliases[name.to_s]
+        @name = OmnitureClient::aliases[name.to_s]
       else
-        @name = name
+        @name = name.to_s
       end
       @value = value
     end
-    def to_param
-      value.to_param(name)
-    end
   end
 end

data/lib/rails.rb CHANGED Viewed

@@ -1,31 +1,50 @@
 module OmnitureClient
   module ActionControllerMethods
-    def reports_to_omniture
-      include ControllerMethods
-      before_filter do
-        omniture_flash.each do |name, value|
-          reporter.add_var(name, value)
-        end
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+    module ClassMethods
+      def reports_to_omniture
+        include InstanceMethods
+        before_filter :set_reporter, :assign_flash_vars
+        attr_accessor :reporter
       end
+    end
-      report_to lambda {
-        begin
-          "#{controller_path.classify}Reporter".constantize.new(self)
-        rescue
-          BasicReporter.new(self)
-        end
-      }
-      define_method :omniture_flash do
+    module InstanceMethods
+      def omniture_flash
         flash[:omniture] ||= {}
       end
+      def omniture_url
+        ssl = :ssl if request.ssl? && OmnitureClient::ssl_url
+        reporter.url(ssl)
+      end
+      private
+      def set_reporter
+        @reporter ||= begin
+          "#{controller_path.classify.pluralize}Reporter".constantize.new(self)
+         rescue NameError
+           BasicReporter.new(self)
+         end
+      end
+      def assign_flash_vars
+        omniture_flash.each do |name, value|
+          reporter.add_var(name, value)
+        end
+      end
     end
   end
 end
-if is_defined?(ApplicationController)
-  ApplicationController.extend(ActionControllerMethods)
-  ApplicationController.reports_to_omniture
+if defined?(ActionController::Base)
+	ActionController::Base.send(:include, OmnitureClient::ActionControllerMethods)
+	ApplicationController.reports_to_omniture
 end
+OmnitureClient::config(YAML::load(File.open(File.join(RAILS_ROOT, 'config', 'omniture.yml')))[RAILS_ENV]) if File.exists?(File.join(RAILS_ROOT, 'config', 'omniture.yml'))

data/omniture_client.gemspec CHANGED Viewed

@@ -5,27 +5,30 @@
 Gem::Specification.new do |s|
   s.name = %q{omniture_client}
-  s.version = "0.0.1"
+  s.version = "0.0.2"
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Alexandru Catighera"]
-  s.date = %q{2009-12-02}
+  s.date = %q{2010-01-08}
   s.email = %q{alex@patch.com}
   s.extra_rdoc_files = [
-    "README"
+    "README.markdown"
   ]
   s.files = [
-    "README",
+    ".gitignore",
+     "MIT-LICENSE",
+     "README.markdown",
      "Rakefile",
      "VERSION",
      "lib/omniture_client.rb",
      "lib/omniture_client/base.rb",
+     "lib/omniture_client/controller_methods.rb",
+     "lib/omniture_client/meta_var.rb",
      "lib/omniture_client/printer.rb",
      "lib/omniture_client/var.rb",
-     "lib/omniture_client/var_group.rb",
      "lib/rails.rb",
      "omniture_client.gemspec",
-     "omniture_client.rb"
+     "sample/omniture.yml"
   ]
   s.homepage = %q{http://github.com/acatighera/omniture_client}
   s.rdoc_options = ["--charset=UTF-8"]

data/sample/omniture.yml ADDED Viewed

@@ -0,0 +1,47 @@
+development:
+  base_url: http://102.112.2O7.net
+  ssl_url: https://102.112.2O7.net
+  suite: suite1
+  version: G.4--NS
+  aliases:
+    prop1: c1
+    prop2: c2
+    prop3: c3
+    prop4: c4
+    prop5: c5
+    prop6: c6
+    prop7: c7
+    prop8: c8
+    prop9: c9
+    prop10: c10
+    prop11: c11
+    prop12: c12
+    prop13: c13
+    prop14: c14
+    prop15: c15
+    prop16: c16
+    prop17: c17
+    prop18: c18
+    prop19: c19
+    prop20: c20
+    e_var1: v1
+    e_var2: v2
+    e_var3: v3
+    e_var4: v4
+    e_var5: v5
+    e_var6: v6
+    e_var7: v7
+    e_var8: v8
+    e_var9: v9
+    e_var10: v10
+    e_var11: v11
+    e_var12: v12
+    e_var13: v13
+    e_var14: v14
+    e_var15: v15
+    e_var16: v16
+    e_var17: v17
+    e_var18: v18
+    e_var19: v19
+    e_var20: v20

metadata CHANGED Viewed

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: omniture_client
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Alexandru Catighera
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
-date: 2009-12-02 00:00:00 -05:00
+date: 2010-01-08 00:00:00 -05:00
 default_executable:
 dependencies: []
@@ -20,19 +20,22 @@ executables: []
 extensions: []
 extra_rdoc_files:
-- README
+- README.markdown
 files:
-- README
+- .gitignore
+- MIT-LICENSE
+- README.markdown
 - Rakefile
 - VERSION
 - lib/omniture_client.rb
 - lib/omniture_client/base.rb
+- lib/omniture_client/controller_methods.rb
+- lib/omniture_client/meta_var.rb
 - lib/omniture_client/printer.rb
 - lib/omniture_client/var.rb
-- lib/omniture_client/var_group.rb
 - lib/rails.rb
 - omniture_client.gemspec
-- omniture_client.rb
+- sample/omniture.yml
 has_rdoc: true
 homepage: http://github.com/acatighera/omniture_client
 licenses: []

data/README DELETED Viewed

File without changes

data/omniture_client.rb DELETED Viewed

@@ -1,7 +0,0 @@
-require 'lib/omniture_client/base.rb'
-require 'lib/omniture_client.rb'
-if is_defined?(Rails)
-  require 'lib/rails.rb'
-end
-class BasicReporter; end