analytics_instrumentation 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 23edc0fcddb60777d22506a73d5644a823beed1d
+  data.tar.gz: 7229fb73b5606f178e55dbaba1df3be2c2b09e34
+SHA512:
+  metadata.gz: d092014e81ee505b97ca8b5d6f47d8671c492513e0f1367276073b672c21b1da74cbb8e07efe7d561b59946d73f12b8d0a0f9985f254ff8575a588143128402e
+  data.tar.gz: ab0dd4da0f9d16afb9944b75109a424696643736e84a74a4e55d424d5102bc431e139809b31bb215110fa53e8772fbc29a59df07293e28d8aa69f628bedb642c

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2015 Jordan Feldstein
+
+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.rdoc

@@ -0,0 +1,225 @@
+= AnalyticsInstrumentation
+
+== Install
+
+    gem 'analytics_instrumentation'
+
+or
+
+    gem install 'analytics_instrumentation'
+
+
+== Usage
+
+Once installed, write your initializer and yml mappings.
+
+== Initializer & Defaults
+
+Most behaviors in AnalyticsInstrumentation are one-size-fits-all.
+
+A few behaviors can be hooked into via an initializer (eg. `./config/initializers/analytics_instrumentation.rb`) to be customized to your app.
+
+The behaviors exposed are:
+
+    # ./config/initializers/analytics_instrumentation.rb
+
+    AnalyticsImplementation.configure do |config|
+      # Your Segment.io write key is required. We will instantiate the client.
+      config.segment_write_key = ENV["SEGMENT_API_KEY"] || ""
+
+      # Define a hash of traits to be passed to `#identify()` calls for each user.
+      config.custom_user_traits = (user) -> {
+        {
+          name: user.full_name,
+          email: user.email,
+          created_at: user.created_at,
+          provider: user.provider,
+          provider_username: user.provider_username,
+          postings_count: user.postings_count,
+          public_collections_count: user.collections_count,
+          private_collections_count: user.private_collections_count,
+          followers_count: user.followers_count,
+          following_count: user.followed_users_count
+        }
+      }
+
+      # # AnalyticsInstrumentation sends a variety of properties with each of your events:
+      # 1. Event-specific properties are configured via the YML files (see below)
+      # 2. System-wide properties are included for you with all events (see below)
+      # 3. To have your own system-wide properties included on all events, have them returned by a Proc set to `config.extra_event_properties`, like so:
+      config.extra_event_properties = -> {
+        {
+          user_sees_experiment_a: current_user.experiment_a?
+          user_sees_experiment_b: current_user.experiment_b?
+        }
+      }
+
+      # To capture and handle errors that happen within AnalyticsInstrumentation,
+      # Define an error_handler, like so:
+      config.error_handler = (e, msg) -> {
+        if Rails.env.production?
+          Rollbar.error(e, msg)
+        else
+          raise
+        end
+      }
+    end
+
+== Configuring Events & Their Properties
+
+AnalyticsInstrumentation maps controller#action pairs to events using YML files in `./config/analytics/*.yml`.
+
+These files also define how properties for each event should be constructed, based on  the corresponding request/response's view_assigns. (Calling @var_name in a view)
+
+Examples:
+
+1. Requests -> Event names
+
+    # ./config/analytics/home.yml
+
+    home#landing:
+      name: Viewed Home page
+    home#press:
+      name: Viewed Press page
+    home#app:
+      name: Viewed App page
+
+2. Requests -> Events with simple properties
+
+    # ./config/analytics/issues.yml
+
+    issues#index:
+      name: Viewed Issue List
+
+    issues#show:
+      name: Viewed Issue
+      page_identifier: "@issue.id"
+      parameters:
+        issue_number: "params[:issue_number]"
+        title: "@issue.title"
+
+3. Requests -> Events with dynamic properties
+
+    # ./config/analytics/products.yml
+
+    api#post_product:
+      name: 'if @likedProduct then "Liked Product" else "Unliked Product" end'
+
+    products#show:
+      name: Viewed Product
+      page_identifier: "@product.id"
+      parameters:
+        product_id: "@product.id"
+        name: '@product.name.gsub("\"", "")'
+        brand: "@brand.try(:name)"
+        category: "@category.try(:name)"
+
+    products#create_comment:
+      name: Created Comment
+      parameters:
+        product_id: "@product.id"
+        product_name: "@product.name"
+        comment_text: "@comment.message"
+        previous_comment_count: "@product.comments_count"
+
+
+== Simple "Page View" Events
+
+AnalyticsInstrumentation will automatically trigger a "Page View" event for every request, passing `request.path` as a `page` property, like so:
+
+    properties = {
+      page: request.path
+    }
+
+This is in addition to the rest of the system-wide properties attached to all events.
+
+
+== System Wide Properties Attached to All Events
+
+    {
+      "Raw Analytics ID"  => raw_analytics_id,
+      "Ajax"              => !request.xhr?.nil?,
+
+      "logged_in"         => !!current_user,
+      "source"            => params[:source], if params[:source]
+
+      "Originating Page Identifier" => session["previous-page-identifier"],
+      "Originating Page Type"       => session["previous-page-type"]
+    }
+
+All new visitors are cookied with a `Raw Analytics ID`, useful as the Actor property when looking at the behavior of logged-out traffic. `Raw Analytics Id` is aliased to user_id when a user logs in, if any of your analytics tools support `#alias()`.
+
+`Originating Page Type/ID` are set automatically based on the previous internal request. `Type` is the Name of the most recently triggered custom event. `Identifier` is the corresponding `page_identifier:`. Search the YML examples for this in action. Useful to see "How did people get here?".
+
+Send `params[:source]` with any GET or POST request to differentiate where in the UI a given event was triggered. eg:
+
+    POST /user/create
+    {
+      user: {...},
+      source: 'Navbar'
+    }
+
+vs
+
+    POST /user/create
+    {
+      user: {...},
+      source: 'Primary CTA'
+    }
+
+
+== System Wide Properties Attached Only to Logged In Requests
+
+Any user traits you return from your initializer's `custom_user_traits` config will be merged with the following default user traits:
+
+    {
+      "User Created At" => current_user.created_at,
+      "Username"        => current_user.try(:username),
+      "Full name"       => current_user.try(:full_name),
+      "User ID"         => current_user.id,
+      "Login Provider"  => current_user.try(:provider) || "Email",
+    }
+
+== Marketing Attribution
+
+AnalyticsInstrumentation makes it easy to see which of your UTM campaigns and external referrers are contributing to product engagement and revenue events deeper in the funnel.
+
+This is done by tracking the first-ever and most-recent set of UTM parameters, as well as the first-ever and most-recent external HTTP referrer for each unique visitor to your site.
+
+These data are passed into all named events (the ones in your YML files) as:
+
+    {
+      first_external_referrer:  'google.com',
+      latest_external_referrer: 'twitter.com',
+      first_utm: {
+        name:     'Spring Campaign 1',
+        source:   'twitter',
+        medium:   'card',
+        term:     'flowers',
+        content:  'variant1'
+      },
+      latest_utm: {
+        name:     'Spring Campaign 1',
+        source:   'twitter',
+        medium:   'card',
+        term:     'flowers',
+        content:  'variant1'
+      }
+    }
+
+This is useful for doing things like "Count the number of new users generated by each ad campaign" or "How many posts were created by users from that buzzfeed article?".
+
+
+== License
+
+MIT
+
+== Thoughts, Feedback, Ideas?
+
+Please tweet to [@jfeldstein](twitter.com/jfeldstein) or [@msfeldstein](twitter.com/msfeldstein) or open a Github Issue if you have feedback.
+
+Thanks!
+
+== Used This Code?
+
+Please let us know if you've used this code in any products or projects. We'd love to hear about your experience! Tweet to [@jfeldstein](twitter.com/jfeldstein) or [@msfeldstein](twitter.com/msfeldstein)

