google_analytics.rb in markcatley-google_analytics-1.0.20080822

- old
+ new

@@ -3,14 +3,13 @@
     def google_analytics_code
       GoogleAnalytics.google_analytics_code(request.ssl?) if GoogleAnalytics.enabled?(request.format)
     end
     
     # An after_filter to automatically add the analytics code.
-    # Add the code at the top of the page to support calls to _trackPageView 
-    #   (see http://www.google.com/support/googleanalytics/bin/answer.py?answer=55527&topic=11006)
-    # If you're not going to use the link_to_tracked view helpers, you can set Rubaidh::GoogleAnalytics.defer_load = true
-    #  to load the codel at the bottom of the page
+    # If you intend to use the link_to_tracked view helpers, you need to set Rubaidh::GoogleAnalytics.defer_load = false
+    # to load the code at the top of the page
+    # (see http://www.google.com/support/googleanalytics/bin/answer.py?answer=55527&topic=11006)
     def add_google_analytics_code
       if GoogleAnalytics.defer_load
         response.body.sub! '</body>', "#{google_analytics_code}</body>" if response.body.respond_to?(:sub!)
       else
         response.body.sub! '<body>', "<body>#{google_analytics_code}" if response.body.respond_to?(:sub!)
@@ -18,72 +17,147 @@
     end
   end
 
   class GoogleAnalyticsConfigurationError < StandardError; end
 
+  # The core functionality to connect a Rails application
+  # to a Google Analytics installation.
+  #
+  # The +GoogleAnalytics+ class has a variety of class attributes for configuration:
+  #
+  # * tracker_id (required)
+  # 
+  # Specify the Google Analytics ID for this web site. This can be found
+  # as the value of +_getTracker+ if you are using the new (ga.js) tracking
+  # code, or the value of +_uacct+ if you are using the old (urchin.js)
+  # tracking code.
+  #
+  # * domain_name
+  #
+  # Specify a different domain name from the default. You'll want to use
+  # this if you have several subdomains that you want to combine into
+  # one report. See the Google Analytics documentation for more
+  # information.
+  #
+  # * legacy_mode
+  #
+  # Specify whether the legacy Google Analytics code should be used. By
+  # default, the new Google Analytics code is used.
+  #
+  # * analytics_url
+  #
+  # I can't see why you'd want to do this, but you can always change the
+  # analytics URL. This is only applicable in legacy mode.
+  #
+  # * analytics_ssl_url
+  #
+  # I can't see why you'd want to do this, but you can always change the
+  # analytics URL (ssl version). This is only applicable in legacy mode.
+  #
+  # * environments
+  #
+  # The environments in which to enable the Google Analytics code. Defaults
+  # to 'production' only. Supply an array of environment names to change this.
+  #
+  # * formats
+  #
+  # The formats for which to add.  Defaults to +:html+ only. Supply an array
+  # of formats to change this.
+  #
+  # * defer_load
+  #
+  # Set this to true (the default) if you want to load the Analytics javascript at 
+  # the bottom of page. Set this to false if you want to load the Analytics 
+  # javascript at the top of the page. The page will render faster if you set this to
+  # true, but that will break the linking functions in Rubaidh::GoogleAnalyticsViewHelper.
+  #
+  # * local_javascript
+  #
+  # Set this to true to use a local copy of the ga.js (or urchin.js) file.
+  # This gives you the added benefit of serving the JS directly from your
+  # server, which in case of a big geographical difference between your server
+  # and Google's can speed things up for your visitors. Use the 
+  # 'google_analytics:update' rake task to update the local JS copies.
+  #
+  # * override_domain_name
+  #
+  # Set this to override the initialized domain name for a single render. Useful
+  # when you're serving to multiple hosts from a single codebase. Typically you'd 
+  # set up a before filter in the appropriate controller:
+  #    before_filter :override_domain_name
+  #    def override_domain_name
+  #      Rubaidh::GoogleAnalytics.override_domain_name  = 'foo.com'
+  #   end
+  #
+  # * override_tracker_id
+  #
+  # Set this to override the initialized tracker ID for a single render. Useful
+  # when you're serving to multiple hosts from a single codebase. Typically you'd 
+  # set up a before filter in the appropriate controller:
+  #    before_filter :override_tracker_id
+  #    def override_tracker_id
+  #      Rubaidh::GoogleAnalytics.override_tracker_id  = 'UA-123456-7'
+  #   end
+  #
+  # * override_trackpageview
+  #
+  # Set this to override the automatically generated path to the page in the
+  # Google Analytics reports for a single render. Typically you'd set this up on a 
+  # controller-by-controller basis:
+  #    def show
+  #      Rubaidh::GoogleAnalytics.override_trackpageview = "path_to_report"
+  #      ...
   class GoogleAnalytics
-    # Specify the Google Analytics ID for this web site.  This can be found
-    # as the value of +_uacct+ in the Javascript excerpt
+  
     @@tracker_id = nil
-    cattr_accessor :tracker_id
+    cattr_accessor :tracker_id  
 
-    # Specify a different domain name from the default.  You'll want to use
-    # this if you have several subdomains that you want to combine into
-    # one report.  See the Google Analytics documentation for more
-    # information.
     @@domain_name = nil
     cattr_accessor :domain_name
 
