kameleoon-client-ruby 3.6.0 → 3.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 92e73ac3d81e29ddfc093e8da1a47f42b9970ea6e8717e0752be511b759db17a
-  data.tar.gz: 710361f25b6338e35bb668bb30f116c931efddd21fdb272fa5367add4d82db22
+  metadata.gz: 9e0001c490d29beefab2f33c416affe19f6ccbc05d83e0aaad70be85070986e3
+  data.tar.gz: 6959eb4d8f421b9e14e62f3c490d5e1c6f038a25d3e5cb785c1832d7908c291d
 SHA512:
-  metadata.gz: 24db6ec9d63c160690506060d703661f77c5b60160fc585117b91460e74185a095f0b52156b268ba18d445797a584c9bd92e824c2bbecf8533d08e09cf89dab6
-  data.tar.gz: ab2f4e530b33235f7105158414ff77ce52f5b824632e4cae53ed06425f32be6f22719dcae86d7d5660cbd09ea4c090672ee5a237828a6db0e0772e80d65032c5
+  metadata.gz: dfe9e75f3563287b6f187a38066a623145ba7ed916d12b9c7ec03dfe7173600ddd16d6a49ca304c4c46ec28794d5372bf29534f36ebaea18fa7eb8c2977dd981
+  data.tar.gz: faf2abe7ed35a211fc210a3e72f90a2bf79a8affde8a35c96af2363fabb50091b1069aaea0074458bff1d56156d80e81cd8cb427e3c772b99dc81d318093f7a9

data/lib/kameleoon/configuration/data_file.rb

@@ -9,7 +9,7 @@ module Kameleoon
   module Configuration
     class DataFile
       attr_reader :settings, :feature_flags, :has_any_targeted_delivery_rule, :feature_flag_by_id, :rule_by_segment_id,
-                  :variation_by_id, :custom_data_info, :experiment_ids_with_js_css_variable
+                  :rule_info_by_exp_id, :variation_by_id, :custom_data_info, :experiment_ids_with_js_css_variable
 
       def to_s
         'DataFile{' \
@@ -74,6 +74,7 @@ module Kameleoon
       def collect_indices
         @feature_flag_by_id = {}
         @rule_by_segment_id = {}
+        @rule_info_by_exp_id = {}
         @variation_by_id = {}
         @experiment_ids_with_js_css_variable = Set.new
 
@@ -84,6 +85,7 @@ module Kameleoon
           has_feature_flag_variable_js_css = feature_flag_variable_js_css?(feature_flag)
           feature_flag.rules.each do |rule|
             @rule_by_segment_id[rule.segment_id] = rule
+            @rule_info_by_exp_id[rule.experiment_id || 0] = RuleInfo.new(feature_flag, rule)
             rule.variation_by_exposition.each do |variation|
               @variation_by_id[variation.variation_id] = variation
             end
@@ -102,5 +104,14 @@ module Kameleoon
         end
       end
     end
+
+    class RuleInfo
+      attr_reader :feature_flag, :rule
+
+      def initialize(feature_flag, rule)
+        @feature_flag = feature_flag
+        @rule = rule
+      end
+    end
   end
 end

data/lib/kameleoon/configuration/rule.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'variation_exposition'
+require 'kameleoon/exceptions'
 require 'kameleoon/targeting/models'
 
 module Kameleoon
@@ -29,7 +30,8 @@ module Kameleoon
 
     # Rule is a class for new rules of feature flags
     class Rule
-      attr_reader :id, :order, :type, :exposition, :experiment_id, :variation_by_exposition, :respool_time, :segment_id, :first_variation
+      attr_reader :id, :order, :type, :exposition, :experiment_id, :variation_by_exposition, :respool_time, :segment_id,
+                  :first_variation
       attr_accessor :targeting_segment
 
       def self.create_from_array(array)
@@ -63,6 +65,15 @@ module Kameleoon
         nil
       end
 
+      def get_variation_by_key(variation_key)
+        var_by_exp = variation_by_exposition.find { |v| v.variation_key == variation_key }
+        unless var_by_exp
+          raise Exception::FeatureVariationNotFound.new(variation_key),
+                "#{self} does not contain variation '#{variation_key}'"
+        end
+        var_by_exp
+      end
+
       def get_variation_id_by_key(key)
         variation_by_exposition.select { |v| v.variation_key == key }.first&.variation_id
       end

data/lib/kameleoon/data/data.rb

@@ -14,6 +14,8 @@ module Kameleoon
     DEVICE = 'DEVICE'
     PAGE_VIEW = 'PAGE_VIEW'
     ASSIGNED_VARIATION = 'ASSIGNED_VARIATION'
+    FORCED_EXPERIMENT_VARIATION = 'FORCED_EXPERIMENT_VARIATION'
+    FORCED_FEATURE_VARIATION = 'FORCED_FEATURE_VARIATION'
     OPERATING_SYSTEM = 'OPERATING_SYSTEM'
     GEOLOCATION = 'GEOLOCATION'
   end

