staccato 0.1.1 → 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 9a674a0fa88901074b28c03b98647b7751322412
+  data.tar.gz: d6db8298721e606f0855c54959eb42537e0d496c
+SHA512:
+  metadata.gz: 323fdd8c54466b98790b5f446c1d20464bb3ce8271a2785881d49d4edf3257602367e05cdfdc38db84d21d5fc5164684c1b25f87d422ee35933c5da7a840b0d5
+  data.tar.gz: 5b290b2d0602444e10562619feef4763161e546aea5dedad33ad0c3eb680633a22566cc37da718674a2587515fd4921e6b86c044a02c61f4a5fb9d273feaef3b

data/.travis.yml

@@ -4,4 +4,5 @@ rvm:
   - 1.9.3
   - 2.0.0
   - 2.1.0
+  - 2.2.0
 script: bundle exec rake

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+## Staccato 0.2.0 ##
+
+*   Enhanced Ecommerce Measurements
+*   Measurable module for further extension of hits
+*   New global hit options for ecommerce
+
+    *Tony Pitale <@tpitale>*
+
 ## Staccato 0.1.1 ##
 
 *   fixes NoopTracker when track! is called on a hit *martin1keogh*

data/README.md

@@ -133,7 +133,10 @@ Staccato::Hit::GLOBAL_OPTIONS.keys # =>
  :application_id,
  :application_installer_id,
  :experiment_id,
- :experiment_variant]
+ :experiment_variant,
+ :product_action,
+ :product_action_list,
+ :promotion_action]
 ```
 
 Boolean options like `anonymize_ip` will be converted from `true`/`false` into `1`/`0` as per the tracking API docs.
@@ -200,13 +203,218 @@ tracker.pageview(path: '/videos/123')
 tracker.pageview(path: '/videos/987')
 ```
 
