Introduce event tags (#30)

This introduces event tags to the API. Event tags are included as eventFeatures in the event payload.

Author: onufryk

lib/optimizely.rb

@@ -162,21 +162,29 @@ def get_variation(experiment_key, user_id, attributes = nil)
       @config.get_variation_key_from_id(experiment_key, variation_id)
     end
 
-    def track(event_key, user_id, attributes = nil, event_value = nil)
+    def track(event_key, user_id, attributes = nil, event_tags = nil)
       # Send conversion event to Optimizely.
       #
       # event_key - Goal key representing the event which needs to be recorded.
       # user_id - String ID for user.
       # attributes - Hash representing visitor attributes and values which need to be recorded.
-      # event_value - Value associated with the event. Can be used to represent revenue in cents.
+      # event_tags - Hash representing metadata associated with the event.
 
       unless @is_valid
         logger = SimpleLogger.new
         logger.log(Logger::ERROR, InvalidDatafileError.new('track').message)
         return nil
       end
 
+      if event_tags and event_tags.is_a? Numeric
+        event_tags = {
+          'revenue' => event_tags
+        }
+        @logger.log(Logger::WARN, 'Event value is deprecated in track call. Use event tags to pass in revenue value instead.')
+      end
+
       return nil if attributes && !attributes_valid?(attributes)
+      return nil if event_tags && !event_tags_valid?(event_tags)
 
       experiment_ids = @config.get_experiment_ids_for_goal(event_key)
       if experiment_ids.empty?
@@ -202,7 +210,7 @@ def track(event_key, user_id, attributes = nil, event_value = nil)
       end
 
       conversion_event = @event_builder.create_conversion_event(event_key, user_id, attributes,
-                                                                event_value, valid_experiment_keys)
+                                                                event_tags, valid_experiment_keys)
       @logger.log(Logger::INFO,
                   'Dispatching conversion event to URL %s with params %s.' % [conversion_event.url,
                                                                               conversion_event.params])
@@ -251,6 +259,15 @@ def attributes_valid?(attributes)
       true
     end
 
+    def event_tags_valid?(event_tags)
+      unless Helpers::Validator.event_tags_valid?(event_tags)
+        @logger.log(Logger::ERROR, 'Provided event tags are in an invalid format.')
+        @error_handler.handle_error(InvalidEventTagFormatError)
+        return false
+      end
+      true
+    end
+
     def validate_inputs(datafile, skip_json_validation)
       unless skip_json_validation
         raise InvalidInputError.new('datafile') unless Helpers::Validator.datafile_valid?(datafile)

lib/optimizely/event_builder.rb

@@ -16,6 +16,7 @@
 require_relative './audience'
 require_relative './params'
 require_relative './version'
+require_relative '../optimizely/helpers/event_tag_utils'
 
 module Optimizely
   class Event
@@ -89,20 +90,21 @@ def create_impression_event(experiment_key, variation_id, user_id, attributes)
       Event.new(:post, IMPRESSION_EVENT_ENDPOINT, @params, POST_HEADERS)
     end
 
-    def create_conversion_event(event_key, user_id, attributes, event_value, experiment_keys)
+    def create_conversion_event(event_key, user_id, attributes, event_tags, experiment_keys)
       # Create conversion Event to be sent to the logging endpoint.
       #
       # event_key - Event key representing the event which needs to be recorded.
       # user_id - ID for user.
       # attributes - Hash representing user attributes and values which need to be recorded.
-      # event_value - Value associated with the event. Can be used to represent revenue in cents.
+      # event_tags - Hash representing metadata associated with the event.
       # experiment_keys - Array of valid experiment keys for the event
       #
       # Returns event hash encapsulating the conversion event.
 
       @params = {}
       add_common_params(user_id, attributes)
-      add_conversion_event(event_key, event_value)
+      add_conversion_event(event_key)
+      add_event_tags(event_tags)
       add_layer_states(user_id, experiment_keys)
       Event.new(:post, CONVERSION_EVENT_ENDPOINT, @params, POST_HEADERS)
     end
@@ -161,26 +163,47 @@ def add_decision(experiment_key, variation_id)
       }
     end
 
-    def add_conversion_event(event_key, event_value)
+    def add_event_tags(event_tags)
+      @params['eventFeatures'] ||= []
+      @params['eventMetrics'] ||= []
+
+      return if event_tags.nil?
+
+      event_tags.each_pair do |event_tag_key, event_tag_value|
+        next if event_tag_value.nil?
+
+        event_feature = {
+          'id' => event_tag_key,
+          'type' => 'custom',
+          'value' => event_tag_value,
+          'shouldIndex' => false,
+        }
+        @params['eventFeatures'].push(event_feature)
+
+      end
+
+      event_value = Helpers::EventTagUtils.get_revenue_value(event_tags)
+
+      if event_value
+        event_metric = {
+          'name' => 'revenue',
+          'value' => event_value
+        }
+        @params['eventMetrics'].push(event_metric)
+      end
+
+    end
+
+    def add_conversion_event(event_key)
       # Add conversion event information to the event.
       #
       # event_key - Event key representing the event which needs to be recorded.