data/lib/kameleoon/data/manager/forced_experiment_variation.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'kameleoon/data/data'
+require 'kameleoon/data/manager/forced_variation'
+
+module Kameleoon
+  module DataManager
+    class ForcedExperimentVariation < ForcedVariation
+      attr_reader :force_targeting
+
+      def initialize(rule, var_by_exp, force_targeting)
+        super(DataType::FORCED_EXPERIMENT_VARIATION, rule, var_by_exp)
+        @force_targeting = force_targeting
+      end
+
+      def ==(other)
+        super(other) && other.is_a?(ForcedExperimentVariation) && (@force_targeting == other.force_targeting)
+      end
+
+      def to_s
+        "ForcedExperimentVariation{rule:#{@rule},var_by_exp:#{@var_by_exp},force_targeting:#{@force_targeting}}"
+      end
+    end
+  end
+end

data/lib/kameleoon/data/manager/forced_feature_variation.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'kameleoon/data/data'
+require 'kameleoon/data/manager/forced_variation'
+
+module Kameleoon
+  module DataManager
+    class ForcedFeatureVariation < ForcedVariation
+      attr_reader :feature_key, :simulated
+
+      def initialize(feature_key, rule, var_by_exp, simulated)
+        super(DataType::FORCED_FEATURE_VARIATION, rule, var_by_exp)
+        @feature_key = feature_key
+        @simulated = simulated
+      end
+
+      def ==(other)
+        super(other) && other.is_a?(ForcedFeatureVariation) && \
+          (@feature_key == other.feature_key) && (@simulated == other.simulated)
+      end
+
+      def to_s
+        "ForcedFeatureVariation{feature_key:'#{@feature_key}',rule:#{@rule}," \
+          "var_by_exp:#{@var_by_exp},simulated:#{@simulated}}"
+      end
+    end
+  end
+end

data/lib/kameleoon/data/manager/forced_variation.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Kameleoon
+  module DataManager
+    class ForcedVariation
+      attr_reader :instance, :rule, :var_by_exp, :rule_type, :assignment_time
+
+      def initialize(data_type, rule, var_by_exp)
+        @instance = data_type
+        @rule = rule
+        @var_by_exp = var_by_exp
+      end
+
+      def ==(other)
+        (@rule == other.rule) && (@var_by_exp == other.var_by_exp)
+      end
+    end
+  end
+end

data/lib/kameleoon/data/manager/visitor.rb

@@ -10,9 +10,11 @@ require 'kameleoon/data/page_view'
 require 'kameleoon/data/unique_identifier'
 require 'kameleoon/data/user_agent'
 require 'kameleoon/data/manager/assigned_variation'
-require 'kameleoon/data/manager/page_view_visit'
-require 'kameleoon/data/manager/data_map_storage'
 require 'kameleoon/data/manager/data_array_storage'
+require 'kameleoon/data/manager/data_map_storage'
+require 'kameleoon/data/manager/forced_experiment_variation'
+require 'kameleoon/data/manager/forced_feature_variation'
+require 'kameleoon/data/manager/page_view_visit'
 require 'kameleoon/logging/kameleoon_logger'
 
 module Kameleoon
@@ -163,38 +165,86 @@ module Kameleoon
         variations
       end
 
+      def get_forced_feature_variation(feature_key)
+        Logging::KameleoonLogger.debug("CALL: Visitor.get_forced_feature_variation(feature_key: '%s')", feature_key)
+        variation = @data.get_from_map(@data.simulated_variations, feature_key)
+        Logging::KameleoonLogger.debug(
+          "RETURN: Visitor.get_forced_feature_variation(feature_key: '%s') -> (variation: %s)",
+          feature_key, variation
+        )
+        variation
+      end
+
+      def get_forced_experiment_variation(experiment_id)
+        Logging::KameleoonLogger.debug(
+          'CALL: Visitor.get_forced_experiment_variation(experiment_id: %d)', experiment_id
+        )
+        variation = @data.get_from_map(@data.forced_variations, experiment_id)
+        Logging::KameleoonLogger.debug(
+          'RETURN: Visitor.get_forced_experiment_variation(experiment_id: %d) -> (variation: %s)',
+          experiment_id, variation
+        )
+        variation
+      end
+
+      def reset_forced_experiment_variation(experiment_id)
+        Logging::KameleoonLogger.debug(
+          'CALL: Visitor.reset_forced_experiment_variation(experiment_id: %d)', experiment_id
+        )
+        @data.remove_from_map(@data.forced_variations, experiment_id)
+        Logging::KameleoonLogger.debug(
+          'RETURN: Visitor.reset_forced_experiment_variation(experiment_id: %d)', experiment_id
+        )
+      end
+
+      def update_simulated_variations(variations)
+        return if (@data.simulated_variations.nil? || @data.simulated_variations.empty?) && variations.empty?
+
+        Logging::KameleoonLogger.debug('CALL: Visitor.update_simulated_variations(variations: %s)', variations)
+        new_simulated_variations = {}
+        variations.each { |sv| new_simulated_variations[sv.feature_key] = sv }
+        @data.mutex.with_write_lock do
+          @data.simulated_variations = new_simulated_variations
+        end
+        Logging::KameleoonLogger.debug('RETURN: Visitor.update_simulated_variations(variations: %s)', variations)
+      end
+
       def add_data(*args, overwrite: true)
         Logging::KameleoonLogger.debug('CALL: Visitor.add_data(args: %s, overwrite: %s)', args, overwrite)
         @data.mutex.with_write_lock do
           args.each do |data|
             case data
