optimizely-sdk 3.4.0 → 3.8.0

data/lib/optimizely/custom_attribute_condition_evaluator.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #
-#    Copyright 2019, Optimizely and contributors
+#    Copyright 2019-2020, 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.
@@ -15,8 +15,10 @@
 #    See the License for the specific language governing permissions and
 #    limitations under the License.
 #
+require_relative 'exceptions'
 require_relative 'helpers/constants'
 require_relative 'helpers/validator'
+require_relative 'semantic_version'
 
 module Optimizely
   class CustomAttributeConditionEvaluator
@@ -26,15 +28,29 @@ module Optimizely
     EXACT_MATCH_TYPE = 'exact'
     EXISTS_MATCH_TYPE = 'exists'
     GREATER_THAN_MATCH_TYPE = 'gt'
+    GREATER_EQUAL_MATCH_TYPE = 'ge'
     LESS_THAN_MATCH_TYPE = 'lt'
+    LESS_EQUAL_MATCH_TYPE = 'le'
     SUBSTRING_MATCH_TYPE = 'substring'
+    SEMVER_EQ = 'semver_eq'
+    SEMVER_GE = 'semver_ge'
+    SEMVER_GT = 'semver_gt'
+    SEMVER_LE = 'semver_le'
+    SEMVER_LT = 'semver_lt'
 
     EVALUATORS_BY_MATCH_TYPE = {
       EXACT_MATCH_TYPE => :exact_evaluator,
       EXISTS_MATCH_TYPE => :exists_evaluator,
       GREATER_THAN_MATCH_TYPE => :greater_than_evaluator,
+      GREATER_EQUAL_MATCH_TYPE => :greater_than_or_equal_evaluator,
       LESS_THAN_MATCH_TYPE => :less_than_evaluator,
-      SUBSTRING_MATCH_TYPE => :substring_evaluator
+      LESS_EQUAL_MATCH_TYPE => :less_than_or_equal_evaluator,
+      SUBSTRING_MATCH_TYPE => :substring_evaluator,
+      SEMVER_EQ => :semver_equal_evaluator,
+      SEMVER_GE => :semver_greater_than_or_equal_evaluator,
+      SEMVER_GT => :semver_greater_than_evaluator,
+      SEMVER_LE => :semver_less_than_or_equal_evaluator,
+      SEMVER_LT => :semver_less_than_evaluator
     }.freeze
 
     attr_reader :user_attributes
@@ -95,7 +111,35 @@ module Optimizely
         return nil
       end
 
-      send(EVALUATORS_BY_MATCH_TYPE[condition_match], leaf_condition)
+      begin
+        send(EVALUATORS_BY_MATCH_TYPE[condition_match], leaf_condition)
+      rescue InvalidAttributeType
+        condition_name = leaf_condition['name']
+        user_value = @user_attributes[condition_name]
+
+        @logger.log(
+          Logger::WARN,
+          format(
+            Helpers::Constants::AUDIENCE_EVALUATION_LOGS['UNEXPECTED_TYPE'],
+            leaf_condition,
+            user_value.class,
+            condition_name
+          )
+        )
+        return nil
+      rescue InvalidSemanticVersion
+        condition_name = leaf_condition['name']
+
+        @logger.log(
+          Logger::WARN,
+          format(
+            Helpers::Constants::AUDIENCE_EVALUATION_LOGS['INVALID_SEMANTIC_VERSION'],
+            leaf_condition,
+            condition_name
+          )
+        )
+        return nil
+      end
     end
 
     def exact_evaluator(condition)
@@ -122,16 +166,7 @@ module Optimizely
 
       if !value_type_valid_for_exact_conditions?(user_provided_value) ||
          !Helpers::Validator.same_types?(condition_value, user_provided_value)
-        @logger.log(
-          Logger::WARN,
-          format(
-            Helpers::Constants::AUDIENCE_EVALUATION_LOGS['UNEXPECTED_TYPE'],
-            condition,
-            user_provided_value.class,
-            condition['name']
-          )
-        )
-        return nil
+        raise InvalidAttributeType
       end
 
       if user_provided_value.is_a?(Numeric) && !Helpers::Validator.finite_number?(user_provided_value)
@@ -173,6 +208,20 @@ module Optimizely
       user_provided_value > condition_value
     end
 