-## Google Documentation
+## Additional Measurements ##
+
+Additional Measurements can be added to any Hit type, but most commonly used with pageviews or events. The current set of measurements is for handling [Enhanced Ecommerce](https://developers.google.com/analytics/devguides/collection/protocol/v1/devguide#enhancedecom) measurements. I've grouped these into ImpressionList, Product, ProductImpression, Promotion, Transaction, Checkout, and CheckoutOption (w/ ImpressionList). Each can be added and combined – per Google's documentation – onto an existing Hit.
+
+**Note:** Certain Measurements require an `index`. This is an integer (usually) between 1 and 200 inclusive.
+
+**Note:** Certain Measurements require a `product_action` to be set. This is a global option, and should be set on the original hit. The `product_action` can be any one of:
+
+* `detail`
+* `click`
+* `add`
+* `remove`
+* `checkout`
+* `checkout_option`
+* `purchase`
+* `refund`
+
+### Transaction w/ Product ###
+
+Using a pageview to track a transaction with a product (using the 'purchase' as the `product_action`:
+
+```ruby
+pageview = tracker.build_pageview(path: '/receipt', hostname: 'mystore.com', title: 'Your Receipt', product_action: 'purchase')
+
+pageview.add_measurement(:transaction, {
+  transaction_id: 'T12345',
+  affiliation: 'Your Store',
+  revenue: 37.39,
+  tax: 2.85,
+  shipping: 5.34,
+  currency: 'USD',
+  coupon_code: 'SUMMERSALE'
+})
+
+pageview.add_measurement(:product, {
+  index: 1, # this is our first product, value may be 1-200
+  id: 'P12345',
+  name: 'T-Shirt',
+  category: 'Apparel',
+  brand: 'Your Brand',
+  variant: 'Purple',
+  quantity: 2,
+  position: 1,
+  price: 14.60,
+  coupon_code: 'ILUVTEES'
+})
+
+pageview.track!
+```
+
+### Transaction Refund ###
+
+The combination of `product_action: 'refund'` and `transaction` measurement setting a matching `id` to a previous transaction.
+
+```ruby
+event = tracker.build_event(category: 'order', action: 'refund', non_interactive: true, product_action: 'refund')
+
+event.add_measurement(:transaction, id: 'T12345')
+
+event.track!
+```
+
+### Transaction & Product Refund ###
+
+The combination of `product_action: 'refund'` and `transaction` measurement setting a matching `id` to a previous transaction. You can also specify a product (or products, using `index`) with a `quantity` (for partial refunds) to refund.
+
+```ruby
+event = tracker.build_event(category: 'order', action: 'refund', non_interactive: true, product_action: 'refund')
+
+event.add_measurement(:transaction, id: 'T12345')
+event.add_measurement(:product, index: 1, id: 'P12345', quantity: 1)
+
+event.track!
+```
+
+### Promotion Impression ###
+
+```ruby
+pageview = tracker.build_pageview(path: '/search', hostname: 'mystore.com', title: 'Search Results')
+
+pageview.add_measurement(:promotion, {
+  index: 1,
+  id: 'PROMO_1234',
+  name: 'Summer Sale',
+  creative: 'summer_sale_banner',
+  position: 'banner_1'
+})
+
+pageview.track!
+```
+
+### Promotion Click ###
+
+Promotion also supports a `promotion_action`, similar to `product_action`. This is another global option on `Hit`.
+
+```ruby
+event = tracker.build_event(category: 'promotions', action: 'click', label: 'internal', promotion_action: 'click')
+
+event.add_measurement(:promotion, {
+  index: 1,
+  id: 'PROMO_1234',
+  name: 'Summer Sale',
+  creative: 'summer_sale_banner',
+  position: 'banner_1'
+})
+
+event.track!
+```
+
+### Product Click ###
+
+```ruby
+event = tracker.build_event(category: 'search', action: 'click', label: 'results', product_action: 'click', product_action_list: 'Search Results')
+
+event.add_measurement(:product, {
+  index: 1,
+  id: 'P12345',
+  name: 'T-Shirt',
+  category: 'Apparel',
+  brand: 'Your Brand',
+  variant: 'Purple',
+  quantity: 2,
+  position: 1,
+  price: 14.60,
+  coupon_code: 'ILUVTEES'
+})
+
+event.track!
+```
+
+### Checkout ###
+
+```ruby
+pageview = tracker.build_pageview(path: '/checkout', hostname: 'mystore.com', title: 'Complete Your Checkout', product_action: 'checkout')
+
+pageview.add_measurement(:product, {
+  index: 1, # this is our first product, value may be 1-200
+  id: 'P12345',
+  name: 'T-Shirt',
+  category: 'Apparel',
+  brand: 'Your Brand',
+  variant: 'Purple',
+  quantity: 2,
+  position: 1,
+  price: 14.60,
+  coupon_code: 'ILUVTEES'
+})
+
+pageview.add_measurement(:checkout, {
+  step: 1,
+  step_option: 'Visa'
+})
+
+pageview.track!
+```
+
+### Checkout Option ###
+
+```ruby
+event = tracker.build_event(category: 'checkout', action: 'option', non_interactive: true, product_action: 'checkout_option')
+
+event.add_measurement(:checkout_options, {
+  step: 2,
+  step_option: 'Fedex'
+})
+
+event.track!
+```
+
+### Impression List & Product Impression ###
+
+```ruby
+pageview = tracker.build_pageview(path: '/home', hostname: 'mystore.com', title: 'Home Page')
+
+pageview.add_measurement(:impression_list, index: 1, name: 'Search Results')
+
+pageview.add_measurement(:product_impression, {
+  index: 1,
+  list_index: 1, # match the impression_list above
+  id: 'P12345',
+  name: 'T-Shirt',
+  category: 'Apparel',
+  brand: 'Your Brand',
+  variant: 'Purple',
+  position: 1,
+  price: 14.60
+})
+
+pageview.add_measurement(:impression_list, index: 2, name: 'Recommendations')
+
+pageview.add_measurement(:product_impression, {
+  index: 1,
+  list_index: 2,
+  name: 'Yellow Tee'
+})
+
+pageview.add_measurement(:product_impression, {
+  index: 2,
+  list_index: 2,
+  name: 'Red Tee'
+})
+
+pageview.track!
+```
+
+## Google Documentation ##
 
 https://developers.google.com/analytics/devguides/collection/protocol/v1/devguide
 https://developers.google.com/analytics/devguides/collection/protocol/v1/reference
 https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters
 
-## Contributing
+## Contributing ##
 
 1. Fork it
 2. Create your feature branch (`git checkout -b my-new-feature`)

data/lib/staccato.rb

@@ -38,6 +38,7 @@ module Staccato
   end
 end
 
+require 'staccato/boolean_helpers'
 require 'staccato/option_set'
 require 'staccato/hit'
 require 'staccato/pageview'
@@ -48,3 +49,4 @@ require 'staccato/timing'
 require 'staccato/transaction'
 require 'staccato/transaction_item'
 require 'staccato/tracker'
+require 'staccato/measurement'

data/lib/staccato/boolean_helpers.rb

@@ -0,0 +1,40 @@
+# Collection of methods for converting to
+#   google's boolean integers from ruby's booleans
+module BooleanHelpers
+  # Convert each boolean in the hash to integer
+  #   if it is a boolean field
+  # @param hash [Hash]
+  # @return [Hash]
+  def convert_booleans(hash)
+    hash.each_pair.with_object({}, &method(:convert_boolean))
+  end
+
+  # Method to convert a single field from bool to int
+  # @param hash [#[]=] the collector object
+  def convert_boolean((k,v), hash)
+    hash[k] = boolean_field?(k) ? integer_for(v) : v
+  end
+
+  # Is this key one of the boolean fields
+  # @param key [Symbol] field key
+  # @return [Boolean]
+  def boolean_field?(key)
+    boolean_fields.include?(key)
+  end
+
+  # Convert a value to appropriate int
+  # @param value [nil, true, false, Integer]
+  # @return [nil, Integer]
+  def integer_for(value)
+    case value
+    when Integer
+      value
+    when TrueClass
+      1
+    when FalseClass
+      0
+    when NilClass
+      nil
+    end
+  end
+end

data/lib/staccato/exception.rb

@@ -15,8 +15,10 @@ module Staccato
       :exception
     end
 
+    # Boolean fields from Hit plus exception-specific field
+    # @return [Array<Symbol>]
     def boolean_fields
-      super << :fatal
+      super + [:fatal]
     end
   end
 end

data/lib/staccato/hit.rb

@@ -18,6 +18,7 @@ module Staccato
       end
     end
 
+    # Hit global options may be set on any hit type options
     GLOBAL_OPTIONS = {
       anonymize_ip: 'aip', # boolean
       queue_time: 'qt', # integer
@@ -63,14 +64,22 @@ module Staccato
 
       # Content Experiments
       experiment_id: 'xid',
-      experiment_variant: 'xvar'
-    }
+      experiment_variant: 'xvar',
 
+      # Product
+      product_action: 'pa',
+      product_action_list: 'pal',
+
+      # Promotion
+      promotion_action: 'promoa'
+    }.freeze
+
+    # Fields which should be converted to boolean for google
     BOOLEAN_FIELDS = [
       :non_interactive,
       :anonymize_ip,
       :java_enabled
-    ]
+    ].freeze
 
     # sets up a new hit
     # @param tracker [Staccato::Tracker] the tracker to collect to