-            when Kameleoon::UserAgent
+            when UserAgent
               @data.user_agent = data.value
-            when Kameleoon::DataManager::AssignedVariation
+            when AssignedVariation
               @data.add_variation(data, overwrite)
-            when Kameleoon::Device
+            when ForcedFeatureVariation
+              @data.add_forced_feature_variation(data)
+            when ForcedExperimentVariation
+              @data.add_forced_experiment_variation(data)
+            when Device
               @data.set_device(data, overwrite)
-            when Kameleoon::Browser
+            when Browser
               @data.set_browser(data, overwrite)
-            when Kameleoon::CustomData
+            when CustomData
               @data.add_custom_data(data, overwrite)
-            when Kameleoon::PageView
+            when PageView
               @data.add_page_view(data)
-            when Kameleoon::DataManager::PageViewVisit
+            when PageViewVisit
               @data.add_page_view_visit(data)
-            when Kameleoon::Conversion
+            when Conversion
               @data.add_conversion(data)
-            when Kameleoon::Cookie
+            when Cookie
               @data.cookie = data
-            when Kameleoon::OperatingSystem
+            when OperatingSystem
               @data.set_operating_system(data, overwrite)
-            when Kameleoon::Geolocation
+            when Geolocation
               @data.set_geolocation(data, overwrite)
-            when Kameleoon::KcsHeat
+            when KcsHeat
               @data.kcs_heat = data
-            when Kameleoon::VisitorVisits
+            when VisitorVisits
               @data.visitor_visits = data
-            when Kameleoon::UniqueIdentifier
+            when UniqueIdentifier
               @is_unique_identifier = data.value
             else
               Logging::KameleoonLogger.warning("Data has unsupported type '%s'", data.class)
@@ -218,7 +268,7 @@ module Kameleoon
     class VisitorData
       attr_reader :mutex, :device, :browser, :geolocation, :operating_system
       attr_accessor :last_activity_time, :legal_consent, :user_agent, :cookie, :kcs_heat, :visitor_visits,
-                    :mapping_identifier
+                    :mapping_identifier, :forced_variations, :simulated_variations
 
       def initialize
         Logging::KameleoonLogger.debug('CALL: VisitorData.new')
@@ -227,6 +277,22 @@ module Kameleoon
         Logging::KameleoonLogger.debug('RETURN: VisitorData.new')
       end
 
+      def get_from_map(map, key)
+        return nil if map.nil?
+
+        @mutex.with_read_lock do
+          return map[key]
+        end
+      end
+
+      def remove_from_map(map, key)
+        return false if map.nil?
+
+        @mutex.with_write_lock do
+          return map.delete(key).nil?
+        end
+      end
+
       def enumerate_sendable_data(&blk)
         blk.call(@device) unless @device.nil?
         blk.call(@browser) unless @browser.nil?
@@ -278,7 +344,7 @@ module Kameleoon
       end
 
       def add_variation(variation, overwrite)
-        @variations = {} if @variations.nil?
+        @variations ||= {}
         if overwrite || !@variations.include?(variation.experiment_id)
           @variations[variation.experiment_id] = variation
         end
@@ -289,7 +355,7 @@ module Kameleoon
       end
 
       def add_custom_data(custom_data, overwrite)
-        @custom_data_map = {} if @custom_data_map.nil?
+        @custom_data_map ||= {}
         if overwrite || !@custom_data_map.include?(custom_data.id)
           @custom_data_map[custom_data.id] = custom_data
         end
@@ -298,10 +364,10 @@ module Kameleoon
       def add_page_view(page_view)
         return if page_view.url.nil? || page_view.url.empty?
 
-        @page_view_visits = {} if @page_view_visits.nil?
+        @page_view_visits ||= {}
         visit = @page_view_visits[page_view.url]
         if visit.nil?
-          visit = DataManager::PageViewVisit.new(page_view)
+          visit = PageViewVisit.new(page_view)
         else
           visit.overwrite(page_view)
         end
@@ -309,7 +375,7 @@ module Kameleoon
       end
 
       def add_page_view_visit(page_view_visit)
-        @page_view_visits = {} if @page_view_visits.nil?
+        @page_view_visits ||= {}
         visit = @page_view_visits[page_view_visit.page_view.url]
         if visit.nil?
           visit = page_view_visit
@@ -320,7 +386,7 @@ module Kameleoon
       end
 
       def add_conversion(conversion)
-        @conversions = [] if @conversions.nil?
+        @conversions ||= []
         @conversions.push(conversion)
       end
 
@@ -331,6 +397,16 @@ module Kameleoon
       def set_operating_system(operating_system, overwrite)
         @operating_system = operating_system if overwrite || @operating_system.nil?
       end
+
+      def add_forced_feature_variation(forced_variation)
+        @simulated_variations ||= {}
+        @simulated_variations[forced_variation.feature_key] = forced_variation
+      end
+
+      def add_forced_experiment_variation(forced_variation)
+        @forced_variations ||= {}
+        @forced_variations[forced_variation.rule.experiment_id || 0] = forced_variation
+      end
     end
   end
 end

data/lib/kameleoon/exceptions.rb

@@ -30,10 +30,10 @@ module Kameleoon
       end
     end
 
