optimizely-sdk 0.0.12

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 901e065c0246efcd95969e7b04b84dc9aab2d9e7
+  data.tar.gz: c7a3e774508632a1161d827178e49ffa039d560f
+SHA512:
+  metadata.gz: 4ff15bc14a26529b3332e41b772befc96559e0d9230d3d41c7c198f757f2a7aede6ec5030064421a9cb87ca676f76d997310ac8211af9fc36554713eb262413c
+  data.tar.gz: 9b6ccd16b467ee4d4f2092e775ef73218fa6ac44f70db80f670884c74aebae09f9623353431806d0f2620e08d4471f6d47cf522d1a32274ac046e57286668819

data/lib/optimizely.rb

@@ -0,0 +1,179 @@
+require_relative 'optimizely/audience'
+require_relative 'optimizely/bucketer'
+require_relative 'optimizely/error_handler'
+require_relative 'optimizely/event_builder'
+require_relative 'optimizely/event_dispatcher'
+require_relative 'optimizely/exceptions'
+require_relative 'optimizely/helpers/group'
+require_relative 'optimizely/helpers/validator'
+require_relative 'optimizely/logger'
+require_relative 'optimizely/project_config'
+
+module Optimizely
+  class Project
+    attr_accessor :config
+    attr_accessor :bucketer
+    attr_accessor :event_builder
+    attr_accessor :event_dispatcher
+    attr_accessor :logger
+    attr_accessor :error_handler
+
+    def initialize(datafile, event_dispatcher = nil, logger = nil, error_handler = nil)
+      # Constructor for Projects.
+      #
+      # datafile - JSON string representing the project.
+      # event_dispatcher - Provides a dispatch_event method which if given a URL and params sends a request to it.
+      # logger - Optional param which provides a log method to log messages. By default nothing would be logged.
+      # error_handler - Optional param which provides a handle_error method to handle exceptions.
+      #                 By default all exceptions will be suppressed.
+
+      @logger = logger || NoOpLogger.new
+      @error_handler = error_handler || NoOpErrorHandler.new
+      @event_dispatcher = event_dispatcher || EventDispatcher.new
+      validate_inputs(datafile)
+
+      @config = ProjectConfig.new(datafile, @logger, @error_handler)
+      @bucketer = Bucketer.new(@config)
+      @event_builder = EventBuilder.new(@config, @bucketer)
+    end
+
+    def activate(experiment_key, user_id, attributes = nil)
+      # Buckets visitor and sends impression event to Optimizely.
+      #
+      # experiment_key - Experiment which needs to be activated.
+      # user_id - String ID for user.
+      # attributes - Hash representing user attributes and values to be recorded.
+      #
+      # Returns variation key representing the variation the user will be bucketed in.
+      # Returns nil if experiment is not Running or if user is not in experiment.
+
+      if attributes && !attributes_valid?(attributes)
+        @logger.log(Logger::INFO, "Not activating user '#{user_id}'.")
+        return nil
+      end
+
+      unless preconditions_valid?(experiment_key, user_id, attributes)
+        @logger.log(Logger::INFO, "Not activating user '#{user_id}'.")
+        return nil
+      end
+
+      variation_id = @bucketer.bucket(experiment_key, user_id)
+
+      if not variation_id
+        @logger.log(Logger::INFO, "Not activating user '#{user_id}'.")
+        return nil
+      end
+
+      # Create and dispatch impression event
+      impression_event = @event_builder.create_impression_event(experiment_key, variation_id, user_id, attributes)
+      @logger.log(Logger::INFO,
+                  'Dispatching impression event to URL %s with params %s.' % [impression_event.url,
+                                                                              impression_event.params])
+      @event_dispatcher.dispatch_event(impression_event.url, impression_event.params)
+
+      @config.get_variation_key_from_id(experiment_key, variation_id)
+    end
+
+    def get_variation(experiment_key, user_id, attributes = nil)
+      # Gets variation where visitor will be bucketed.
+      #
+      # experiment_key - Experiment for which visitor variation needs to be determined.
+      # user_id - String ID for user.
+      # attributes - Hash representing user attributes.
+      #
+      # Returns variation key where visitor will be bucketed.
+      # Returns nil if experiment is not Running or if user is not in experiment.
+
+      if attributes && !attributes_valid?(attributes)
+        @logger.log(Logger::INFO, "Not activating user '#{user_id}.")
+        return nil
+      end
+
+      unless preconditions_valid?(experiment_key, user_id, attributes)
+        @logger.log(Logger::INFO, "Not activating user '#{user_id}.")
+        return nil
+      end
+
+      variation_id = @bucketer.bucket(experiment_key, user_id)
+      @config.get_variation_key_from_id(experiment_key, variation_id)
+    end
+
+    def track(event_key, user_id, attributes = nil, event_value = 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.
+
+      # Create and dispatch conversion event
+
+      return nil if attributes && !attributes_valid?(attributes)
+
+      experiment_ids = @config.get_experiment_ids_for_goal(event_key)
+      if experiment_ids.empty?
+        @config.logger.log(Logger::INFO, "Not tracking user '#{user_id}' for experiment '#{experiment_key}'.")
+        return nil
+      end
+
+      # Filter out experiments that are not running or that do not include the user in audience conditions
+      valid_experiment_keys = []
+      experiment_ids.each do |experiment_id|
+        experiment_key = @config.experiment_id_map[experiment_id]['key']
+        unless preconditions_valid?(experiment_key, user_id, attributes)
+          @config.logger.log(Logger::INFO, "Not tracking user '#{user_id}' for experiment '#{experiment_key}'.")
+          next
+        end
+        valid_experiment_keys.push(experiment_key)
+      end
+
+      conversion_event = @event_builder.create_conversion_event(event_key, user_id, attributes,
+                                                                event_value, valid_experiment_keys)
+      @logger.log(Logger::INFO,
+                  'Dispatching conversion event to URL %s with params %s.' % [conversion_event.url,
+                                                                              conversion_event.params])
+      @event_dispatcher.dispatch_event(conversion_event.url, conversion_event.params)
+    end
+
+    private
+
+    def preconditions_valid?(experiment_key, user_id, attributes)
+      # Validates preconditions for bucketing a user.
+      #
+      # experiment_key - String key for an experiment.
+      # user_id - String ID of user.
+      # attributes - Hash of user attributes.
+      #
+      # Returns boolean representing whether all preconditions are valid.
+
+      unless @config.experiment_running?(experiment_key)
+        @logger.log(Logger::INFO, "Experiment '#{experiment_key} is not running.")
+        return false
+      end
+
+      unless Audience.user_in_experiment?(@config, experiment_key, attributes)
+        @logger.log(Logger::INFO,
+                    "User '#{user_id} does not meet the conditions to be in experiment '#{experiment_key}.")
+        return false
+      end
+
+      true
+    end
+
+    def attributes_valid?(attributes)
+      unless Helpers::Validator.attributes_valid?(attributes)
+        @logger.log(Logger::ERROR, 'Provided attributes are in an invalid format.')
+        @error_handler.handle_error(InvalidAttributeFormatError)
+        return false
+      end
+      true
+    end
+
+    def validate_inputs(datafile)
+      raise InvalidDatafileError unless Helpers::Validator.datafile_valid?(datafile)
+      raise InvalidLoggerError unless Helpers::Validator.logger_valid?(@logger)
+      raise InvalidErrorHandlerError unless Helpers::Validator.error_handler_valid?(@error_handler)
+      raise InvalidEventDispatcherError unless Helpers::Validator.event_dispatcher_valid?(@event_dispatcher)
+    end
+  end
+end

data/lib/optimizely/audience.rb

@@ -0,0 +1,37 @@
+require 'json'
+require_relative './condition'
+
+module Optimizely
+  module Audience
+    module_function
+
+    def user_in_experiment?(config, experiment_key, attributes)
+      # Determine for given experiment if user satisfies the audiences for the experiment.
+      #
+      # config - Representation of the Optimizely project config.
+      # experiment_key - Key representing experiment for which visitor is to be bucketed.
+      # attributes - Hash representing user attributes which will be used in determining if
+      #              the audience conditions are met.
+      #
+      # Returns boolean representing if user satisfies audience conditions for any of the audiences or not.
+
+      audience_ids = config.get_audience_ids_for_experiment(experiment_key)
+
+      # Return true if there are no audiences
+      return true if audience_ids.empty?
+
+      # Return false if there are audiences but no attributes
+      return false unless attributes
+
+      # Return true if any one of the audience conditions are met
+      @condition_evaluator = ConditionEvaluator.new(attributes)
+      audience_ids.each do |audience_id|
+        audience_conditions = config.get_audience_conditions_from_id(audience_id)
+        audience_conditions = JSON.load(audience_conditions)
+        return true if @condition_evaluator.evaluate(audience_conditions)
+      end
+
+      false
+    end
+  end
+end

data/lib/optimizely/bucketer.rb

@@ -0,0 +1,143 @@
+require 'murmurhash3'
+require_relative 'helpers/group'
+
+module Optimizely
+  class Bucketer
+    # Optimizely bucketing algorithm that evenly distributes visitors.
+
+    BUCKETING_ID_TEMPLATE = '%{user_id}%{entity_id}'
+    HASH_SEED = 1
+    MAX_HASH_VALUE = 2**32
+    MAX_TRAFFIC_VALUE = 10_000
+    UNSIGNED_MAX_32_BIT_VALUE = 0xFFFFFFFF
+
+    def initialize(config)
+      # Bucketer init method to set bucketing seed and project config data.
+      #
+      # config - ProjectConfig data to be used in making bucketing decisions.
+
+      @bucket_seed = HASH_SEED
+      @config = config
+    end
+
+    def bucket(experiment_key, user_id)
+      # Determines ID of variation to be shown for a given experiment key and user ID.
+      #
+      # experiment_key - String Key representing experiment for which visitor is to be bucketed.
+      # user_id - String ID for user.
+      #
+      # Returns String variation ID in which visitor with ID user_id has been placed. Nil if no variation.
+
+      # handle forced variations if applicable
+      forced_variations = @config.get_forced_variations(experiment_key)
+      forced_variation_key = forced_variations[user_id]
+      if forced_variation_key
+        forced_variation_id = @config.get_variation_id_from_key(experiment_key, forced_variation_key)
+        if forced_variation_id
+          @config.logger.log(Logger::INFO, "User '#{user_id}' is forced in variation '#{forced_variation_key}'.")
+          return forced_variation_id
+        else
+          @config.logger.log(
+            Logger::INFO,
+            "Variation key '#{forced_variation_key}' is not in datafile. Not activating user '#{user_id}'."
+          )
+          return nil
+        end
+      end
+
+      # check if experiment is in a group; if so, check if user is bucketed into specified experiment
+      experiment_id = @config.get_experiment_id(experiment_key)
+      group_id = @config.get_experiment_group_id(experiment_key)
+      if group_id
+        group = @config.group_key_map.fetch(group_id)
+        if Helpers::Group.random_policy?(group)
+          bucketing_id = sprintf(BUCKETING_ID_TEMPLATE, user_id: user_id, entity_id: group_id)
+          traffic_allocations = group.fetch('trafficAllocation')
+          bucket_value = generate_bucket_value(bucketing_id)
+          @config.logger.log(Logger::DEBUG, "Assigned experiment bucket #{bucket_value} to user '#{user_id}'.")
+          bucketed_experiment_id = find_bucket(bucket_value, traffic_allocations)
+
+          # return if the user is not bucketed into any experiment
+          unless bucketed_experiment_id
+            @config.logger.log(Logger::INFO, "User '#{user_id}' is in no experiment.")
+            return nil
+          end
+
+          # return if the user is bucketed into a different experiment than the one specified
+          if bucketed_experiment_id != experiment_id
+            @config.logger.log(
+              Logger::INFO,
+              "User '#{user_id}' is not in experiment '#{experiment_key}' of group #{group_id}."
+            )
+            return nil
+          end
+
+          # continue bucketing if the user is bucketed into the experiment specified
+          @config.logger.log(
+            Logger::INFO,
+            "User '#{user_id}' is in experiment '#{experiment_key}' of group #{group_id}."
+          )
+        end
+      end
+
+      bucketing_id = sprintf(BUCKETING_ID_TEMPLATE, user_id: user_id, entity_id: experiment_id)
+      bucket_value = generate_bucket_value(bucketing_id)
+      @config.logger.log(Logger::DEBUG, "Assigned variation bucket #{bucket_value} to user '#{user_id}'.")
+      traffic_allocations = @config.get_traffic_allocation(experiment_key)
+      variation_id = find_bucket(bucket_value, traffic_allocations)
+      if variation_id
+        variation_key = @config.get_variation_key_from_id(experiment_key, variation_id)
+        @config.logger.log(
+          Logger::INFO,
+          "User '#{user_id}' is in variation '#{variation_key}' of experiment '#{experiment_key}'."
+        )
+        return variation_id
+      end
+
+      @config.logger.log(Logger::INFO, "User '#{user_id}' is in no variation.")
+      nil
+    end
+
+    private
+
+    def find_bucket(bucket_value, traffic_allocations)
+      # Helper function to find the matching entity ID for a given bucketing value in a list of traffic allocations.
+      #
+      # bucket_value - Integer bucket value
+      # traffic_allocations - Array of traffic allocations
+      #
+      # Returns entity ID corresponding to the provided bucket value or nil if no match is found.
+
+      traffic_allocations.each do |traffic_allocation|
+        current_end_of_range = traffic_allocation['endOfRange']
+        if bucket_value < current_end_of_range
+          entity_id = traffic_allocation['entityId']
+          return entity_id
+        end
+      end
+
+      nil
+    end
+
+    def generate_bucket_value(bucketing_id)
+      # Helper function to generate bucket value in half-closed interval [0, MAX_TRAFFIC_VALUE).
+      #
+      # bucketing_id - String ID for bucketing.
+      #
+      # Returns bucket value corresponding to the provided bucketing ID.
+
+      ratio = (generate_unsigned_hash_code_32_bit(bucketing_id)).to_f / MAX_HASH_VALUE
+      (ratio * MAX_TRAFFIC_VALUE).to_i
+    end
+
+    def generate_unsigned_hash_code_32_bit(bucketing_id)
+      # Helper function to retreive hash code
+      #
+      # bucketing_id - String ID for bucketing.
+      #
+      # Returns hash code which is a 32 bit unsigned integer.
+
+      MurmurHash3::V32.str_hash(bucketing_id, @bucket_seed) & UNSIGNED_MAX_32_BIT_VALUE
+    end
+  end
+end

data/lib/optimizely/condition.rb

@@ -0,0 +1,118 @@
+require 'json'
+
+module Optimizely
+  class ConditionalOperatorTypes
+    AND = 'and'
+    OR = 'or'
+    NOT = 'not'
+  end
+
+  class ConditionEvaluator
+    DEFAULT_OPERATOR_TYPES = [
+      ConditionalOperatorTypes::AND,
+      ConditionalOperatorTypes::OR,
+      ConditionalOperatorTypes::NOT
+    ]
+
+    attr_reader :user_attributes
+
+    def initialize(user_attributes)
+      @user_attributes = user_attributes
+    end
+
+    def and_evaluator(conditions)
+      # Evaluates an array of conditions as if the evaluator had been applied
+      # to each entry and the results AND-ed together.
+      #
+      # conditions - Array of conditions ex: [operand_1, operand_2]
+      #
+      # Returns boolean true if all operands evaluate to true.
+
+      conditions.each do |condition|
+        result = evaluate(condition)
+        return result if result == false
+      end
+
+      true
+    end
+
+    def or_evaluator(conditions)
+      # Evaluates an array of conditions as if the evaluator had been applied
+      # to each entry and the results AND-ed together.
+      #
+      # conditions - Array of conditions ex: [operand_1, operand_2]
+      #
+      # Returns boolean true if any operand evaluates to true.
+
+      conditions.each do |condition|
+        result = evaluate(condition)
+        return result if result == true
+      end
+
+      false
+    end
+
+    def not_evaluator(single_condition)
+      # Evaluates an array of conditions as if the evaluator had been applied
+      # to a single entry and NOT was applied to the result.
+      #
+      # single_condition - Array of a single condition ex: [operand_1]
+      #
+      # Returns boolean true if the operand evaluates to false.
+
+      return false if single_condition.length != 1
+
+      !evaluate(single_condition[0])
+    end
+
+    def evaluator(condition_array)
+      # Method to compare single audience condition against provided user data i.e. attributes.
+      #
+      # condition_array - Array consisting of condition key and corresponding value.
+      #
+      # Returns boolean indicating the result of comparing the condition value against the user attributes.
+
+      condition_array[1] == @user_attributes[condition_array[0]]
+    end
+
+    def evaluate(conditions)
+      # Top level method to evaluate audience conditions.
+      #
+      # conditions - Nested array of and/or conditions.
+      #              Example: ['and', operand_1, ['or', operand_2, operand_3]]
+      #
+      # Returns boolean result of evaluating the conditions evaluated.
+
+      if conditions.is_a? Array
+        operator_type = conditions[0]
+        return false unless DEFAULT_OPERATOR_TYPES.include?(operator_type)
+        case operator_type
+        when ConditionalOperatorTypes::AND
+          return and_evaluator(conditions[1..-1])
+        when ConditionalOperatorTypes::OR
+          return or_evaluator(conditions[1..-1])
+        when ConditionalOperatorTypes::NOT
+          return not_evaluator(conditions[1..-1])
+        end
+      end
+
+      # Create array of condition key and corresponding value of audience condition.
+      condition_array = audience_condition_deserializer(conditions)
+
+      # Compare audience condition against provided user data i.e. attributes.
+      evaluator(condition_array)
+    end
+
+    private
+
+    def audience_condition_deserializer(condition)
+      # Deserializer defining how hashes need to be decoded for audience conditions.
+      #
+      # condition - Hash representing one audience condition.
+      #
+      # Returns array consisting of condition key and corresponding value.
+
+      [condition['name'], condition['value']]
+    end
+  end
+end