data/Rakefile

@@ -0,0 +1,40 @@
+require 'rubygems'
+require 'rake'
+require 'rake/testtask'
+$:.push File.expand_path("../lib", __FILE__)
+require "analytics_instrumentation"
+
+# Rake::TestTask.new(:test) do |test|
+#   test.libs << 'lib' << 'test'
+#   test.pattern = 'test/{functional,unit}/**/*_test.rb'
+# end
+
+# namespace :test do
+#   Rake::TestTask.new(:lint) do |test|
+#     test.libs << 'lib' << 'test'
+#     test.pattern = 'test/test_active_model_lint.rb'
+#   end
+
+#   task :all => ['test', 'test:lint']
+# end
+
+# task :default => 'test:all'
+
+desc 'Builds the gem'
+task :build do
+  sh "gem build analytics_instrumentation.gemspec"
+end
+
+desc 'Builds and installs the gem'
+task :install => :build do
+  sh "gem install analytics_instrumentation-#{AnalyticsInstrumentation::VERSION}"
+end
+
+desc 'Tags version, pushes to remote, and pushes gem'
+task :release => :build do
+  sh "git tag v#{AnalyticsInstrumentation::VERSION}"
+  sh "git push origin master"
+  sh "git push origin v#{AnalyticsInstrumentation::VERSION}"
+  sh "gem push analytics_instrumentation-#{AnalyticsInstrumentation::VERSION}.gem"
+  sh "rm analytics_instrumentation-#{AnalyticsInstrumentation::VERSION}.gem"
+end