-    # Feature Variable Not Found
-    class FeatureVariableNotFound < FeatureError
-      def initialize(key = '')
-        super("Feature variable #{key}")
+    # Feature Experiment Not Found
+    class FeatureExperimentNotFound < FeatureError
+      def initialize(id = '')
+        super("Experiment #{id}")
       end
     end
 
@@ -44,6 +44,13 @@ module Kameleoon
       end
     end
 
+    # Feature Variable Not Found
+    class FeatureVariableNotFound < FeatureError
+      def initialize(key = '')
+        super("Feature variable #{key}")
+      end
+    end
+
     # Feature Environment Disabled
     class FeatureEnvironmentDisabled < FeatureError
       def initialize(feature_key, environment = nil)

data/lib/kameleoon/kameleoon_client.rb

@@ -7,6 +7,7 @@ require 'kameleoon/configuration/data_file'
 require 'kameleoon/data/custom_data'
 require 'kameleoon/data/user_agent'
 require 'kameleoon/data/manager/assigned_variation'
+require 'kameleoon/data/manager/forced_experiment_variation'
 require 'kameleoon/data/manager/visitor_manager'
 require 'kameleoon/exceptions'
 require 'kameleoon/hybrid/manager'
@@ -75,7 +76,7 @@ module Kameleoon
       @remote_data_manager = Managers::RemoteData::RemoteDataManager.new(
         @data_manager, @network_manager, @visitor_manager
       )
-      @cookie_manager = Network::Cookie::CookieManager.new(@data_manager, config.top_level_domain)
+      @cookie_manager = Network::Cookie::CookieManager.new(@data_manager, @visitor_manager, config.top_level_domain)
       @readiness = ClientReadiness.new
       @targeting_manager = Targeting::TargetingManager.new(@data_manager, @visitor_manager)
 
@@ -611,16 +612,25 @@ module Kameleoon
     #
     # DEPRECATED. Please use `get_active_features` instead.
     def get_active_feature_list_for_visitor(visitor_code)
-      Logging::KameleoonLogger.info('[DEPRECATION] `get_active_feature_list_for_visitor` is deprecated.' \
-                                         ' Please use `get_active_features` instead.')
-      Logging::KameleoonLogger.info("CALL: KameleoonClient.get_active_feature_list_for_visitor(visitor_code: '%s')",
-                                    visitor_code)
+      Logging::KameleoonLogger.info(
+        '[DEPRECATION] `get_active_feature_list_for_visitor` is deprecated. Please use `get_active_features` instead.'
+      )
+      Logging::KameleoonLogger.info(
+        "CALL: KameleoonClient.get_active_feature_list_for_visitor(visitor_code: '%s')", visitor_code
+      )
       Utils::VisitorCode.validate(visitor_code)
+      visitor = @visitor_manager.get_visitor(visitor_code)
       list_keys = []
       @data_manager.data_file.feature_flags.each do |feature_key, feature_flag|
         next unless feature_flag.environment_enabled
 
-        variation, rule, = _calculate_variation_key_for_feature(visitor_code, feature_flag)
+        forced_variation = visitor&.get_forced_feature_variation(feature_key)
+        if forced_variation
+          variation = forced_variation.var_by_exp
+          rule = forced_variation.rule
+        else
+          variation, rule = _calculate_variation_key_for_feature(visitor_code, feature_flag)
+        end
         variation_key = _get_variation_key(variation, rule, feature_flag)
         list_keys.push(feature_key) if variation_key != Kameleoon::Configuration::VariationType::VARIATION_OFF
       end
@@ -649,12 +659,19 @@ module Kameleoon
       )
       Logging::KameleoonLogger.info("CALL: KameleoonClient.get_active_features(visitor_code: '%s')", visitor_code)
       Utils::VisitorCode.validate(visitor_code)
+      visitor = @visitor_manager.get_visitor(visitor_code)
       map_active_features = {}
 
       @data_manager.data_file.feature_flags.each_value do |feature_flag|
         next unless feature_flag.environment_enabled
 
-        var_by_exp, rule = _calculate_variation_key_for_feature(visitor_code, feature_flag)
+        forced_variation = visitor&.get_forced_feature_variation(feature_flag.feature_key)
+        if forced_variation
+          var_by_exp = forced_variation.var_by_exp
+          rule = forced_variation.rule
+        else
+          var_by_exp, rule = _calculate_variation_key_for_feature(visitor_code, feature_flag)
+        end
         variation_key = _get_variation_key(var_by_exp, rule, feature_flag)
 
         next if variation_key == Configuration::VariationType::VARIATION_OFF
@@ -701,6 +718,52 @@ module Kameleoon
       engine_tracking_code
     end
 