@@ -88,31 +97,60 @@ module Staccato
 
     # collects the parameters from options for this hit type
     def params
-      base_params.
-        merge(tracker_default_params).
-        merge(global_options_params).
-        merge(hit_params).
-        merge(custom_dimensions).
-        merge(custom_metrics).
-        reject {|_,v| v.nil?}
-    end
-
-    def add_custom_dimension(position, value)
-      self.custom_dimensions["cd#{position}"] = value
-    end
-
+      {}.
+      merge!(base_params).
+      merge!(tracker_default_params).
+      merge!(global_options_params).
+      merge!(hit_params).
+      merge!(custom_dimensions).
+      merge!(custom_metrics).
+      merge!(measurement_params).
+      reject {|_,v| v.nil?}
+    end
+
+    # Set a custom dimension value at an index
+    # @param index [Integer]
+    # @param value
+    def add_custom_dimension(index, value)
+      self.custom_dimensions["cd#{index}"] = value
+    end
+
+    # Custom dimensions for this hit
+    # @return [Hash]
     def custom_dimensions
       @custom_dimensions ||= {}
     end
 
-    def add_custom_metric(position, value)
-      self.custom_metrics["cm#{position}"] = value
+    # Set a custom metric value at an index
+    # @param index [Integer]
+    # @param value
+    def add_custom_metric(index, value)
+      self.custom_metrics["cm#{index}"] = value
     end
 
+    # Custom metrics for this hit
+    # @return [Hash]
     def custom_metrics
       @custom_metrics ||= {}
     end
 
+    # Add a measurement by its symbol name with options
+    # 
+    # @param key [Symbol] any one of the measurable classes lookup key
+    # @param options [Hash] options for the measurement
+    def add_measurement(key, options = {})
+      self.measurements << Measurement.lookup(key).new(options)
+    end
+
+    # Measurements for this hit
+    # @return [Array<Measurable>]
+    def measurements
+      @measurements ||= []
+    end
+
+    # Returns the value for session control
+    #   based on options for session_start/_end
+    # @return ['start', 'end']
     def session_control
       case
       when options[:session_start], options[:start_session]
@@ -128,34 +166,12 @@ module Staccato
     end
 
     private
-    def convert_booleans(hash)
-      hash.each_pair.with_object({}, &method(:convert_boolean))
-    end
-
-    def convert_boolean((k,v), hash)
-      hash[k] = boolean_field?(k) ? integer_for(v) : v
-    end
-
+    # @private
     def boolean_fields
       BOOLEAN_FIELDS
     end
 
-    def boolean_field?(key)
-      boolean_fields.include?(key)
-    end
-
-    def integer_for(value)
-      case value
-      when Integer
-        value
-      when TrueClass
-        1
-      when FalseClass
-        0
-      when NilClass
-        nil
-      end
-    end
+    include BooleanHelpers
 
     # @private
     def base_params
@@ -199,5 +215,10 @@ module Staccato
         }.compact
       ]
     end
+
+    # @private
+    def measurement_params
+      measurements.dup.map!(&:params).inject({}, &:merge!)
+    end
   end
 end