data/lib/analytics_instrumentation/analytics_attribution.rb

@@ -0,0 +1,74 @@
+module AnalyticsAttribution
+  def add_attribution(props)
+    # Gather
+    attribution_data = {
+      first_external_referrer:  get_first_referrer,
+      latest_external_referrer: get_latest_referrer,
+      latest_utm:               get_latest_utm
+    }
+
+    # Persist
+    attribution_data.each do |k,v|
+      set_cookie k, v
+    end
+
+    # Merge
+    props.merge! attribution_data
+  end
+
+  private
+  def get_first_referrer
+    get_cookie("first_external_referrer") || get_latest_referrer
+  end
+
+  def get_latest_referrer
+    ref = request.referrer
+    bad_host = attribution_host(ref).nil?
+    our_host = attribution_host(ref) == attribution_host(request.original_url)
+    if ref.blank? || our_host || bad_host
+      get_cookie "latest_external_referrer"
+    else
+      attribution_host(ref)
+    end
+  end
+
+  def get_latest_utm
+    name    = params[:utm_campaign]
+    source  = params[:utm_source]
+    medium  = params[:utm_medium]
+    term    = params[:utm_term]
+    content = params[:utm_content]
+
+    if name.blank?
+      get_cookie 'latest_utm'
+    else
+      {
+        name:     name,
+        source:   source,
+        medium:   medium,
+        term:     term,
+        content:  content
+      }
+    end
+  end
+
+  def attribution_host(url)
+    return nil if url.nil?
+    uri = URI.parse(url)
+    uri.host && uri.host.sub(/\Awww\./,'').downcase
+  end
+
+  def set_cookie(key, value)
+    stored_value = value.is_a?(Hash) ? value.to_json : value
+    cookies[key] = stored_value
+  end
+
+  def get_cookie(key)
+    output = cookies[key]
+    if output && output[0] == "{"
+      JSON.parse(output) rescue nil
+    else
+      output
+    end
+  end
+end

data/lib/analytics_instrumentation/analytics_mapping.rb

@@ -0,0 +1,42 @@
+class AnalyticsMapping
+  def self.createMappings
+    # TODO: Reload this on Rails Auto-reload
+    mappings = {}
+    @mappingFiles = Dir.glob("config/analytics/*.yml")
+    for file in @mappingFiles
+      yaml = YAML.load_file(file)
+      mappings.merge! yaml
+    end
+    mappings
+  end
+
+  @@mappings = AnalyticsMapping.createMappings
+
+  def self.to_event(params, view_assigns)
+    methodName = "#{params[:controller]}##{params[:action]}"
+    analysis = @@mappings[methodName]
+
+    return nil if analysis.nil?
+
+    replaceAllTokens(analysis, params, view_assigns)
+
+    analysis
+  end
+
+  def self.replaceAllTokens(obj, params, view_assigns)
+    if obj.is_a? String
+      replaceTokens(obj, params, view_assigns)
+    elsif obj.is_a? Hash
+      obj.each {|k, v| replaceAllTokens(v, params, view_assigns)}
+    end
+  end
+
+  def self.replaceTokens(str, params, view_assigns)
+    return if str["@"].nil? && str["params["].nil?
+    properties = {}
+    view_assigns.each {|k, v| properties.instance_variable_set "@#{k}", v}
+    properties["params"] = params
+    result = ERB.new("<%= #{str} %>").result(properties.instance_eval {binding})
+    str[0..-1] = result
+  end
+end