+    ##
+    # Sets or resets a forced variation for a visitor in a specific experiment,
+    # so the experiment will be evaluated to the variation for the visitor.
+    #
+    # In order to reset the forced variation set the `variation_key` parameter to `nil`.
+    # If the forced variation you want to reset does not exist, the method will have no effect.
+    #
+    # @param [String] visitor_code The unique visitor code identifying the visitor.
+    # @param [Integer] experiment_id The identifier of the experiment you want to set/reset the forced variation for.
+    # @param [String | NilClass] variation_key The identifier of the variation you want the experiment to be evaluated
+    # to. Set to `nil` to reset the forced variation.
+    # @param [Bool] force_targeting If `true`, the visitor will be targeted to the experiment regardless its
+    # conditions. Otherwise, the normal targeting logic will be preserved. Optional (defaults to `true`).
+    #
+    # @raise [Kameleoon::Exception::VisitorCodeInvalid] The provided **visitor code** is invalid.
+    # @raise [Kameleoon::Exception::FeatureExperimentNotFound] The provided **experiment id** does not exist in
+    # the feature flag.
+    # @raise [Kameleoon::Exception::FeatureVariationNotFound] The provided **variation key** does not belong to
+    # the experiment.
+    def set_forced_variation(visitor_code, experiment_id, variation_key, force_targeting: true)
+      Logging::KameleoonLogger.info(
+        "CALL: KameleoonClient.set_forced_variation(visitor_code: '%s', experiment_id: %d, variation_key: %s, " \
+        'force_targeting: %s)',
+        visitor_code, experiment_id, variation_key.nil? ? 'nil' : "'#{variation_key}'", force_targeting
+      )
+      Utils::VisitorCode.validate(visitor_code)
+      if variation_key.nil?
+        visitor = @visitor_manager.get_visitor(visitor_code)
+        visitor&.reset_forced_experiment_variation(experiment_id)
+      else
+        rule_info = @data_manager.data_file.rule_info_by_exp_id[experiment_id]
+        if rule_info.nil?
+          raise Exception::FeatureExperimentNotFound.new(experiment_id), "Experiment #{experiment_id} is not found"
+        end
+
+        var_by_exp = rule_info.rule.get_variation_by_key(variation_key)
+        forced_variation = DataManager::ForcedExperimentVariation.new(rule_info.rule, var_by_exp, force_targeting)
+        @visitor_manager.add_data(visitor_code, forced_variation)
+      end
+      Logging::KameleoonLogger.info(
+        "RETURN: KameleoonClient.set_forced_variation(visitor_code: '%s', experiment_id: %d, variation_key: %s, " \
+        'force_targeting: %s)',
+        visitor_code, experiment_id, variation_key.nil? ? 'nil' : "'#{variation_key}'", force_targeting
+      )
+    end
+
     private
 
     HYBRID_EXPIRATION_TIME = 5
@@ -853,9 +916,18 @@ module Kameleoon
         "CALL: KameleoonClient.get_variation_info(visitor_code: '%s', feature_flag: %s, track: %s)",
         visitor_code, feature_flag, track
       )
-      var_by_exp, rule = _calculate_variation_key_for_feature(visitor_code, feature_flag)
+      visitor = @visitor_manager.get_visitor(visitor_code)
+      forced_variation = visitor&.get_forced_feature_variation(feature_flag.feature_key)
+      if forced_variation
+        var_by_exp = forced_variation.var_by_exp
+        rule = forced_variation.rule
+      else
+        var_by_exp, rule = _calculate_variation_key_for_feature(visitor_code, feature_flag)
+      end
+      unless forced_variation&.simulated
+        save_variation(visitor_code, rule, var_by_exp, track: track)
+      end
       variation_key = _get_variation_key(var_by_exp, rule, feature_flag)
-      save_variation(visitor_code, rule, var_by_exp, track: track)
       Logging::KameleoonLogger.debug(
         "RETURN: KameleoonClient.get_variation_info(visitor_code: '%s', feature_flag: %s, track: %s)" \
         ' -> (variation_key: %s, variation_by_exposition: %s, rule: %s)',
@@ -872,9 +944,16 @@ module Kameleoon
         visitor_code, feature_key
       )
       feature_flag = @data_manager.data_file.get_feature_flag(feature_key)
-      variation, rule = _calculate_variation_key_for_feature(visitor_code, feature_flag)
+      visitor = @visitor_manager.get_visitor(visitor_code)
+      forced_variation = visitor&.get_forced_feature_variation(feature_flag.feature_key)
+      if forced_variation
+        variation = forced_variation.var_by_exp
+        rule = forced_variation.rule
+      else
+        variation, rule = _calculate_variation_key_for_feature(visitor_code, feature_flag)
+      end
+      save_variation(visitor_code, rule, variation) unless forced_variation&.simulated
       variation_key = _get_variation_key(variation, rule, feature_flag)
-      save_variation(visitor_code, rule, variation)
       @tracking_manager.add_visitor_code(visitor_code)
       Logging::KameleoonLogger.debug(
         "RETURN: KameleoonClient._get_feature_variation_key(visitor_code: '%s', feature_key: '%s')" \
@@ -910,28 +989,39 @@ module Kameleoon
         "CALL: KameleoonClient._calculate_variation_key_for_feature(visitor_code: '%s', feature_flag: %s)",
         visitor_code, feature_flag
       )
+      visitor = @visitor_manager.get_visitor(visitor_code)
       # no rules -> return default_variation_key
+      selected_variation = nil
+      selected_rule = nil
       feature_flag.rules.each do |rule|
+        forced_variation = visitor&.get_forced_experiment_variation(rule.experiment_id || 0)
+        if forced_variation&.force_targeting
+          # Forcing experiment variation in force-targeting mode
+          selected_variation = forced_variation.var_by_exp
+          selected_rule = rule
+          break
+        end
         # check if visitor is targeted for rule, else next rule
         next unless check_targeting(visitor_code, rule.experiment_id, rule)
 
