gxapi_rails 0.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 1fc14fc4272595a73becebfd7d22821d6c0f90af
+  data.tar.gz: cb8ec33f3f319d597e91666bf3a14301374d07d3
+SHA512:
+  metadata.gz: 1d787804b60b6a832378ba4ad5cfeccdda4126a49cac129c26986abb98a6fcad44fe46d2c98ae22a47be8e9f6c118cb4e5bf26625df99a50fad9612ec35e34a1
+  data.tar.gz: 061edc4dadaf492b59137b5660df80aaa828a75db68c4f633a7a8c74a72c1168f4847b5355718842b352ea556081fc9fb5b0d93165b14c738f368988ae32e929

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2013 Dan Langevin
+
+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,161 @@
+# Gxapi
+
+[![Code Climate](https://codeclimate.com/repos/5276603656b10215e9014c80/badges/ddae4ab98746f66abf45/gpa.png)](https://codeclimate.com/repos/5276603656b10215e9014c80/feed) [![Build Status](https://travis-ci.org/dlangevin/gxapi_rails.png?branch=master)](https://travis-ci.org/dlangevin/gxapi_rails)
+
+Gxapi interfaces with Google Analytics Experiments to retrieve data from
+its API and determine which variant should be presented to a given user
+
+## Installation
+    % gem install gxapi_rails
+    % rails g gxapi_rails
+
+## Configuration
+
+First, you must create a Google Analytics Service Account.
+Information can be found here https://developers.google.com/accounts/docs/OAuth2ServiceAccount
+
+Gxapi uses `#{Rails.root}/config/gxapi.yml` to configure variables.  You can
+use different configurations per environment (development/test/production)
+
+### Example Configuration
+    development:
+      google_analytics:
+        account_id: ACCOUNT_ID
+        profile_id: PROFILE_ID
+        web_property_id: WEB_PROPERTY_ID
+      google:
+        email: SERVICE_ACCOUNT_EMAIL
+        private_key_path: 'PATH_TO_SERVICE_ACCOUNT_PRIVATE_KEY'
+
+### Where the F do I find all this stuff?
+
+<a href="https://developers.google.com/accounts/docs/OAuth2ServiceAccount"
+target="_blank">Some instructions</a>
+on creating a Google Analytics Service Account
+
+<a href="https://developers.google.com/analytics/resources/concepts/gaConceptsAccounts"
+target="_blank">Some instructions</a> on where to find your
+Google Analytics settings
+
+
+## Usage
+
+### Layout
+
+First, add the experiment Javascript in your layout
+
+    # app/views/layouts/application.html.erb
+    <%= gxapi_experiment_js %>
+
+This will render the Javascript tag to pull in the Google Analytics
+Content Experiment JS source and the corresponding call to send your
+experiment data in.  If you are specifying a custom variable name
+(the default is 'variant'), you can add it here as well
+
+    # app/views/layouts/application.html.erb
+    <%= gxapi_experiment_js(:custom_var) %>
+
+If you have multiple experiments on the same page, you can add this same
+call for each experiment in a view
+
+    # app/views/layouts/application.html.erb
+    <%= gxapi_experiment_js %>
+
+    # app/views/posts/index.html.erb
+    <%= gxapi_experiment_js(:other_experiment_key) %>
+
+### Controller
+
+Once you have set up an experiment in Google Analytics, you can reference
+it by name in your controller
+
+    class PostsController < ApplicationController
+
+      def index
+        gxapi_get_variant("My Experiment")
+      end
+
+    end
+
+This will use the default key `variant` for the experiment.  To customize
+this name, you can pass another value.  This is useful when you are using
+multiple experiments on the same page
+
+    class PostsController < ApplicationController
+
+      def index
+        gxapi_get_variant("My Experiment", :exp1)
+        gxapi_get_variant("Other Experiment", :exp2)
+      end
+
+    end
+
+### Control Flow
+
+In the controller and the view, you can access the variant name to determine
+which path your code should take.  `gxapi_get_variant` returns a
+`Celluloid::Future` to prevent blocking while the result is calculated.  To
+get the value in the controller you can call `#value`.  In the view,
+Gxapi provides a the `gxapi_variant_name` helper.
+
+    class PostsController < ApplicationController
+
+      def index
+        gxapi_get_variant("My Experiment", :exp1)
+      end
+
+    end
+
+    # app/views/posts/index.html.erb
+
+    <h1>My Page</h1>
+
+    <% if gxapi_variant_name(:exp1) == 'version_a' -%>
+      Do some stuff...
+    <% else -%>
+      Do some other stuff...
+    <% end -%>
+
+### Testing and overriding
+
+In order to view a specific version, you can pass `experiment_name=value`
+into a GET request to the action. This will short-circuit the rendering
+of the JavaScript call to Google so testing will not affect your results
+
+    # GET /posts.html?variant=my_var
+
+    # app/controllers/posts_controller.rb
+    def index
+      gxapi_get_variant("My Experiment")
+    end
+
+    # app/views/posts/index.html.erb
+    gxapi_variant_name # Will always equal 'my_var'
+
+
+    # GET /posts.html?custom_name=my_var
+
+    # app/controllers/posts_controller.rb
+    def index
+      gxapi_get_variant("My Experiment", :custom_name)
+    end
+
+    # app/views/posts/index.html.erb
+    gxapi_variant_name(:custom_name) # Will always equal 'my_var'
+
+
+## Contributing to gxapi
+
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
+* Fork the project.
+* Start a feature/bugfix branch.
+* Commit and push until you are happy with your contribution.
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+## Copyright
+
+Copyright (c) 2013 Dan Langevin. See LICENSE.txt for
+further details.
+

data/Rakefile

@@ -0,0 +1,25 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+RSpec::Core::RakeTask.new(:rcov) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :default => :spec

data/app/helpers/gxapi_helper.rb

@@ -0,0 +1,108 @@
+
+#
+# View helper for Gxapi.
+#
+# @author [dlangevin]
+#
+module GxapiHelper
+
+  #
+  # Get the HTMl to load script from Google Ananlytics
+  # and setChosenVariation to tell it which one we served
+  #
+  # @return [String] HTML
+  def gxapi_experiment_js(*args)
+    # extract options
+    opts = args.last.is_a?(Hash) ? args.pop : {}
+    # default
+    ivar_name = args.first || :variant
+
+    unless variant = self.get_variant(ivar_name)
+      return ""
+    end
+
+    # our return value
+    ret = ""
+    # first time we call this, we add the script
+    unless @gxapi_experiment_called == true
+      ret += self.gxapi_source(opts)
+      Gxapi.logger.debug {"Rendered Gxapi source"}
+    end
+
+    @gxapi_experiment_called = true
+    ret += self.get_variant_js(variant)
+
+    Gxapi.logger.debug { "#{ivar_name} is now #{variant.value.name}" }
+
+    ret.html_safe
+  end
+
+  #
+  # Get the version for a given variant
+  # @return [String]
+  def gxapi_variant_name(ivar_name = :variant)
+    # if we have params[ivar], we just use it
+    return "default" unless variant = instance_variable_get("@#{ivar_name}")
+    return variant.value.try(:name) || "default"
+  end
+
+  protected
+
+  #
+  # Get the variant if it exists and has an experiment_id
+  #
+  # @param  ivar_name [String] Name of the instance variable for the
+  # variant
+  #
+  # @return [Gxapi::Ostruct, false] Variant if it exists, false otherwise
+  def get_variant(ivar_name)
+    # make sure we have our variant
+    unless variant = instance_variable_get("@#{ivar_name}")
+      Gxapi.logger.debug { "No variant found - #{ivar_name}" }
+      return false
+    end
+    # and a valid experiment id
+    unless variant.value.experiment_id.present?
+      Gxapi.logger.debug { "No experiment_id found : #{variant.value} "}
+      return false
+    end
+    return variant
+  end
+
+  #
+  # Get the JS for a variant
+  #
+  # @param  variant [Ostruct] Variant definition
+  #
+  # @return [String] JS to render
+  def get_variant_js(variant)
+    javascript_tag{
+      "cxApi.setChosenVariation(
+        #{variant.value.index},
+        '#{escape_javascript(variant.value.experiment_id)}'
+      );".html_safe
+    }
+  end
+
+  #
+  # The Javascript tag for the Content experiment API
+  #
+  # @param [Hash] opts Hash of options
+  #
+  # @return [String] HTML for the tag
+  def gxapi_source(opts)
+    ret = javascript_include_tag(
+      "https://www.google-analytics.com/cx/api.js"
+    )
+    ret += "\n"
+    # set domain name if present
+    if opts[:domain]
+      domain_call = javascript_tag{
+        "cxApi.setDomainName('#{escape_javascript(opts[:domain])}');".html_safe
+      }
+      ret += domain_call.html_safe
+      ret += "\n"
+    end
+    ret
+  end
+end

data/lib/gxapi.rb

@@ -0,0 +1,160 @@
+require 'active_support'
+require 'celluloid'
+require 'erb'
+require 'json'
+require 'yaml'
+
+require File.expand_path('../gxapi/base', __FILE__)
+require File.expand_path('../gxapi/google_analytics', __FILE__)
+require File.expand_path('../gxapi/ostruct', __FILE__)
+require File.expand_path('../gxapi/version', __FILE__)
+
+
+if defined?(::Rails)
+  require File.expand_path('../gxapi/controller_methods', __FILE__)
+  require File.expand_path('../gxapi/engine', __FILE__)
+end
+
+module Gxapi
+
+  #
+  # get our cache instance
+  #
+  # @return [ActiveSupport::Cache::Store]
+  def self.cache
+    # if we have an overridden cache, return it
+    return @overridden_cache if defined?(@overridden_cache)
+    # use Rails.cache if it is defined
+    return ::Rails.cache if defined?(::Rails) && ::Rails.cache
+    # last resort, just use our own cache choice
+    @cache ||= ActiveSupport::Cache::MemoryStore.new
+  end
+
+  #
+  # setter for {Gxapi.cache}
+  #
+  # @return [ActiveSupport::Cache::Store] The new cache object
+  def self.cache=(cache)
+    @overridden_cache = cache
+  end
+
+  #
+  # namespace for our cache keys
+  #
+  # @return [String, nil]
+  def self.cache_namespace
+    @cache_namespace
+  end
+
+  #
+  # setter for {Gxapi.cache_namespace}
+  #
+  # @return [String] New value for cache_namespace
+  def self.cache_namespace=(val)
+    @cache_namespace = val
+  end
+
+  #
+  # Gxapi config - this is loaded based on the
+  # {Gxapi.config_path}
+  #
+  # @return [Gxapi::Ostruct]
+  def self.config
+    @config ||= begin
+      # parse our yml file after running it through ERB
+      contents = File.read(self.config_path)
+      yml = ERB.new(contents).result(binding)
+      Gxapi::Ostruct.new(YAML.load(yml)[Gxapi.env])
+    end
+  end
+
+  #
+  # get the config path for our config YAML file
+  #
+  # @return [String] defaults to #{Rails.root}/config/gxapi.yml
+  def self.config_path
+    @config_path ||= File.join(Rails.root, "config/gxapi.yml")
+  end
+
+  #
+  # setter for config path
+  #
+  # @return [String] value of {Gxapi.config_path}
+  def self.config_path=(val)
+    @config_path = val
+  end
+
+  #
+  # our environment - defaults to Rails.env or test
+  #
+  # @return [String]
+  def self.env
+    @env ||= defined?(::Rails) ? ::Rails.env : "test"
+  end
+
+  #
+  # Set the value of {Gxapi.env}
+  #
+  # @return [String] environment
+  def self.env=(val)
+    @env = val
+  end
+
+  #
+  # instance of logger for Gxapi
+  #
+  # @return [Logger, Log4r::Logger]
+  def self.logger
+    @logger ||= begin
+      if defined?(::Rails) && ::Rails.logger
+        ::Rails.logger
+      else
+        Logger.new(STDOUT)
+      end
+    end
+  end
+
+
+  #
+  # Setter for the Logger
+  # @param  logger [Logger, Log4r]
+  #
+  # @return [Logger, Log4r] Logger instance
+  def self.logger=(logger)
+    @logger = logger
+  end
+
+  #
+  # Reload all data from experiments
+  #
+  # @return [Boolean] Always true
+  def self.reload_experiments
+    Base.new("").reload_experiments
+    true
+  end
+
+
+  #
+  # root directory for gxapi
+  #
+  # @return [String]
+  def self.root
+    File.expand_path("../../", __FILE__)
+  end
+
+  #
+  # Wrap with error handling
+  # logs errors and returns false if an error
+  # occurs
+  #
+  # @return [Value, false]
+  def self.with_error_handling(&block)
+    begin
+      yield
+    rescue => e
+      self.logger.error(e.message)
+      self.logger.error(e.backtrace)
+      false
+    end
+  end
+end