data/lib/analytics_instrumentation/config.rb

@@ -0,0 +1,47 @@
+module AnalyticsInstrumentation
+  class Config
+    include ActiveModel::Validations
+
+    class Invalid < StandardError; end
+
+    attr_accessor :extra_event_properties
+    attr_accessor :custom_user_traits
+    attr_accessor :error_handler
+    attr_accessor :segment_write_key
+
+    validates_presence_of :segment_write_key
+
+    @@REQUIRED_CALLABLES = [
+      :extra_event_properties,
+      :custom_user_traits,
+      :error_handler
+    ]
+    validate do
+      @@REQUIRED_CALLABLES.each |callable| do
+        unless self.send(callable).respond_to?(:call)
+          errors.add(callable, "must be a callable object (eg. Proc)")
+        end
+      end
+    end
+
+    def initialize
+      self.extra_event_properties = -> {}
+      self.custom_user_traits     = -> {}
+      self.error_handler          = (msg) -> { raise }
+    end
+
+    def custom_user_traits(user)
+      self.custom_user_traits(user) || {}
+    end
+
+    def extra_event_properties
+      self.extra_event_properties() || {}
+    end
+
+    def intercom?
+      Intercom rescue false
+    end
+
+    private
+  end
+end

data/lib/analytics_instrumentation/version.rb

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

data/lib/analytics_instrumentation.rb