-        vis = @visitor_manager.get_visitor(visitor_code)
+        unless forced_variation.nil?
+          # Forcing experiment variation in targeting-only mode
+          selected_variation = forced_variation.var_by_exp
+          selected_rule = rule
+          break
+        end
         # use mappingIdentifier instead of visitorCode if it was set up
-        code_for_hash = vis&.mapping_identifier || visitor_code
+        code_for_hash = visitor&.mapping_identifier || visitor_code
         # uses for rule exposition
         hash_rule = Utils::HashDouble.obtain_rule(code_for_hash, rule.id, rule.respool_time)
         Logging::KameleoonLogger.debug("Calculated hash_rule: %s for visitor_code: '%s'", hash_rule, code_for_hash)
         # check main expostion for rule with hashRule
         if hash_rule <= rule.exposition
           if rule.targeted_delivery_type?
-            Logging::KameleoonLogger.debug(
-              "RETURN: KameleoonClient._calculate_variation_key_for_feature(visitor_code: '%s', feature_flag: %s) " \
-                '-> (variation: %s, rule: %s)',
-              visitor_code, feature_flag, rule.first_variation, rule
-            )
-            return [rule.first_variation, rule]
+            selected_variation = rule.first_variation
+            selected_rule = rule
+            break
           end
-
           # uses for variation's expositions
           hash_variation = Utils::HashDouble.obtain_rule(code_for_hash, rule.experiment_id, rule.respool_time)
           Logging::KameleoonLogger.debug(
@@ -940,11 +1030,9 @@ module Kameleoon
           # get variation key with new hashVariation
           variation = rule.get_variation(hash_variation)
           unless variation.nil?
-            Logging::KameleoonLogger.debug(
-              "RETURN: KameleoonClient._calculate_variation_key_for_feature(visitor_code: '%s', " \
-                'feature_flag: %s) -> (variation: %s, rule: %s)', visitor_code, feature_flag, variation, rule
-            )
-            return [variation, rule]
+            selected_variation = variation
+            selected_rule = rule
+            break
           end
         # if visitor is targeted for targeted rule then break cycle -> return default
         elsif rule.targeted_delivery_type?
@@ -953,9 +1041,9 @@ module Kameleoon
       end
       Logging::KameleoonLogger.debug(
         "RETURN: KameleoonClient._calculate_variation_key_for_feature(visitor_code: '%s', feature_flag: %s) " \
-          '-> (variation: nil, rule: nil)', visitor_code, feature_flag
+          '-> (variation: %s, rule: %s)', visitor_code, feature_flag, selected_variation, selected_rule
       )
-      [nil, nil]
+      [selected_variation, selected_rule]
     end
 
     def _get_variation_key(var_by_exp, rule, feature_flag)

data/lib/kameleoon/network/cookie/cookie_manager.rb

@@ -1,21 +1,29 @@
 # frozen_string_literal: true
 
-require 'kameleoon/utils'
+require 'kameleoon/data/manager/forced_feature_variation'
 require 'kameleoon/logging/kameleoon_logger'
+require 'kameleoon/utils'
 
 module Kameleoon
   module Network
     module Cookie
-      COOKIE_KEY_JS = '_js_'
       VISITOR_CODE_COOKIE = 'kameleoonVisitorCode'
+      KAMELEOON_SIMULATION_FF_DATA = 'kameleoonSimulationFFData'
+      EXPERIMENT_ID_KEY = 'expId'
+      VARIATION_ID_KEY = 'varId'
       COOKIE_TTL_SECONDS = 380 * 86_400 # 380 days in seconds
 
       class CookieManager
-        def initialize(data_manager, top_level_domain)
-          Logging::KameleoonLogger.debug("CALL: CookieManager.new(top_level_domain: '%s')", top_level_domain)
+        def initialize(data_manager, visitor_manager, top_level_domain)
+          Logging::KameleoonLogger.debug(
+            "CALL: CookieManager.new(data_manager, visitor_manager, top_level_domain: '%s')", top_level_domain
+          )
           @data_manager = data_manager
+          @visitor_manager = visitor_manager
           @top_level_domain = top_level_domain
-          Logging::KameleoonLogger.debug("RETURN: CookieManager.new(top_level_domain: '%s')", top_level_domain)
+          Logging::KameleoonLogger.debug(
+            "RETURN: CookieManager.new(data_manager, visitor_manager, top_level_domain: '%s')", top_level_domain
+          )
         end
 
         def get_or_add(cookies, default_visitor_code = nil)
@@ -25,35 +33,8 @@ module Kameleoon
             "CALL: CookieManager.get_or_add(cookies: %s, default_visitor_code: '%s')",
             cookies, default_visitor_code
           )