+    def greater_than_or_equal_evaluator(condition)
+      # Evaluate the given greater than or equal match condition for the given user attributes.
+      # Returns boolean true if the user attribute value is greater than or equal to the condition value,
+      #                 false if the user attribute value is less than the condition value,
+      #                 nil if the condition value isn't a number or the user attribute value isn't a number.
+
+      condition_value = condition['value']
+      user_provided_value = @user_attributes[condition['name']]
+
+      return nil unless valid_numeric_values?(user_provided_value, condition_value, condition)
+
+      user_provided_value >= condition_value
+    end
+
     def less_than_evaluator(condition)
       # Evaluate the given less than match condition for the given user attributes.
       # Returns boolean true if the user attribute value is less than the condition value,
@@ -187,6 +236,20 @@ module Optimizely
       user_provided_value < condition_value
     end
 
+    def less_than_or_equal_evaluator(condition)
+      # Evaluate the given less than or equal match condition for the given user attributes.
+      # Returns boolean true if the user attribute value is less than or equal to the condition value,
+      #                 false if the user attribute value is greater than the condition value,
+      #                 nil if the condition value isn't a number or the user attribute value isn't a number.
+
+      condition_value = condition['value']
+      user_provided_value = @user_attributes[condition['name']]
+
+      return nil unless valid_numeric_values?(user_provided_value, condition_value, condition)
+
+      user_provided_value <= condition_value
+    end
+
     def substring_evaluator(condition)
       # Evaluate the given substring match condition for the given user attributes.
       # Returns boolean true if the condition value is a substring of the user attribute value,
@@ -204,22 +267,66 @@ module Optimizely
         return nil
       end
 
-      unless user_provided_value.is_a?(String)
-        @logger.log(
-          Logger::WARN,
-          format(
-            Helpers::Constants::AUDIENCE_EVALUATION_LOGS['UNEXPECTED_TYPE'],
-            condition,
-            user_provided_value.class,
-            condition['name']
-          )
-        )
-        return nil
-      end
+      raise InvalidAttributeType unless user_provided_value.is_a?(String)
 
       user_provided_value.include? condition_value
     end
 
+    def semver_equal_evaluator(condition)
+      # Evaluate the given semantic version equal match target version for the user version.
+      # Returns boolean true if the user version is equal to the target version,
+      #                 false if the user version is not equal to the target version
+
+      target_version = condition['value']
+      user_version = @user_attributes[condition['name']]
+
+      SemanticVersion.compare_user_version_with_target_version(target_version, user_version).zero?
+    end
+
+    def semver_greater_than_evaluator(condition)
+      # Evaluate the given semantic version greater than match target version for the user version.
+      # Returns boolean true if the user version is greater than the target version,
+      #                 false if the user version is less than or equal to the target version
+
+      target_version = condition['value']
+      user_version = @user_attributes[condition['name']]
+
+      SemanticVersion.compare_user_version_with_target_version(target_version, user_version).positive?
+    end
+
+    def semver_greater_than_or_equal_evaluator(condition)
+      # Evaluate the given semantic version greater than or equal to match target version for the user version.
+      # Returns boolean true if the user version is greater than or equal to the target version,
+      #                 false if the user version is less than the target version
+
+      target_version = condition['value']
+      user_version = @user_attributes[condition['name']]
+
+      SemanticVersion.compare_user_version_with_target_version(target_version, user_version) >= 0
+    end
+
+    def semver_less_than_evaluator(condition)
+      # Evaluate the given semantic version less than match target version for the user version.
+      # Returns boolean true if the user version is less than the target version,
+      #                 false if the user version is greater than or equal to the target version
+
+      target_version = condition['value']
+      user_version = @user_attributes[condition['name']]
+
+      SemanticVersion.compare_user_version_with_target_version(target_version, user_version).negative?
+    end
+
+    def semver_less_than_or_equal_evaluator(condition)
+      # Evaluate the given semantic version less than or equal to match target version for the user version.
+      # Returns boolean true if the user version is less than or equal to the target version,
+      #                 false if the user version is greater than the target version
+
+      target_version = condition['value']
+      user_version = @user_attributes[condition['name']]
+
+      SemanticVersion.compare_user_version_with_target_version(target_version, user_version) <= 0
+    end
+
     private
 
     def valid_numeric_values?(user_value, condition_value, condition)