-    # Specify whether the legacy Google Analytics code should be used.
     @@legacy_mode = false
     cattr_accessor :legacy_mode
     
-    # I can't see why you'd want to do this, but you can always change the
-    # analytics URL.  This is only applicable in legacy mode.
     @@analytics_url = 'http://www.google-analytics.com/urchin.js'
     cattr_accessor :analytics_url
 
-    # I can't see why you'd want to do this, but you can always change the
-    # analytics URL (ssl version).  This is only applicable in legacy mode.
     @@analytics_ssl_url = 'https://ssl.google-analytics.com/urchin.js'
     cattr_accessor :analytics_ssl_url
 
-    # The environments in which to enable the Google Analytics code.  Defaults
-    # to 'production' only.
     @@environments = ['production']
     cattr_accessor :environments
     
-    # The formats for which to add.  Defaults
-    # to :html only.
     @@formats = [:html]
     cattr_accessor :formats
 
-    # Set this to true if you want to load the Analytics javascript at the bottom of
-    # each page rather than at the top. This may result in faster page render times, 
-    # but may break link_to_tracked functionality.
     @@defer_load = true
     cattr_accessor :defer_load
     
-    # Set this to true to use a local copy of the ga.js (or urchin.js) file.
-    # This gives you the added benefit of serving the JS directly from your
-    # server, which in case of a big geographical difference between your server
-    # and Google's can speed things up for your visitors. Use the 
-    # 'google_analytics:update' rake task to update the local JS copies.
     @@local_javascript = false
     cattr_accessor :local_javascript
     
+    cattr_accessor :override_domain_name
+    cattr_accessor :override_tracker_id
+    cattr_accessor :override_trackpageview
+    
     # Return true if the Google Analytics system is enabled and configured
     # correctly for the specified format
     def self.enabled?(format)
       raise Rubaidh::GoogleAnalyticsConfigurationError if tracker_id.blank? || analytics_url.blank?
       environments.include?(RAILS_ENV) && formats.include?(format.to_sym)
     end
     
+    # Construct the javascript code to be inserted on the calling page. The +ssl+
+    # parameter can be used to force the SSL version of the code in legacy mode only.
     def self.google_analytics_code(ssl = false)
       return legacy_google_analytics_code(ssl) if legacy_mode
 
       extra_code = domain_name.blank? ? nil : "pageTracker._setDomainName(\"#{domain_name}\");"
+      if !override_domain_name.blank?
+        extra_code = "pageTracker._setDomainName(\"#{override_domain_name}\");"
+        self.override_domain_name = nil
+      end
       
       code = if local_javascript
         <<-HTML
         <script src="#{LocalAssetTagHelper.new.javascript_path( 'ga.js' )}" type="text/javascript">
         </script>
@@ -98,31 +172,37 @@
       end
       
       code << <<-HTML
       <script type="text/javascript">
       <!--//--><![CDATA[//><!--
-      var pageTracker = _gat._getTracker('#{tracker_id}');
+      var pageTracker = _gat._getTracker('#{request_tracker_id}');
       #{extra_code}
       pageTracker._initData();
-      pageTracker._trackPageview();
+      pageTracker._trackPageview(#{request_tracked_path});
       //--><!]]>
       </script>
       HTML
     end
 
-    # Run the legacy version of the Google Analytics code.
+    # Construct the legacy version of the Google Analytics code. The +ssl+
+    # parameter specifies whether or not to return the SSL version of the code.
     def self.legacy_google_analytics_code(ssl = false)
       extra_code = domain_name.blank? ? nil : "_udn = \"#{domain_name}\";"
+      if !override_domain_name.blank?
+        extra_code = "_udn = \"#{override_domain_name}\";"
+        self.override_domain_name = nil
+      end
+
       url = legacy_analytics_js_url(ssl)
 
       code = <<-HTML
       <script src="#{url}" type="text/javascript">
       </script>
       <script type="text/javascript">
-      _uacct = "#{tracker_id}";
+      _uacct = "#{request_tracker_id}";
       #{extra_code}
-      urchinTracker();
+      urchinTracker(#{request_tracked_path});
       </script>
       HTML
     end
     
     # Generate the correct URL for the legacy Analytics JS file
@@ -131,12 +211,27 @@
         LocalAssetTagHelper.new.javascript_path( 'urchin.js' )
       else
         ssl ? analytics_ssl_url : analytics_url
       end
     end
+
+    # Determine the tracker ID for this request
+    def self.request_tracker_id
+      use_tracker_id = override_tracker_id.blank? ? tracker_id : override_tracker_id
+      self.override_tracker_id = nil
+      use_tracker_id
+    end
+    
+    # Determine the path to report for this request
+    def self.request_tracked_path
+      use_tracked_path = override_trackpageview.blank? ? '' : "'#{override_trackpageview}'"
+      self.override_trackpageview = nil
+      use_tracked_path
+    end
+    
   end
-  
-  class LocalAssetTagHelper
+
+  class LocalAssetTagHelper # :nodoc:
     # For helping with local javascripts
     include ActionView::Helpers::AssetTagHelper
   end
 end