-
-          visitor_code = get_visitor_code_from_cookies(cookies)
-          unless visitor_code.nil?
-            Utils::VisitorCode.validate(visitor_code)
-            Logging::KameleoonLogger.debug("Read visitor code '%s' from cookies %s", visitor_code, cookies)
-            # Remove adding cookies when we will be sure that it doesn't break anything
-            add(visitor_code, cookies) unless @data_manager.visitor_code_managed?
-            Logging::KameleoonLogger.debug(
-              "RETURN: CookieManager.get_or_add(cookies: %s, default_visitor_code: '%s') -> (visitor_code: '%s')",
-              cookies, default_visitor_code, visitor_code
-            )
-            return visitor_code
-          end
-
-          if default_visitor_code.nil?
-            visitor_code = Utils::VisitorCode.generate
-            Logging::KameleoonLogger.debug("Generated new visitor code '%s'", visitor_code)
-            add(visitor_code, cookies) unless @data_manager.visitor_code_managed?
-            Logging::KameleoonLogger.debug(
-              "RETURN: CookieManager.get_or_add(cookies: %s, default_visitor_code: '%s') -> (visitor_code: '%s')",
-              cookies, default_visitor_code, visitor_code
-            )
-            return visitor_code
-          end
-
-          visitor_code = default_visitor_code
-          Utils::VisitorCode.validate(visitor_code)
-          Logging::KameleoonLogger.debug("Used default visitor code '{%s}'", default_visitor_code)
-          add(visitor_code, cookies)
+          visitor_code = get_or_add_visitor_code(cookies, default_visitor_code)
+          process_simulated_variations(cookies, visitor_code)
           Logging::KameleoonLogger.debug(
             "RETURN: CookieManager.get_or_add(cookies: %s, default_visitor_code: '%s') -> (visitor_code: '%s')",
             cookies, default_visitor_code, visitor_code
@@ -78,9 +59,34 @@ module Kameleoon
 
         private
 
+        def get_or_add_visitor_code(cookies, default_visitor_code)
+          visitor_code = get_value_from_cookies(cookies, VISITOR_CODE_COOKIE)
+          unless visitor_code.nil?
+            Utils::VisitorCode.validate(visitor_code)
+            Logging::KameleoonLogger.debug("Read visitor code '%s' from cookies %s", visitor_code, cookies)
+            # Remove adding cookies when we will be sure that it doesn't break anything
+            add(visitor_code, cookies) unless @data_manager.visitor_code_managed?
+            return visitor_code
+          end
+
+          if default_visitor_code.nil?
+            visitor_code = Utils::VisitorCode.generate
+            Logging::KameleoonLogger.debug("Generated new visitor code '%s'", visitor_code)
+            add(visitor_code, cookies) unless @data_manager.visitor_code_managed?
+            return visitor_code
+          end
+
+          visitor_code = default_visitor_code
+          Utils::VisitorCode.validate(visitor_code)
+          Logging::KameleoonLogger.debug("Used default visitor code '{%s}'", default_visitor_code)
+          add(visitor_code, cookies)
+          visitor_code
+        end
+
         def add(visitor_code, cookies)
-          Logging::KameleoonLogger.debug("CALL: CookieManager.add(visitor_code: '%s', cookies: %s)",
-                                         visitor_code, cookies)
+          Logging::KameleoonLogger.debug(
+            "CALL: CookieManager.add(visitor_code: '%s', cookies: %s)", visitor_code, cookies
+          )
           cookie = {
             value: visitor_code,
             expires: Time.now + COOKIE_TTL_SECONDS,
@@ -88,8 +94,9 @@ module Kameleoon
             domain: @top_level_domain
           }
           cookies[VISITOR_CODE_COOKIE] = cookie
-          Logging::KameleoonLogger.debug("RETURN: CookieManager.add(visitor_code: '%s', cookies: %s)",
-                                         visitor_code, cookies)
+          Logging::KameleoonLogger.debug(
+            "RETURN: CookieManager.add(visitor_code: '%s', cookies: %s)", visitor_code, cookies
+          )
           cookies
         end
 
@@ -100,22 +107,90 @@ module Kameleoon
           cookies
         end
 
-        def get_visitor_code_from_cookies(cookies)
-          Logging::KameleoonLogger.debug('CALL: CookieManager.get_visitor_code_from_cookies(cookies: %s)', cookies)
-          cookie = cookies[VISITOR_CODE_COOKIE]
+        def process_simulated_variations(cookies, visitor_code)
+          raw = get_value_from_cookies(cookies, KAMELEOON_SIMULATION_FF_DATA)
+          return if raw.nil?
+
+          variations = parse_simulated_variations(raw)
+          visitor = @visitor_manager.get_or_create_visitor(visitor_code)
+          visitor.update_simulated_variations(variations)
+        rescue StandardError => e
+          Logging::KameleoonLogger.error('Failed to process simulated variations cookie: %s', e)
+        end
+
+        def parse_simulated_variations(raw)
+          data_file = @data_manager.data_file
+          jobj = JSON.parse(raw)
+          return nil unless jobj.is_a?(Hash)
+
+          variations = []
+          jobj.each do |feature_key, value|
+            unless feature_key.is_a?(String) && value.is_a?(Hash)
+              log_malformed_simulated_variations_cookie(raw)
+              next
+            end
+
+            experiment_id = value[EXPERIMENT_ID_KEY]
+            if !experiment_id.is_a?(Integer) || experiment_id.negative?
+              log_malformed_simulated_variations_cookie(raw)
+              next
+            end
+
+            unless experiment_id.zero?
+              variation_id = value[VARIATION_ID_KEY]
+              if !variation_id.is_a?(Integer) || variation_id.negative?
+                log_malformed_simulated_variations_cookie(raw)
+                next
+              end
+            end
+            simulated_variation = simulated_variation_from_data_file(
+              data_file, feature_key, experiment_id, variation_id
+            )
+            variations.push(simulated_variation) unless simulated_variation.nil?
+          end
+          variations
+        end
+
+        def log_malformed_simulated_variations_cookie(raw)
+          Logging::KameleoonLogger.error('Malformed simulated variations cookie: %s', raw)
+        end
+
+        def simulated_variation_from_data_file(data_file, feature_key, experiment_id, variation_id)
+          feature_flag = data_file.feature_flags[feature_key]
+          unless feature_flag
+            Logging::KameleoonLogger.error("Simulated feature flag '%s' is not found", feature_key)
+            return nil
+          end
+          return DataManager::ForcedFeatureVariation.new(feature_key, nil, nil, true) if experiment_id.zero?
+
+          rule = feature_flag.rules.find { |r| r.experiment_id == experiment_id }
+          unless rule
+            Logging::KameleoonLogger.error('Simulated experiment %d is not found', experiment_id)
+            return nil
+          end
+          var_by_exp = rule.variation_by_exposition.find { |v| v.variation_id == variation_id }
+          unless var_by_exp
+            Logging::KameleoonLogger.error('Simulated variation %d is not found', variation_id)
+            return nil
+          end
+          DataManager::ForcedFeatureVariation.new(feature_key, rule, var_by_exp, true)
+        end
+
+        def get_value_from_cookies(cookies, key)
+          Logging::KameleoonLogger.debug('CALL: CookieManager.get_value_from_cookies(cookies: %s)', cookies)
+          cookie = cookies[key]
           case cookie
           when String
-            visitor_code = cookie
+            value = cookie
           when Hash
-            visitor_code = cookie[:value]
+            value = cookie[:value]
           end
-          visitor_code = visitor_code[COOKIE_KEY_JS.size..] if visitor_code&.start_with?(COOKIE_KEY_JS)
-          visitor_code = nil if visitor_code&.empty?
+          value = nil if value&.empty?
           Logging::KameleoonLogger.debug(
-            "RETURN: CookieManager.get_visitor_code_from_cookies(cookies: %s) -> (visitor_code: '%s')",
-            cookies, visitor_code
+            "RETURN: CookieManager.get_value_from_cookies(cookies: %s) -> (value: '%s')",
+            cookies, value
           )
-          visitor_code
+          value
         end
       end
     end

data/lib/kameleoon/types/variation.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'kameleoon/configuration/variation'
+
 module Kameleoon
   # Module which contains all internal data of SDK
   module Types
@@ -19,7 +21,7 @@ module Kameleoon
       end
 
       def active?
-        variation_key != Configuration::VariationType::VARIATION_OFF
+        @key != Configuration::VariationType::VARIATION_OFF
       end
     end
   end

data/lib/kameleoon/utils.rb

@@ -75,6 +75,7 @@ module Kameleoon
       HTTPS = 'https://'
       REGEX_DOMAIN = /^(\.?(([a-zA-Z\d][a-zA-Z\d-]*[a-zA-Z\d])|[a-zA-Z\d]))
 (\.(([a-zA-Z\d][a-zA-Z\d-]*[a-zA-Z\d])|[a-zA-Z\d])){1,126}$/x.freeze
+      LOCALHOST = 'localhost'
 
       def self.validate_top_level_domain(top_level_domain)
         return nil if top_level_domain.nil? || top_level_domain.empty?
@@ -91,9 +92,13 @@ module Kameleoon
           break
         end
 
-        unless REGEX_DOMAIN.match?(top_level_domain)
-          Logging::KameleoonLogger.error("The top-level domain '%s' is invalid.", top_level_domain)
-          return nil
+        if !REGEX_DOMAIN.match?(top_level_domain) && top_level_domain != LOCALHOST
+          Logging::KameleoonLogger.error(
+            "The top-level domain '%s' is invalid. The value has been set as provided, but it does not meet " \
+              'the required format for proper SDK functionality. Please check the domain for correctness.',
+            top_level_domain
+          )
+          return top_level_domain
         end
 
         top_level_domain

data/lib/kameleoon/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module Kameleoon
-  SDK_VERSION = '3.6.0'
+  SDK_VERSION = '3.7.0'
   SDK_NAME = 'RUBY'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kameleoon-client-ruby
 version: !ruby/object:Gem::Version
-  version: 3.6.0
+  version: 3.7.0
 platform: ruby
 authors:
 - Kameleoon
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-11-14 00:00:00.000000000 Z
+date: 2024-12-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: em-http-request
@@ -95,6 +95,9 @@ files:
 - lib/kameleoon/data/manager/assigned_variation.rb
 - lib/kameleoon/data/manager/data_array_storage.rb
 - lib/kameleoon/data/manager/data_map_storage.rb
+- lib/kameleoon/data/manager/forced_experiment_variation.rb
+- lib/kameleoon/data/manager/forced_feature_variation.rb
+- lib/kameleoon/data/manager/forced_variation.rb
 - lib/kameleoon/data/manager/page_view_visit.rb
 - lib/kameleoon/data/manager/visitor.rb
 - lib/kameleoon/data/manager/visitor_manager.rb