@@ -234,18 +341,7 @@ module Optimizely
         return false
       end
 
-      unless user_value.is_a?(Numeric)
-        @logger.log(
-          Logger::WARN,
-          format(
-            Helpers::Constants::AUDIENCE_EVALUATION_LOGS['UNEXPECTED_TYPE'],
-            condition,
-            user_value.class,
-            condition['name']
-          )
-        )
-        return false
-      end
+      raise InvalidAttributeType unless user_value.is_a?(Numeric)
 
       unless Helpers::Validator.finite_number?(user_value)
         @logger.log(

data/lib/optimizely/decide/optimizely_decide_option.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+#    Copyright 2020, 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.
+#
+
+module Optimizely
+  module Decide
+    module OptimizelyDecideOption
+      DISABLE_DECISION_EVENT = 'DISABLE_DECISION_EVENT'
+      ENABLED_FLAGS_ONLY = 'ENABLED_FLAGS_ONLY'
+      IGNORE_USER_PROFILE_SERVICE = 'IGNORE_USER_PROFILE_SERVICE'
+      INCLUDE_REASONS = 'INCLUDE_REASONS'
+      EXCLUDE_VARIABLES = 'EXCLUDE_VARIABLES'
+    end
+  end
+end

data/lib/optimizely/decide/optimizely_decision.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+#    Copyright 2020, 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 'json'
+
+module Optimizely
+  module Decide
+    class OptimizelyDecision
+      attr_reader :variation_key, :enabled, :variables, :rule_key, :flag_key, :user_context, :reasons
+
+      def initialize(
+        variation_key: nil,
+        enabled: nil,
+        variables: nil,
+        rule_key: nil,
+        flag_key: nil,
+        user_context: nil,
+        reasons: nil
+      )
+        @variation_key = variation_key
+        @enabled = enabled || false
+        @variables = variables || {}
+        @rule_key = rule_key
+        @flag_key = flag_key
+        @user_context = user_context
+        @reasons = reasons || []
+      end
+
+      def as_json
+        {
+          variation_key: @variation_key,
+          enabled: @enabled,
+          variables: @variables,
+          rule_key: @rule_key,
+          flag_key: @flag_key,
+          user_context: @user_context.as_json,
+          reasons: @reasons
+        }
+      end
+
+      def to_json(*args)
+        as_json.to_json(*args)
+      end
+    end
+  end
+end

data/lib/optimizely/decide/optimizely_decision_message.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+#    Copyright 2020, 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.
+#
+
+module Optimizely
+  module Decide
+    module OptimizelyDecisionMessage
+      SDK_NOT_READY = 'Optimizely SDK not configured properly yet.'
+      FLAG_KEY_INVALID = 'No flag was found for key "%s".'
+      VARIABLE_VALUE_INVALID = 'Variable value for key "%s" is invalid or wrong type.'
+    end
+  end
+end

data/lib/optimizely/decision_service.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #
-#    Copyright 2017-2019, Optimizely and contributors
+#    Copyright 2017-2020, 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.
@@ -40,6 +40,7 @@ module Optimizely
     Decision = Struct.new(:experiment, :variation, :source)
 
     DECISION_SOURCES = {
+      'EXPERIMENT' => 'experiment',
       'FEATURE_TEST' => 'feature-test',
       'ROLLOUT' => 'rollout'
     }.freeze
@@ -51,7 +52,7 @@ module Optimizely
       @forced_variation_map = {}
     end
 
-    def get_variation(project_config, experiment_key, user_id, attributes = nil)
+    def get_variation(project_config, experiment_key, user_id, attributes = nil, decide_options = [])
       # Determines variation into which user will be bucketed.
       #
       # project_config - project_config - Instance of ProjectConfig
@@ -62,56 +63,78 @@ module Optimizely
       # Returns variation ID where visitor will be bucketed
       #   (nil if experiment is inactive or user does not meet audience conditions)
 
+      decide_reasons = []
       # By default, the bucketing ID should be the user ID
-      bucketing_id = get_bucketing_id(user_id, attributes)
+      bucketing_id, bucketing_id_reasons = get_bucketing_id(user_id, attributes)
+      decide_reasons.push(*bucketing_id_reasons)
       # Check to make sure experiment is active
       experiment = project_config.get_experiment_from_key(experiment_key)
-      return nil if experiment.nil?
+      return nil, decide_reasons if experiment.nil?
 
       experiment_id = experiment['id']
       unless project_config.experiment_running?(experiment)
-        @logger.log(Logger::INFO, "Experiment '#{experiment_key}' is not running.")
-        return nil
+        message = "Experiment '#{experiment_key}' is not running."
+        @logger.log(Logger::INFO, message)
+        decide_reasons.push(message)
+        return nil, decide_reasons
       end
 
       # Check if a forced variation is set for the user
-      forced_variation = get_forced_variation(project_config, experiment_key, user_id)
-      return forced_variation['id'] if forced_variation
+      forced_variation, reasons_received = get_forced_variation(project_config, experiment_key, user_id)
+      decide_reasons.push(*reasons_received)
+      return forced_variation['id'], decide_reasons if forced_variation
 
       # Check if user is in a white-listed variation
-      whitelisted_variation_id = get_whitelisted_variation_id(project_config, experiment_key, user_id)
-      return whitelisted_variation_id if whitelisted_variation_id
-
-      # Check for saved bucketing decisions
-      user_profile = get_user_profile(user_id)
-      saved_variation_id = get_saved_variation_id(project_config, experiment_id, user_profile)
-      if saved_variation_id
-        @logger.log(
-          Logger::INFO,
-          "Returning previously activated variation ID #{saved_variation_id} of experiment '#{experiment_key}' for user '#{user_id}' from user profile."
-        )
-        return saved_variation_id
+      whitelisted_variation_id, reasons_received = get_whitelisted_variation_id(project_config, experiment_key, user_id)
+      decide_reasons.push(*reasons_received)
+      return whitelisted_variation_id, decide_reasons if whitelisted_variation_id
+
+      should_ignore_user_profile_service = decide_options.include? Optimizely::Decide::OptimizelyDecideOption::IGNORE_USER_PROFILE_SERVICE
+      # Check for saved bucketing decisions if decide_options do not include ignoreUserProfileService
+      unless should_ignore_user_profile_service
+        user_profile, reasons_received = get_user_profile(user_id)
+        decide_reasons.push(*reasons_received)
+        saved_variation_id, reasons_received = get_saved_variation_id(project_config, experiment_id, user_profile)
+        decide_reasons.push(*reasons_received)
+        if saved_variation_id
+          message = "Returning previously activated variation ID #{saved_variation_id} of experiment '#{experiment_key}' for user '#{user_id}' from user profile."
+          @logger.log(Logger::INFO, message)
+          decide_reasons.push(message)
+          return saved_variation_id, decide_reasons
+        end
       end
 
       # Check audience conditions
-      unless Audience.user_in_experiment?(project_config, experiment, attributes, @logger)
-        @logger.log(
-          Logger::INFO,
-          "User '#{user_id}' does not meet the conditions to be in experiment '#{experiment_key}'."
-        )
-        return nil
+      user_meets_audience_conditions, reasons_received = Audience.user_meets_audience_conditions?(project_config, experiment, attributes, @logger)
+      decide_reasons.push(*reasons_received)
+      unless user_meets_audience_conditions
+        message = "User '#{user_id}' does not meet the conditions to be in experiment '#{experiment_key}'."
+        @logger.log(Logger::INFO, message)
+        decide_reasons.push(message)
+        return nil, decide_reasons
       end
 
       # Bucket normally
-      variation = @bucketer.bucket(project_config, experiment, bucketing_id, user_id)
+      variation, bucket_reasons = @bucketer.bucket(project_config, experiment, bucketing_id, user_id)
+      decide_reasons.push(*bucket_reasons)
       variation_id = variation ? variation['id'] : nil
 
+      message = ''
+      if variation_id
+        variation_key = variation['key']
+        message = "User '#{user_id}' is in variation '#{variation_key}' of experiment '#{experiment_key}'."
+      else
+        message = "User '#{user_id}' is in no variation."
+      end
+      @logger.log(Logger::INFO, message)
+      decide_reasons.push(message)
+
       # Persist bucketing decision
-      save_user_profile(user_profile, experiment_id, variation_id)
-      variation_id
+      save_user_profile(user_profile, experiment_id, variation_id) unless should_ignore_user_profile_service
+      [variation_id, decide_reasons]
     end
 
-    def get_variation_for_feature(project_config, feature_flag, user_id, attributes = nil)
+    def get_variation_for_feature(project_config, feature_flag, user_id, attributes = nil, decide_options = [])
       # Get the variation the user is bucketed into for the given FeatureFlag.
       #
       # project_config - project_config - Instance of ProjectConfig
@@ -121,28 +144,20 @@ module Optimizely
       #
       # Returns Decision struct (nil if the user is not bucketed into any of the experiments on the feature)
 
+      decide_reasons = []
+
       # check if the feature is being experiment on and whether the user is bucketed into the experiment
-      decision = get_variation_for_feature_experiment(project_config, feature_flag, user_id, attributes)
-      return decision unless decision.nil?
+      decision, reasons_received = get_variation_for_feature_experiment(project_config, feature_flag, user_id, attributes, decide_options)
+      decide_reasons.push(*reasons_received)
+      return decision, decide_reasons unless decision.nil?
 
-      feature_flag_key = feature_flag['key']
-      decision = get_variation_for_feature_rollout(project_config, feature_flag, user_id, attributes)
-      if decision
-        @logger.log(
-          Logger::INFO,
-          "User '#{user_id}' is bucketed into a rollout for feature flag '#{feature_flag_key}'."
-        )
-        return decision
-      end
-      @logger.log(
-        Logger::INFO,
-        "User '#{user_id}' is not bucketed into a rollout for feature flag '#{feature_flag_key}'."
-      )
+      decision, reasons_received = get_variation_for_feature_rollout(project_config, feature_flag, user_id, attributes)
+      decide_reasons.push(*reasons_received)
 
-      nil
+      [decision, decide_reasons]
     end
 
-    def get_variation_for_feature_experiment(project_config, feature_flag, user_id, attributes = nil)
+    def get_variation_for_feature_experiment(project_config, feature_flag, user_id, attributes = nil, decide_options = [])
       # Gets the variation the user is bucketed into for the feature flag's experiment.
       #
       # project_config - project_config - Instance of ProjectConfig
@@ -152,45 +167,41 @@ module Optimizely
       #
       # Returns Decision struct (nil if the user is not bucketed into any of the experiments on the feature)
       # or nil if the user is not bucketed into any of the experiments on the feature
+      decide_reasons = []
       feature_flag_key = feature_flag['key']
       if feature_flag['experimentIds'].empty?
-        @logger.log(
-          Logger::DEBUG,
-          "The feature flag '#{feature_flag_key}' is not used in any experiments."
-        )
-        return nil
+        message = "The feature flag '#{feature_flag_key}' is not used in any experiments."
+        @logger.log(Logger::DEBUG, message)
+        decide_reasons.push(message)
+        return nil, decide_reasons
       end
 
       # Evaluate each experiment and return the first bucketed experiment variation
       feature_flag['experimentIds'].each do |experiment_id|
         experiment = project_config.experiment_id_map[experiment_id]
         unless experiment
-          @logger.log(
-            Logger::DEBUG,
-            "Feature flag experiment with ID '#{experiment_id}' is not in the datafile."
-          )
-          return nil
+          message = "Feature flag experiment with ID '#{experiment_id}' is not in the datafile."
+          @logger.log(Logger::DEBUG, message)
+          decide_reasons.push(message)
+          return nil, decide_reasons
         end
 
         experiment_key = experiment['key']
-        variation_id = get_variation(project_config, experiment_key, user_id, attributes)
+        variation_id, reasons_received = get_variation(project_config, experiment_key, user_id, attributes, decide_options)
+        decide_reasons.push(*reasons_received)
 
         next unless variation_id
 
         variation = project_config.variation_id_map[experiment_key][variation_id]
-        @logger.log(
-          Logger::INFO,
-          "The user '#{user_id}' is bucketed into experiment '#{experiment_key}' of feature '#{feature_flag_key}'."
-        )
-        return Decision.new(experiment, variation, DECISION_SOURCES['FEATURE_TEST'])
+
+        return Decision.new(experiment, variation, DECISION_SOURCES['FEATURE_TEST']), decide_reasons
       end
 
-      @logger.log(
-        Logger::INFO,
-        "The user '#{user_id}' is not bucketed into any of the experiments on the feature '#{feature_flag_key}'."
-      )
+      message = "The user '#{user_id}' is not bucketed into any of the experiments on the feature '#{feature_flag_key}'."
+      @logger.log(Logger::INFO, message)
+      decide_reasons.push(message)
 
-      nil
+      [nil, decide_reasons]
     end
 
     def get_variation_for_feature_rollout(project_config, feature_flag, user_id, attributes = nil)
@@ -203,27 +214,27 @@ module Optimizely
       # attributes - Hash representing user attributes
       #
       # Returns the Decision struct or nil if not bucketed into any of the targeting rules
-      bucketing_id = get_bucketing_id(user_id, attributes)
+      decide_reasons = []
+      bucketing_id, bucketing_id_reasons = get_bucketing_id(user_id, attributes)
+      decide_reasons.push(*bucketing_id_reasons)
       rollout_id = feature_flag['rolloutId']
       if rollout_id.nil? || rollout_id.empty?
         feature_flag_key = feature_flag['key']
-        @logger.log(
-          Logger::DEBUG,
-          "Feature flag '#{feature_flag_key}' is not used in a rollout."
-        )
-        return nil
+        message = "Feature flag '#{feature_flag_key}' is not used in a rollout."
+        @logger.log(Logger::DEBUG, message)
+        decide_reasons.push(message)
+        return nil, decide_reasons
       end
 
       rollout = project_config.get_rollout_from_id(rollout_id)
       if rollout.nil?
-        @logger.log(
-          Logger::DEBUG,
-          "Rollout with ID '#{rollout_id}' is not in the datafile '#{feature_flag['key']}'"
-        )
-        return nil
+        message = "Rollout with ID '#{rollout_id}' is not in the datafile '#{feature_flag['key']}'"
+        @logger.log(Logger::DEBUG, message)
+        decide_reasons.push(message)
+        return nil, decide_reasons
       end
 
-      return nil if rollout['experiments'].empty?
+      return nil, decide_reasons if rollout['experiments'].empty?
 
       rollout_rules = rollout['experiments']
       number_of_rules = rollout_rules.length - 1
@@ -231,44 +242,54 @@ module Optimizely
       # Go through each experiment in order and try to get the variation for the user
       number_of_rules.times do |index|
         rollout_rule = rollout_rules[index]
-        audience_id = rollout_rule['audienceIds'][0]
-        audience = project_config.get_audience_from_id(audience_id)
-        audience_name = audience['name']
+        logging_key = index + 1
 
+        user_meets_audience_conditions, reasons_received = Audience.user_meets_audience_conditions?(project_config, rollout_rule, attributes, @logger, 'ROLLOUT_AUDIENCE_EVALUATION_LOGS', logging_key)
+        decide_reasons.push(*reasons_received)
         # Check that user meets audience conditions for targeting rule
-        unless Audience.user_in_experiment?(project_config, rollout_rule, attributes, @logger)
-          @logger.log(
-            Logger::DEBUG,
-            "User '#{user_id}' does not meet the conditions to be in rollout rule for audience '#{audience_name}'."
-          )
+        unless user_meets_audience_conditions
+          message = "User '#{user_id}' does not meet the audience conditions for targeting rule '#{logging_key}'."
+          @logger.log(Logger::DEBUG, message)
+          decide_reasons.push(message)
           # move onto the next targeting rule
           next
         end
 
+        message = "User '#{user_id}' meets the audience conditions for targeting rule '#{logging_key}'."
+        @logger.log(Logger::DEBUG, message)
+        decide_reasons.push(message)
+
         # Evaluate if user satisfies the traffic allocation for this rollout rule
-        variation = @bucketer.bucket(project_config, rollout_rule, bucketing_id, user_id)
-        return Decision.new(rollout_rule, variation, DECISION_SOURCES['ROLLOUT']) unless variation.nil?
+        variation, bucket_reasons = @bucketer.bucket(project_config, rollout_rule, bucketing_id, user_id)
+        decide_reasons.push(*bucket_reasons)
+        return Decision.new(rollout_rule, variation, DECISION_SOURCES['ROLLOUT']), decide_reasons unless variation.nil?
 
         break
       end
 
       # get last rule which is the everyone else rule
       everyone_else_experiment = rollout_rules[number_of_rules]
+      logging_key = 'Everyone Else'
+
+      user_meets_audience_conditions, reasons_received = Audience.user_meets_audience_conditions?(project_config, everyone_else_experiment, attributes, @logger, 'ROLLOUT_AUDIENCE_EVALUATION_LOGS', logging_key)
+      decide_reasons.push(*reasons_received)
       # Check that user meets audience conditions for last rule
-      unless Audience.user_in_experiment?(project_config, everyone_else_experiment, attributes, @logger)
-        audience_id = everyone_else_experiment['audienceIds'][0]
-        audience = project_config.get_audience_from_id(audience_id)
-        audience_name = audience['name']
-        @logger.log(
-          Logger::DEBUG,
-          "User '#{user_id}' does not meet the conditions to be in rollout rule for audience '#{audience_name}'."
-        )
-        return nil
+      unless user_meets_audience_conditions
+        message = "User '#{user_id}' does not meet the audience conditions for targeting rule '#{logging_key}'."
+        @logger.log(Logger::DEBUG, message)
+        decide_reasons.push(message)
+        return nil, decide_reasons
       end
-      variation = @bucketer.bucket(project_config, everyone_else_experiment, bucketing_id, user_id)
-      return Decision.new(everyone_else_experiment, variation, DECISION_SOURCES['ROLLOUT']) unless variation.nil?
 
-      nil
+      message = "User '#{user_id}' meets the audience conditions for targeting rule '#{logging_key}'."
+      @logger.log(Logger::DEBUG, message)
+      decide_reasons.push(message)
+
+      variation, bucket_reasons = @bucketer.bucket(project_config, everyone_else_experiment, bucketing_id, user_id)
+      decide_reasons.push(*bucket_reasons)
+      return Decision.new(everyone_else_experiment, variation, DECISION_SOURCES['ROLLOUT']), decide_reasons unless variation.nil?
+
+      [nil, decide_reasons]
     end
 
     def set_forced_variation(project_config, experiment_key, user_id, variation_key)
@@ -318,9 +339,11 @@ module Optimizely
       #
       # Returns Variation The variation which the given user and experiment should be forced into
 
+      decide_reasons = []
       unless @forced_variation_map.key? user_id
-        @logger.log(Logger::DEBUG, "User '#{user_id}' is not in the forced variation map.")
-        return nil
+        message = "User '#{user_id}' is not in the forced variation map."
+        @logger.log(Logger::DEBUG, message)
+        return nil, decide_reasons
       end
 
       experiment_to_variation_map = @forced_variation_map[user_id]
@@ -328,12 +351,13 @@ module Optimizely
       experiment_id = experiment['id'] if experiment
       # check for nil and empty string experiment ID
       # this case is logged in get_experiment_from_key
-      return nil if experiment_id.nil? || experiment_id.empty?
+      return nil, decide_reasons if experiment_id.nil? || experiment_id.empty?
 
       unless experiment_to_variation_map.key? experiment_id
-        @logger.log(Logger::DEBUG, "No experiment '#{experiment_key}' mapped to user '#{user_id}' "\
-                    'in the forced variation map.')
-        return nil
+        message = "No experiment '#{experiment_key}' mapped to user '#{user_id}' in the forced variation map."
+        @logger.log(Logger::DEBUG, message)
+        decide_reasons.push(message)
+        return nil, decide_reasons
       end
 
       variation_id = experiment_to_variation_map[experiment_id]
@@ -343,12 +367,13 @@ module Optimizely
 
       # check if the variation exists in the datafile
       # this case is logged in get_variation_from_id
-      return nil if variation_key.empty?
+      return nil, decide_reasons if variation_key.empty?
 
-      @logger.log(Logger::DEBUG, "Variation '#{variation_key}' is mapped to experiment '#{experiment_key}' "\
-                  "and user '#{user_id}' in the forced variation map")
+      message = "Variation '#{variation_key}' is mapped to experiment '#{experiment_key}' and user '#{user_id}' in the forced variation map"
+      @logger.log(Logger::DEBUG, message)
+      decide_reasons.push(message)
 
-      variation
+      [variation, decide_reasons]
     end
 
     private
@@ -364,27 +389,24 @@ module Optimizely
 
       whitelisted_variations = project_config.get_whitelisted_variations(experiment_key)
 
-      return nil unless whitelisted_variations
+      return nil, nil unless whitelisted_variations
 
       whitelisted_variation_key = whitelisted_variations[user_id]
 
-      return nil unless whitelisted_variation_key
+      return nil, nil unless whitelisted_variation_key
 
       whitelisted_variation_id = project_config.get_variation_id_from_key(experiment_key, whitelisted_variation_key)
 
       unless whitelisted_variation_id
-        @logger.log(
-          Logger::INFO,
-          "User '#{user_id}' is whitelisted into variation '#{whitelisted_variation_key}', which is not in the datafile."
-        )
-        return nil
+        message = "User '#{user_id}' is whitelisted into variation '#{whitelisted_variation_key}', which is not in the datafile."
+        @logger.log(Logger::INFO, message)
+        return nil, message
       end
 
-      @logger.log(
-        Logger::INFO,
-        "User '#{user_id}' is whitelisted into variation '#{whitelisted_variation_key}' of experiment '#{experiment_key}'."
-      )
-      whitelisted_variation_id
+      message = "User '#{user_id}' is whitelisted into variation '#{whitelisted_variation_key}' of experiment '#{experiment_key}'."
+      @logger.log(Logger::INFO, message)
+
+      [whitelisted_variation_id, message]
     end
 
     def get_saved_variation_id(project_config, experiment_id, user_profile)
@@ -395,19 +417,18 @@ module Optimizely
       # user_profile - Hash user profile
       #
       # Returns string variation ID (nil if no decision is found)
-      return nil unless user_profile[:experiment_bucket_map]
+      return nil, nil unless user_profile[:experiment_bucket_map]
 
       decision = user_profile[:experiment_bucket_map][experiment_id]
-      return nil unless decision
+      return nil, nil unless decision
 
       variation_id = decision[:variation_id]
-      return variation_id if project_config.variation_id_exists?(experiment_id, variation_id)
+      return variation_id, nil if project_config.variation_id_exists?(experiment_id, variation_id)
+
+      message = "User '#{user_profile[:user_id]}' was previously bucketed into variation ID '#{variation_id}' for experiment '#{experiment_id}', but no matching variation was found. Re-bucketing user."
+      @logger.log(Logger::INFO, message)
 
-      @logger.log(
-        Logger::INFO,
-        "User '#{user_profile['user_id']}' was previously bucketed into variation ID '#{variation_id}' for experiment '#{experiment_id}', but no matching variation was found. Re-bucketing user."
-      )
-      nil
+      [nil, message]
     end
 
     def get_user_profile(user_id)
@@ -422,15 +443,17 @@ module Optimizely
         experiment_bucket_map: {}
       }
 