-      # event_value - Value associated with the event. Can be used to represent revenue in cents.
 
       event_id = @config.event_key_map[event_key]['id']
       event_name = @config.event_key_map[event_key]['key']
 
       @params['eventEntityId'] = event_id
-      @params['eventFeatures'] = []
       @params['eventName'] = event_name
-      @params['eventMetrics'] = []
-
-      if event_value
-        @params['eventMetrics'].push({
-          'name' => 'revenue',
-          'value' => event_value,
-        })
-      end
     end
 
     def add_layer_states(user_id, experiment_keys)
@@ -241,18 +264,21 @@ def create_impression_event(experiment_key, variation_id, user_id, attributes)
       Event.new(:get, sprintf(OFFLINE_API_PATH, project_id: @params[Params::PROJECT_ID]), @params, {})
     end
 
-    def create_conversion_event(event_key, user_id, attributes, event_value, experiment_keys)
+    def create_conversion_event(event_key, user_id, attributes, event_tags, experiment_keys)
       # Create conversion Event to be sent to the logging endpoint.
       #
       # event_key - Goal key representing the event which needs to be recorded.
       # user_id - ID for user.
       # attributes - Hash representing user attributes and values which need to be recorded.
-      # event_value - Value associated with the event. Can be used to represent revenue in cents.
+      # event_tags - Hash representing metadata associated with the event.
       # experiment_keys - Array of valid experiment keys for the goal
       #
       # Returns event hash encapsulating the conversion event.
 
       @params = {}
+
+      event_value = Helpers::EventTagUtils.get_revenue_value(event_tags)
+
       add_common_params(user_id, attributes)
       add_conversion_goal(event_key, event_value)
       add_experiment_variation_params(user_id, experiment_keys)

lib/optimizely/exceptions.rb

@@ -40,6 +40,14 @@ def initialize(msg = 'Attributes provided are in an invalid format.')
     end
   end
 
+  class InvalidEventTagFormatError < Error
+    # Raised when attributes are provided in an invalid format (e.g. not a Hash)
+
+    def initialize(msg = 'Event tags provided are in an invalid format.')
+      super
+    end
+  end
+
   class InvalidExperimentError < Error
     # Raised when an invalid experiment key is provided
 

lib/optimizely/helpers/event_tag_utils.rb

@@ -0,0 +1,57 @@
+#
+#    Copyright 2017, Optimizely and contributors
+#
+#    Licensed under the Apache License, Version 2.0 (the "License");
+#    you may not use this file except in compliance with the License.
+#    You may obtain a copy of the License at
+#
+#        http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS,
+#    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#    See the License for the specific language governing permissions and
+#    limitations under the License.
+#
+require 'optimizely/logger'
+require 'optimizely/helpers/validator'
+
+module Optimizely
+  module Helpers
+    module EventTagUtils
+      module_function
+
+      def get_revenue_value(event_tags)
+        # Grab the revenue value from the event tags. "revenue" is a reserved keyword.
+        #
+        # event_tags - Hash representing metadata associated with the event.
+        # Returns revenue value as an integer number
+        # Returns nil if revenue can't be retrieved from the event tags.
+
+        if event_tags.nil? or !Helpers::Validator.attributes_valid?(event_tags)
+          return nil
+        end
+
+        unless event_tags.has_key?('revenue')
+          return nil
+        end
+
+        logger = SimpleLogger.new
+        raw_value = event_tags['revenue']
+
+        unless raw_value.is_a? Numeric
+          logger.log(Logger::WARN, "Failed to parse revenue value #{raw_value} from event tags.")
+          return nil
+        end
+
+        if raw_value.is_a? Float
+          logger.log(Logger::WARN, "Failed to parse revenue value #{raw_value} from event tags.")
+          return nil
+        end
+
+        logger.log(Logger::INFO, "Parsed revenue value #{raw_value} from event tags.")
+        raw_value
+      end
+    end
+  end
+end

lib/optimizely/helpers/validator.rb

@@ -32,6 +32,16 @@ def attributes_valid?(attributes)
         attributes.is_a?(Hash)
       end
 
+      def event_tags_valid?(event_tags)
+        # Determines if provided event tags are valid.
+        #
+        # event_tags - Event tags to be validated.
+        #
+        # Returns boolean depending on validity of event tags.
+
+        event_tags.is_a?(Hash)
+      end
+
       def datafile_valid?(datafile)
         # Determines if a given datafile is valid.
         #