@@ -0,0 +1,189 @@
+require 'analytics_instrumentation/analytics_attribution'
+require 'analytics_instrumentation/analytics_mapping'
+
+module AnalyticsInstrumentation
+  include AnalyticsAttribution
+
+  class << self
+    def included(base)
+      @segment = Segment::Analytics.new({
+          write_key:  @config.segment_write_key,
+          on_error:   @config.error_handler
+      })
+
+      base.class_eval do
+        base.send(:after_filter, :analyticsLogPageView)
+        base.send(:after_filter, :analyticsCheckSessionStart)
+      end
+    end
+
+    def configure(&proc)
+      @config ||= Config.new
+      yield @config
+
+      unless @config.valid?
+        errors = @config.errors.full_messages.join(', ')
+        raise Config::Invalid.new(errors)
+      end
+    end
+  end
+
+  def analyticsCheckSessionStart
+    begin
+      return if skip_analytics?
+      if current_user
+        if !session[:last_seen] || session[:last_seen] < 30.minutes.ago
+          analyticsTrackEvent("Session Start")
+          if @config.intercom? && Rails.env.production?
+            Intercom.post("https://api.intercom.io/users", {user_id:current_user.id, new_session:true})
+          end
+        end
+        session[:last_seen] = Time.now
+      else
+        if session[:last_seen_logged_out].nil? || session[:last_seen_logged_out] < 30.minutes.ago
+          analyticsTrackEvent("Session Start")
+        end
+        session[:last_seen_logged_out] = Time.now
+      end
+    rescue => e
+      @config.error_handler(e, "Analytics Check Session Crash: #{request.filtered_path}")
+    end
+  end
+
+  def analyticsLogPageView
+    begin
+      return if skip_analytics?
+      return if self.status >= 400
+
+      page_view_event = AnalyticsMapping.to_event(params, self.view_assigns)
+
+      if page_view_event
+        if current_user
+          analyticsSetPerson(current_user)
+        end
+        add_attribution page_view_event[:parameters]
+        analyticsTrackEvent page_view_event[:name], page_view_event[:parameters]
+        analyticsStoreOriginatingPage page_view_event
+      end
+
+      properties = {
+        page: request.path
+      }
+      properties.merge! analyticsSuperProperties
+      analyticsTrackEvent "Page View", properties
+    rescue => e
+      @config.error_handler(e, "Analytics Crash: #{request.filtered_path}")
+    end
+  end
+
+  def analyticsStoreOriginatingPage(page_view_event)
+    if !request.xhr?
+      session["previous-page-type"]       = page_view_event[:name]
+      session["previous-page-identifier"] = page_view_event[:page_identifier]
+    end
+  end
+
+  def analyticsApplyOriginatingPage(properties)
+    properties["Originating Page Identifier"] = session["previous-page-identifier"]
+    properties["Originating Page Type"]       = session["previous-page-type"]
+  end
+
+  def analyticsAliasUser(user_id)
+    return if skip_analytics?
+
+    aliasProperties = {
+      previous_id: session[:analytics_id],
+      user_id: user_id
+    }
+
+    logger.debug "Analytics.alias #{aliasProperties}"
+    @segment.alias(aliasProperties)
+    @segment.flush
+  end
+
+  def analyticsSetPerson(user)
+    return if skip_analytics?
+
+    properties = {
+      user_id: user.id,
+      traits: @config.custom_user_traits(user)
+    }
+
+    logger.debug "Analytics.identify #{JSON.pretty_generate(properties)}"
+    @segment.identify(properties)
+  end
+
+  def analyticsSuperProperties
+    superProperties = {
+      "Raw Analytics ID" => raw_analytics_id,
+      "Ajax" => !request.xhr?.nil?
+    }
+    if current_user
+      superProperties.merge!({
+        "User Created At" => current_user.created_at,
+        "Username" => current_user.try(:username),
+        "Full name" => current_user.try(:full_name),
+        "User ID" => current_user.id,
+        "Login Provider" => current_user.try(:provider) || "Email"
+      })
+    end
+    superProperties
+  end
+
+  def analyticsTrackEvent(name, properties={})
+    return if skip_analytics?
+
+    properties ||= {}
+
+    properties["logged_in"] = !!current_user
+    properties["source"]    = params[:source] if params[:source]
+
+    properties.merge! analyticsSuperProperties
+    properties.merge! @config.extra_event_properties
+
+    analyticsApplyOriginatingPage properties
+
+    analyticsProperties = {
+      user_id: analyticsID,
+      event: name,
+      properties: properties,
+      context: {
+        userAgent: request.env['HTTP_USER_AGENT'],
+        ip: request.remote_ip,
+        'Google Analytics' => {
+          clientId: googleAnalyticsID
+        }
+      }
+    }
+
+    logger.debug "Analytics.track #{JSON.pretty_generate(analyticsProperties)}"
+    @segment.track(analyticsProperties)
+  end
+
+  def raw_analytics_id
+    session[:analytics_id] ||= (rand * 1000000000000000).to_i
+    session[:analytics_id]
+  end
+
+  def analyticsID
+    if current_user then return current_user.id end
+    raw_analytics_id
+  end
+
+  private
+  def googleAnalyticsID
+    ck = cookies[:_ga]
+    return "1.1" if ck.nil?
+    parts = ck.split(".")
+    "#{parts[2]}.#{parts[3]}"
+  end
+
+  def skip_analytics?
+    return true if Rails.env.test?
+    return true if request.bot?
+    return true if request.user_agent.nil?
+    bad_strings = ["http:", "https:", "twitterbot", "bingbot", "googlebot", "gediapartners-google"]
+    return true if bad_strings.any? { |s| !request.user_agent.downcase.index(s).nil? }
+    false
+  end
+end

data/lib/config/routes.rb

@@ -0,0 +1,7 @@
+# TODO: Not namespace this
+
+CanopyBackend::Application.routes.draw do
+
+  post "api/analytics_event" => "analytics_implementation#analytics_event", as: :analytics_event
+
+end

data/lib/controllers/analytics_implementation_controller.rb

@@ -0,0 +1,11 @@
+class AnalyticsImplementationController < ApplicationController
+
+  # Exposes an endpoint to which one can ajax handwritten events.
+  def analytics_event
+    name = params[:name]
+    properties = params[:properties]
+    analyticsTrackEvent(name, properties)
+    render text: ""
+  end
+
+end

data/lib/controllers/application_controller.rb

@@ -0,0 +1,3 @@
+class ApplicationController < ActionController::Base
+  include AnalyticsInstrumentation
+end

data/lib/tasks/analytics_instrumentation_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :analytics_instrumentation do
+#   # Task goes here
+# end

data/test/analytics_instrumentation_test.rb

@@ -0,0 +1,7 @@
+require 'test_helper'
+
+class AnalyticsInstrumentationTest < ActiveSupport::TestCase
+  test "truth" do
+    assert_kind_of Module, AnalyticsInstrumentation
+  end
+end