-      return user_profile unless @user_profile_service
+      return user_profile, nil unless @user_profile_service
 
+      message = nil
       begin
         user_profile = @user_profile_service.lookup(user_id) || user_profile
       rescue => e
-        @logger.log(Logger::ERROR, "Error while looking up user profile for user ID '#{user_id}': #{e}.")
+        message = "Error while looking up user profile for user ID '#{user_id}': #{e}."
+        @logger.log(Logger::ERROR, message)
       end
 
-      user_profile
+      [user_profile, message]
     end
 
     def save_user_profile(user_profile, experiment_id, variation_id)
@@ -461,16 +484,17 @@ module Optimizely
       # attributes - Hash user attributes
       # Returns String representing bucketing ID if it is a String type in attributes else return user ID
 
-      return user_id unless attributes
+      return user_id, nil unless attributes
 
       bucketing_id = attributes[Optimizely::Helpers::Constants::CONTROL_ATTRIBUTES['BUCKETING_ID']]
 
       if bucketing_id
-        return bucketing_id if bucketing_id.is_a?(String)
+        return bucketing_id, nil if bucketing_id.is_a?(String)
 
-        @logger.log(Logger::WARN, 'Bucketing ID attribute is not a string. Defaulted to user ID.')
+        message = 'Bucketing ID attribute is not a string. Defaulted to user ID.'
+        @logger.log(Logger::WARN, message)
       end
-      user_id
+      [user_id, message]
     end
   end
 end