kameleoon-client-ruby 3.19.0 → 3.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dde5f6ebb9e6779b9bf8d4edbdded4e11b82aa642ec046bd2493306e0b2a7ad8
-  data.tar.gz: 5a15f627b2832ec10f001ef7ee061fa31c6dbd618b02ec55ff9d1d66ee17d5a8
+  metadata.gz: ea79d87e992d2f5bf9829c8082427c18251101be90f50c769b46242a1f4fc272
+  data.tar.gz: 305d07e5adee2b86cf58acc2b01f8a47f4161daeb06efbc8239e7a585ec355cd
 SHA512:
-  metadata.gz: 91d3f34ab6855ed62d571fa5d40b85a04504926f2d38650c9b62f052bd9f0b79b0ce95ece6636fa37ecc5062020f2361bc5e0e8af80383b0d2b377dffd5919e7
-  data.tar.gz: c2e5efd80b73d5f8ce9c48a6f069aadda0fc7d1a6bc390a2d98af4a8a69b36928bac0188c77406bd793d8db6c4701df24838c67efc89b98d4d0e6b7e425b9c68
+  metadata.gz: c3319b271cf4053f01e9fab40b0133cd609a800f55fd3de84f19b76209d2fcbe5438672aa24a42dc39c1dd4dade97641956c2cff1f5c5c0cee8ece0d80636ca8
+  data.tar.gz: 10dfdd35cf97d0adb20ed4a866c4b6739be6ec11458c267a550bf02f6e5ae2542b282b2c30ac33ae94797e3e4a8ce8dd6187406ef1d85603c2d02d0b9f09d44f

data/lib/kameleoon/client_readiness.rb

@@ -3,37 +3,47 @@
 require 'concurrent'
 
 module Kameleoon
+  # ClientReadiness is a cross-thread latch signalling that the SDK has
+  # successfully loaded its configuration.
+  #
+  # It is created on the thread that builds the client but released (`set`) from
+  # the background thread(s) performing configuration fetches, so it relies on
+  # Concurrent::Event (which allows cross-thread release) rather than a
+  # read/write lock (whose write lock must be released by the acquiring thread).
+  #
+  # A failed fetch does NOT release the latch: the client keeps retrying in the
+  # background and the latch is released as soon as any fetch succeeds. Callers
+  # should bound their `wait` with a timeout so they are never blocked forever
+  # when the configuration can never be loaded.
   class ClientReadiness
-    attr_reader :is_initializing, :success
-
     def initialize
-      @is_initializing = false
       @success = false
-      @condition = Concurrent::ReadWriteLock.new
-      reset
+      @event = Concurrent::Event.new
     end
 
-    def reset
-      @success = false
-      unless @is_initializing
-        @is_initializing = true
-        @condition.acquire_write_lock
-      end
+    # @return [Boolean] whether the SDK has become ready (configuration loaded).
+    def success
+      @success
     end
 
+    # Record a fetch outcome. A successful fetch marks the client ready and
+    # unblocks all waiting threads; a failed fetch is ignored so that a later
+    # successful retry can still release the latch. Idempotent and safe to call
+    # from any thread.
     def set(success)
-      @success = success
-      if @is_initializing
-        @condition.release_write_lock
-        @is_initializing = false
-      end
+      return unless success
+
+      @success = true
+      @event.set
     end
 
-    def wait
-      if @is_initializing
-        @condition.acquire_read_lock
-        @condition.release_read_lock
-      end
+    # Block until the SDK becomes ready or the timeout elapses.
+    #
+    # @param timeout [Numeric, nil] maximum number of seconds to wait;
+    #   nil waits indefinitely.
+    # @return [Boolean] whether the SDK is ready.
+    def wait(timeout = nil)
+      @event.wait(timeout)
       @success
     end
   end

data/lib/kameleoon/data/browser.rb

@@ -49,7 +49,7 @@ module Kameleoon
       @version = version
     end
 
-    def obtain_full_post_text_line
+    def query
       params = {
         eventType: 'staticData',
         browserIndex: @type,

data/lib/kameleoon/data/conversion.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'json'
+require 'set'
 require 'kameleoon/data/custom_data'
 require 'kameleoon/network/uri_helper'
 require 'kameleoon/utils'
@@ -9,11 +10,11 @@ require_relative 'data'
 module Kameleoon
   # Conversion class uses for tracking conversion
   class Conversion < DuplicationSafeData
-    attr_reader :goal_id, :revenue, :negative, :metadata
+    attr_reader :goal_id, :revenue, :negative, :metadata, :assignment_time
 
     def to_s
       "Conversion{goal_id:#{@goal_id},revenue:#{@revenue},negative:#{@negative}," \
-      "metadata:#{Utils::Strval.obj_to_s(@metadata)}}"
+      "metadata:#{Utils::Strval.obj_to_s(@metadata)},assignment_time:#{@assignment_time}}"
     end
 
     # @param [Integer] goal_id Id of the goal associated to the conversion
@@ -26,9 +27,17 @@ module Kameleoon
       @revenue = revenue || 0.0
       @negative = negative || false
       @metadata = metadata
+      @assignment_time = Time.now.to_f
     end
 
-    def obtain_full_post_text_line
+    # @api private
+    def self.build_internal(goal_id, revenue = 0.0, negative = false, metadata: nil, assignment_time: nil)
+      conversion = new(goal_id, revenue, negative, metadata: metadata)
+      conversion.instance_variable_set(:@assignment_time, assignment_time || Time.now.to_f)
+      conversion
+    end
+
+    def query
       params = {
         eventType: 'conversion',
         goalId: @goal_id,

data/lib/kameleoon/data/custom_data.rb

@@ -85,7 +85,7 @@ module Kameleoon
       @index
     end
 
-    def obtain_full_post_text_line
+    def query
       str_values = JSON.generate(Hash[@values.collect { |k| [k, 1] }])
       params = {
         eventType: 'customData',

data/lib/kameleoon/data/data.rb

@@ -38,7 +38,7 @@ module Kameleoon
       @state = DataState::UNSENT
     end
 
-    def obtain_full_post_text_line
+    def query
       raise KameleoonError.new('ToDo: implement this method.'), 'ToDo: implement this method.'
     end
 

data/lib/kameleoon/data/device.rb

@@ -24,7 +24,7 @@ module Kameleoon
       @device_type = device_type
     end
 
-    def obtain_full_post_text_line
+    def query
       params = {
         eventType: 'staticData',
         deviceType: @device_type,

data/lib/kameleoon/data/geolocation.rb

@@ -26,7 +26,7 @@ module Kameleoon
       @longitude = longitude
     end
 
-    def obtain_full_post_text_line
+    def query
       params = {
         eventType: 'geolocation',
         nonce: nonce

data/lib/kameleoon/data/manager/assigned_variation.rb

@@ -25,10 +25,10 @@ module Kameleoon
         @experiment_id = experiment_id
         @variation_id = variation_id
         @rule_type = rule_type
-        @assignment_time = assignment_time || Time.new.to_i
+        @assignment_time = assignment_time || Time.now.to_f
       end
 
-      def obtain_full_post_text_line
+      def query
         params = {
           eventType: EVENT_TYPE,
           id: @experiment_id,

data/lib/kameleoon/data/manager/page_view_visit.rb

@@ -12,7 +12,7 @@ module Kameleoon
       def initialize(page_view, count = 1, timestamp = nil)
         @page_view = page_view
         @count = count
-        @last_timestamp = timestamp.nil? ? Time.new.to_i : timestamp
+        @last_timestamp = timestamp.nil? ? Time.new.to_f : timestamp
       end
 
       # Not thread-save method, should be called in synchronized code
@@ -20,7 +20,7 @@ module Kameleoon
       def overwrite(page_view)
         @page_view = page_view
         @count += 1
-        @last_timestamp = Time.new.to_i
+        @last_timestamp = Time.new.to_f
       end
 
       # Not thread-save method, should be called in synchronized code

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

@@ -55,7 +55,7 @@ module Kameleoon
       end
 
       def update_last_activity_time
-        @data.last_activity_time = Time.new.to_i
+        @data.last_activity_time = Time.new.to_f
       end
 
       def enumerate_sendable_data(&blk)
@@ -322,7 +322,7 @@ module Kameleoon
 
       def initialize
         Logging::KameleoonLogger.debug('CALL: VisitorData.new')
-        @time_started = (Time.now.to_f * 1000).to_i
+        @time_started = Time.now.to_f
         @mutex = Concurrent::ReadWriteLock.new
         @legal_consent = LegalConsent::UNKNOWN
         Logging::KameleoonLogger.debug('RETURN: VisitorData.new')

data/lib/kameleoon/data/manager/visitor_manager.rb

@@ -154,7 +154,7 @@ module Kameleoon
 
       def purge
         Logging::KameleoonLogger.debug('CALL: VisitorManager.purge')
-        expired_time = Time.new.to_i - @expiration_period
+        expired_time = Time.new.to_f - @expiration_period
         @visitors.each_pair do |vc, v|
           next if v.last_activity_time >= expired_time
 

data/lib/kameleoon/data/mapping_identifier.rb

@@ -28,7 +28,7 @@ module Kameleoon
       false
     end
 
-    def obtain_full_post_text_line
+    def query
       mip = Kameleoon::Network::UriHelper.encode_query({ mappingIdentifier: true })
       "#{super}&#{mip}"
     end

data/lib/kameleoon/data/operating_system.rb

@@ -62,7 +62,7 @@ module Kameleoon
       @os_type = os_type
     end
 
-    def obtain_full_post_text_line
+    def query
       params = {
         eventType: 'staticData',
         os: OperatingSystemType.name_from_type(@os_type),
@@ -73,4 +73,3 @@ module Kameleoon
     end
   end
 end
-

data/lib/kameleoon/data/page_view.rb

@@ -25,7 +25,7 @@ module Kameleoon
       @referrers = referrers.instance_of?(Integer) ? [referrers] : referrers
     end
 
-    def obtain_full_post_text_line
+    def query
       params = {
         eventType: 'page',
         href: @url,

data/lib/kameleoon/data/personalization.rb

@@ -2,15 +2,16 @@
 
 module Kameleoon
   class Personalization
-    attr_reader :id, :variation_id
+    attr_reader :id, :variation_id, :assignment_time
 
-    def initialize(id, variation_id)
+    def initialize(id, variation_id, assignment_time: nil)
       @id = id
       @variation_id = variation_id
+      @assignment_time = assignment_time || Time.now.to_f
     end
 
     def to_s
-      "Personalization{id:#{@id},variation_id:#{@variation_id}}"
+      "Personalization{id:#{@id},variation_id:#{@variation_id},assignment_time:#{@assignment_time}}"
     end
   end
 end

data/lib/kameleoon/data/targeted_segment.rb

@@ -14,7 +14,7 @@ module Kameleoon
       @id = id
     end
 
-    def obtain_full_post_text_line
+    def query
       params = {
         eventType: EVENT_TYPE,
         id: @id,

data/lib/kameleoon/data/visitor_visits.rb

@@ -33,7 +33,7 @@ module Kameleoon
       )
     end
 
-    def obtain_full_post_text_line
+    def query
       params = {
         eventType: 'staticData',
         visitNumber: @visit_number,

data/lib/kameleoon/kameleoon_client.rb

@@ -92,9 +92,24 @@ module Kameleoon
                                     site_code, config)
     end
 
-    def wait_init
-      Logging::KameleoonLogger.info('CALL: KameleoonClient.wait_init')
-      result = @readiness.wait
+    ##
+    # Block until the SDK has loaded its configuration and is ready to use.
+    #
+    # If the initial fetch fails the client keeps retrying in the background, so
+    # this method returns as soon as any fetch succeeds. The wait is always
+    # bounded by a timeout, so it never blocks indefinitely: when the timeout
+    # elapses before the configuration is loaded, the method returns false.
+    #
+    # @param [Integer, nil] timeout_millisecond Maximum time to wait, in
+    #   milliseconds. When nil or negative, config.default_timeout_millisecond
+    #   is applied.
+    # @return [Boolean] true if the SDK is ready, false if the timeout elapsed first.
+    def wait_init(timeout_millisecond = nil)
+      Logging::KameleoonLogger.info('CALL: KameleoonClient.wait_init(timeout_millisecond: %s)', timeout_millisecond)
+      if timeout_millisecond.nil? || timeout_millisecond.negative?
+        timeout_millisecond = @config.default_timeout_millisecond
+      end
+      result = @readiness.wait(timeout_millisecond / 1000.0)
       Logging::KameleoonLogger.info('RETURN: KameleoonClient.wait_init -> (result: %s)', result)
       result
     end
@@ -822,7 +837,8 @@ module Kameleoon
           Logging::KameleoonLogger.error('Initial configuration fetch failed: %s', e)
         end
         @readiness.set(ok)
-        manage_configuration_update(@data_manager.data_file.settings.real_time_update) if ok
+        real_time_update = ok && @data_manager.data_file.settings.real_time_update
+        manage_configuration_update(real_time_update)
       end
     end
 
@@ -834,6 +850,9 @@ module Kameleoon
         rescue StandardError => e
           Logging::KameleoonLogger.error('Error occurred during configuration fetching: %s', e)
         end
+        # Release any threads still waiting in `wait_init` once a (re)fetch
+        # finally succeeds after an unsuccessful initial fetch.
+        @readiness.set(ok)
         real_time_update = @data_manager.data_file.settings.real_time_update
         if !ok && real_time_update
           @data_manager.data_file.settings.real_time_update = false

data/lib/kameleoon/managers/remote_data/remote_visitor_data.rb

@@ -32,7 +32,9 @@ module Kameleoon
             prev_visits = []
             previous_visits.each_index do |i|
               visit = previous_visits[i]
-              prev_visits.push(VisitorVisits::Visit.new(visit['timeStarted'] || 0, visit['timeLastEvent']))
+              prev_visits.push(
+                VisitorVisits::Visit.new(ms_to_s(visit['timeStarted'] || 0), ms_to_s(visit['timeLastEvent']))
+              )
               parse_visit(visit, i + 1)
             end
             @visitor_visits = VisitorVisits.new(prev_visits, @visit_number)
@@ -113,7 +115,7 @@ module Kameleoon
             page_view_visit = @page_view_visits[href]
             if page_view_visit.nil?
               page_view = PageView.new(href, page_event['data']['title'])
-              @page_view_visits[href] = DataManager::PageViewVisit.new(page_view, 1, page_event['time'])
+              @page_view_visits[href] = DataManager::PageViewVisit.new(page_view, 1, ms_to_s(page_event['time']))
             else
               page_view_visit.increase_page_visits
             end
@@ -128,7 +130,7 @@ module Kameleoon
 
             @experiments[id] = DataManager::AssignedVariation.new(
               id, experiment_event['data']['variationId'],
-              Configuration::RuleType::UNKNOWN, assignment_time: experiment_event['time']
+              Configuration::RuleType::UNKNOWN, assignment_time: ms_to_s(experiment_event['time'])
             )
           end
         end
@@ -137,7 +139,10 @@ module Kameleoon
           @conversions = [] if @conversions.nil?
           conversion_events.each do |conversion_event|
             data = conversion_event['data']
-            conversion = Conversion.new(data['goalId'], data['revenue'], data['negative'])
+            conversion = Conversion.send(
+              :build_internal, data['goalId'], data['revenue'], data['negative'],
+              assignment_time: ms_to_s(conversion_event['time'])
+            )
             @conversions.push(conversion)
           end
         end
@@ -173,10 +178,20 @@ module Kameleoon
             id = personalization_event['data']['id']
             next if @personalizations.include?(id)
 
-            @personalizations[id] = Personalization.new(id, personalization_event['data']['variationId'])
+            @personalizations[id] = Personalization.new(
+              id,
+              personalization_event['data']['variationId'],
+              assignment_time: ms_to_s(personalization_event['time'])
+            )
           end
         end
 
+        def ms_to_s(timestamp)
+          return nil if timestamp.nil?
+
+          timestamp / 1000.0
+        end
+
         def conversions_single_objects
           objects = []
           objects += @conversions unless @conversions.nil?

data/lib/kameleoon/managers/tracking/tracking_builder.rb

@@ -127,7 +127,7 @@ module Kameleoon
           )
           user_agent = visitor&.user_agent
           unsent_data.each do |data|
-            line = data.obtain_full_post_text_line
+            line = data.query
             next if line.empty?
 
             line = add_line_params(line, visitor_code_param, user_agent)

data/lib/kameleoon/network/access_token_source.rb

@@ -39,7 +39,7 @@ module Kameleoon
 
       def get_token(timeout = nil)
         Logging::KameleoonLogger.debug('CALL: AccessTokenSource.getToken(timeout: %s)', timeout)
-        now = Time.new.to_i
+        now = Time.new.to_f
         token = @cached_token
         return call_fetch_token(timeout) if token.nil? || token.expired?(now)
 
@@ -105,7 +105,7 @@ module Kameleoon
       end
 
       def handle_fetched_token(token, expires_in)
-        now = Time.new.to_i
+        now = Time.new.to_f
         exp_time = now + expires_in - TOKEN_EXPIRATION_GAP
         if expires_in > TOKEN_OBSOLESCENCE_GAP
           obs_time = now + expires_in - TOKEN_OBSOLESCENCE_GAP

data/lib/kameleoon/network/activity_event.rb

@@ -18,7 +18,7 @@ module Kameleoon
         @sent = false
       end
 
-      def obtain_full_post_text_line
+      def query
         params = {
           eventType: EVENT_TYPE,
           nonce: Kameleoon::Utils.generate_random_string(Kameleoon::NONCE_LENGTH)

data/lib/kameleoon/targeting/conditions/conversion_condition.rb

@@ -1,28 +1,43 @@
 # frozen_string_literal: true
 
 require 'kameleoon/data/conversion'
-require 'kameleoon/data/manager/data_array_storage'
+require 'kameleoon/targeting/conditions/visitor_scope_condition'
 
 module Kameleoon
-  # @api private
   module Targeting
-    # ConversionCondition is a condition for checking targeting of conversions of visitor
-    class ConversionCondition < Condition
+    class ConversionCondition < VisitorScopeCondition
       def initialize(json_condition)
-        super(json_condition)
+        super(json_condition, VisitScope::VISITOR)
         @goal_id = json_condition['goalId']
       end
 
-      def check(conversion_storage)
-        return false unless conversion_storage.is_a?(Kameleoon::DataManager::DataArrayStorage)
-        return true if @goal_id.nil?
+      def check(data)
+        return false unless data.is_a?(TargetingData)
 
-        is_targeted = false
-        conversion_storage.enumerate do |conversion|
-          is_targeted = conversion.is_a?(Kameleoon::Conversion) && (@goal_id == conversion.goal_id)
-          break if is_targeted
+        threshold = assignment_threshold(data.visitor_visits)
+        targeted_conversion?(data.conversions, threshold)
+      end
+
+      private
+
+      def targeted_conversion?(conversions, threshold)
+        return false unless conversions.respond_to?(:enumerate)
+
+        targeted = false
+        conversions.enumerate do |conversion|
+          targeted = (@goal_id.nil? || @goal_id == conversion.goal_id) && conversion.assignment_time >= threshold
+          break if targeted
+        end
+        targeted
+      end
+
+      class TargetingData
+        attr_reader :conversions, :visitor_visits
+
+        def initialize(conversions, visitor_visits)
+          @conversions = conversions
+          @visitor_visits = visitor_visits
         end
-        is_targeted
       end
     end
   end

data/lib/kameleoon/targeting/conditions/exclusive_experiment_condition.rb

@@ -1,13 +1,13 @@
 # frozen_string_literal: true
 
 require 'kameleoon/logging/kameleoon_logger'
-require 'kameleoon/targeting/condition'
+require 'kameleoon/targeting/conditions/visitor_scope_condition'
 
 module Kameleoon
   # @api private
   module Targeting
     # ExclusiveExperiment represents an instance of Exclusive Experiment condition in user account
-    class ExclusiveExperimentCondition < Condition
+    class ExclusiveExperimentCondition < VisitorScopeCondition
       module CampaignType
         EXPERIMENT = 'EXPERIMENT'
         PERSONALIZATION = 'PERSONALIZATION'
@@ -15,21 +15,22 @@ module Kameleoon
       end
 
       def initialize(json_condition)
-        super(json_condition)
+        super(json_condition, VisitScope::VISITOR)
 
         @campaign_type = json_condition['campaignType']
       end
 
       def check(data)
-        return false unless data.is_a?(ExclusiveExperimentInfo)
+        return false unless data.is_a?(TargetingData)
 
+        threshold = assignment_threshold(data.visitor_visits)
         case @campaign_type
         when CampaignType::EXPERIMENT
-          return check_experiment(data)
+          return check_experiment(data, threshold)
         when CampaignType::PERSONALIZATION
-          return check_personalization(data)
+          return check_personalization(data, threshold)
         when CampaignType::ANY
-          return check_personalization(data) && check_experiment(data)
+          return check_personalization(data, threshold) && check_experiment(data, threshold)
         end
         Logging::KameleoonLogger.error("Unexpected campaign type for '#{type}' condition: '#{@campaign_type}'")
         false
@@ -37,23 +38,41 @@ module Kameleoon
 
       private
 
-      def check_experiment(data)
-        size = data.variations_storage&.size || 0
-        size.zero? || (size == 1 && !data.variations_storage.get(data.current_experiment_id).nil?)
+      def check_experiment(data, threshold)
+        return true if data.variations.nil?
+
+        result = true
+        data.variations.enumerate do |variation|
+          if variation.experiment_id != data.current_experiment_id && variation.assignment_time >= threshold
+            result = false
+            break
+          end
+        end
+        result
       end
 
-      def check_personalization(data)
-        (data.personalizations_storage&.size || 0).zero?
+      def check_personalization(data, threshold)
+        return true if data.personalizations.nil?
+
+        result = true
+        data.personalizations.enumerate do |personalization|
+          if personalization.assignment_time >= threshold
+            result = false
+            break
+          end
+        end
+        result
       end
-    end
 
-    class ExclusiveExperimentInfo
-      attr_reader :current_experiment_id, :variations_storage, :personalizations_storage
+      class TargetingData
+        attr_reader :current_experiment_id, :variations, :personalizations, :visitor_visits
 
-      def initialize(current_experiment_id, variations_storage, personalizations_storage)
-        @current_experiment_id = current_experiment_id
-        @variations_storage = variations_storage
-        @personalizations_storage = personalizations_storage
+        def initialize(current_experiment_id, variations, personalizations, visitor_visits = nil)
+          @current_experiment_id = current_experiment_id
+          @variations = variations
+          @personalizations = personalizations
+          @visitor_visits = visitor_visits
+        end
       end
     end
   end

data/lib/kameleoon/targeting/conditions/target_experiment_condition.rb

@@ -1,17 +1,17 @@
 # frozen_string_literal: true
 
 require 'kameleoon/logging/kameleoon_logger'
-require 'kameleoon/targeting/condition'
+require 'kameleoon/targeting/conditions/visitor_scope_condition'
 
 module Kameleoon
   # @api private
   module Targeting
     # TargetExperiment represents an instance of Experiment condition in user account
-    class TargetExperimentCondition < Condition
+    class TargetExperimentCondition < VisitorScopeCondition
       include Kameleoon::Exception
 
       def initialize(json_condition)
-        super(json_condition)
+        super(json_condition, VisitScope::CURRENT_VISIT)
 
         @variation_id = json_condition['variationId'] || -1
         @experiment_id = json_condition['experimentId'] || -1
@@ -19,9 +19,10 @@ module Kameleoon
       end
 
       def check(data)
-        return false unless data.is_a?(TargetExperimentInfo)
+        return false unless data.is_a?(TargetingData)
 
-        variation = data.variations_storage&.get(@experiment_id)
+        variation = data.variations&.get(@experiment_id)
+        variation = nil if !variation.nil? && variation.assignment_time < assignment_threshold(data.visitor_visits)
         case @variation_match_type
         when Operator::ANY
           return !variation.nil?
@@ -33,13 +34,14 @@ module Kameleoon
         )
         false
       end
-    end
 
-    class TargetExperimentInfo
-      attr_reader :variations_storage
+      class TargetingData
+        attr_reader :variations, :visitor_visits
 
-      def initialize(variations_storage)
-        @variations_storage = variations_storage
+        def initialize(variations, visitor_visits = nil)
+          @variations = variations
+          @visitor_visits = visitor_visits
+        end
       end
     end
   end

data/lib/kameleoon/targeting/conditions/target_feature_flag_condition.rb

@@ -1,59 +1,63 @@
 # frozen_string_literal: true
 
-require 'kameleoon/targeting/condition'
+require 'kameleoon/targeting/conditions/visitor_scope_condition'
 require 'kameleoon/exceptions'
 
 module Kameleoon
   # @api private
   module Targeting
-    # TargetFeatureFlag represents an instance of FeatureFlag condition in user account
-    class TargetFeatureFlagCondition < Condition
+    class TargetFeatureFlagCondition < VisitorScopeCondition
       include Kameleoon::Exception
 
       def initialize(json_condition)
-        super(json_condition)
-
+        super(json_condition, VisitScope::CURRENT_VISIT)
         @feature_flag_id = json_condition['featureFlagId']
         @condition_variation_key = json_condition['variationKey']
         @condition_rule_id = json_condition['ruleId']
       end
 
       def check(data)
-        return false unless data.is_a?(TargetFeatureFlagInfo) && data.variations_storage.size.positive?
+        return false unless valid_data?(data)
 
         get_rules(data).any? { |rule| check_rule(data, rule) }
       end
 
       private
 
+      def valid_data?(data)
+        data.is_a?(TargetingData) && !data.data_file.nil? && data.variations&.size.to_i.positive?
+      end
+
       def check_rule(data, rule)
         return false unless rule.is_a?(Configuration::Rule)
-        return false if !@condition_rule_id.nil? && (@condition_rule_id != rule.id)
-
-        variation = data.variations_storage.get(rule.experiment.id)
-        return false if variation.nil?
+        return false if @condition_rule_id && @condition_rule_id != rule.id
 
-        return true if @condition_variation_key.nil?
+        variation = data.variations.get(rule.experiment.id)
+        return false if variation.nil? || variation.assignment_time < assignment_threshold(data.visitor_visits)
 
-        variation = data.data_file.variation_by_id[variation.variation_id]
+        check_variation_key(data.data_file, variation)
+      end
 
-        return false unless variation.is_a?(Configuration::VariationByExposition)
+      def check_variation_key(data_file, variation)
+        return true if @condition_variation_key.nil?
 
-        variation.variation_key == @condition_variation_key
+        resolved = data_file.variation_by_id[variation.variation_id]
+        resolved.is_a?(Configuration::VariationByExposition) &&
+          resolved.variation_key == @condition_variation_key
       end
 
       def get_rules(data)
-        feature_flag = data.data_file.feature_flag_by_id[@feature_flag_id]
-        feature_flag&.rules || []
+        data.data_file.feature_flag_by_id[@feature_flag_id]&.rules || []
       end
-    end
 
-    class TargetFeatureFlagInfo
-      attr_reader :data_file, :variations_storage
+      class TargetingData
+        attr_reader :data_file, :variations, :visitor_visits
 
-      def initialize(data_file, variations_storage)
-        @data_file = data_file
-        @variations_storage = variations_storage
+        def initialize(data_file, variations, visitor_visits = nil)
+          @data_file = data_file
+          @variations = variations
+          @visitor_visits = visitor_visits
+        end
       end
     end
   end

data/lib/kameleoon/targeting/conditions/target_personalization_condition.rb

@@ -1,32 +1,34 @@
 # frozen_string_literal: true
 
-require 'kameleoon/targeting/condition'
+require 'kameleoon/targeting/conditions/visitor_scope_condition'
 
 module Kameleoon
   # @api private
   module Targeting
     # TargetPersonalization represents an instance of Personalization condition in user account
-    class TargetPersonalizationCondition < Condition
+    class TargetPersonalizationCondition < VisitorScopeCondition
       include Kameleoon::Exception
 
       def initialize(json_condition)
-        super(json_condition)
+        super(json_condition, VisitScope::CURRENT_VISIT)
 
         @personalization_id = json_condition['personalizationId'] || -1
       end
 
       def check(data)
-        return false unless data.is_a?(TargetPersonalizationInfo)
+        return false unless data.is_a?(TargetingData)
 
-        !data.personalizations_storage&.get(@personalization_id).nil?
+        personalization = data.personalizations&.get(@personalization_id)
+        !personalization.nil? && personalization.assignment_time >= assignment_threshold(data.visitor_visits)
       end
-    end
 
-    class TargetPersonalizationInfo
-      attr_reader :personalizations_storage
+      class TargetingData
+        attr_reader :personalizations, :visitor_visits
 
-      def initialize(personalizations_storage)
-        @personalizations_storage = personalizations_storage
+        def initialize(personalizations, visitor_visits = nil)
+          @personalizations = personalizations
+          @visitor_visits = visitor_visits
+        end
       end
     end
   end

data/lib/kameleoon/targeting/conditions/time_elapsed_since_visit_condition.rb

@@ -19,9 +19,8 @@ module Kameleoon
 
         prev_visits = data.prev_visits
         if prev_visits.size >= 1
-          now = (Time.now.to_f * 1000).to_i # ... * 1000 for convert seconds to milliseconds
           visit_time = prev_visits[@is_first_visit ? prev_visits.size - 1 : 0].time_started
-          return check_targeting(now - visit_time)
+          return check_targeting(Time.now.to_f - visit_time)
         end
         false
       end

data/lib/kameleoon/targeting/conditions/visit_number_today_condition.rb

@@ -16,7 +16,7 @@ module Kameleoon
         return false unless data.is_a?(TargetingData) && !@condition_value.nil?
 
         number_of_visits_today = 0
-        start_of_day = (Time.new.to_date.to_time.to_f * 1000).to_i # ... * 1000 to convert seconds to milliseconds
+        start_of_day = Time.new.to_date.to_time.to_f
         data.visitor_visits.prev_visits.each do |visit|
           break if visit.time_started < start_of_day
 
@@ -31,7 +31,7 @@ module Kameleoon
 
         def initialize(current_visit_time_started, visitor_visits)
           @current_visit_time_started =
-            current_visit_time_started.is_a?(Integer) ? current_visit_time_started : (Time.new.to_f * 1000).to_i
+            current_visit_time_started.is_a?(Integer) ? current_visit_time_started : Time.new.to_f
           @visitor_visits = visitor_visits.is_a?(VisitorVisits) ? visitor_visits : VisitorVisits.new([])
         end
       end

data/lib/kameleoon/targeting/conditions/visitor_scope_condition.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require 'kameleoon/data/visitor_visits'
+require 'kameleoon/targeting/condition'
+
+module Kameleoon
+  # @api private
+  module Targeting
+    module VisitScope
+      CURRENT_VISIT = 'CURRENT_VISIT'
+      VISITOR = 'VISITOR'
+    end
+
+    class VisitorScopeCondition < Condition
+      MIN_VISITOR_VISIT_COUNT = 2
+      MAX_VISITOR_VISIT_COUNT = 25
+
+      def initialize(json_condition, default_visit_scope)
+        super(json_condition)
+        @visit_scope = parse_visit_scope(json_condition['visitScope'], default_visit_scope)
+        @visit_count = parse_visit_count(json_condition['visitCount'])
+      end
+
+      private
+
+      def assignment_threshold(visitor_visits)
+        return 0.0 unless visitor_visits.is_a?(Kameleoon::VisitorVisits)
+
+        prev_visits = visitor_visits.prev_visits
+        if @visit_scope == VisitScope::CURRENT_VISIT || @visit_count < MIN_VISITOR_VISIT_COUNT || prev_visits.empty?
+          return visitor_visits.time_started
+        end
+
+        visit_index = [[@visit_count - MIN_VISITOR_VISIT_COUNT, 0].max, prev_visits.size - 1].min
+        prev_visits[visit_index].time_started
+      end
+
+      def parse_visit_scope(value, default_visit_scope)
+        case value&.upcase
+        when VisitScope::CURRENT_VISIT
+          VisitScope::CURRENT_VISIT
+        when VisitScope::VISITOR
+          VisitScope::VISITOR
+        else
+          default_visit_scope
+        end
+      end
+
+      def parse_visit_count(value)
+        return value if value.is_a?(Integer) && value.positive?
+
+        MAX_VISITOR_VISIT_COUNT
+      end
+    end
+  end
+end

data/lib/kameleoon/targeting/targeting_manager.rb

@@ -2,6 +2,7 @@
 
 require 'kameleoon/logging/kameleoon_logger'
 require 'kameleoon/targeting/condition'
+require 'kameleoon/targeting/conditions/conversion_condition'
 require 'kameleoon/targeting/conditions/exclusive_experiment_condition'
 require 'kameleoon/targeting/conditions/sdk_language_condition'
 require 'kameleoon/targeting/conditions/segment_condition'
@@ -68,20 +69,26 @@ module Kameleoon
             }
           )
         when ConditionType::CONVERSIONS
-          condition_data = visitor.conversions unless visitor.nil?
+          condition_data = ConversionCondition::TargetingData.new(visitor&.conversions, visitor&.visitor_visits)
         when ConditionType::SDK_LANGUAGE
           condition_data = SdkInfo.new(Kameleoon::SDK_NAME, Kameleoon::SDK_VERSION)
         when ConditionType::VISITOR_CODE
           condition_data = visitor_code
         when ConditionType::TARGET_FEATURE_FLAG
-          condition_data = TargetFeatureFlagInfo.new(@data_manager.data_file, visitor.variations) unless visitor.nil?
+          condition_data = TargetFeatureFlagCondition::TargetingData.new(
+            @data_manager.data_file, visitor&.variations, visitor&.visitor_visits
+          )
         when ConditionType::TARGET_EXPERIMENT
-          condition_data = TargetExperimentInfo.new(visitor&.variations)
+          condition_data = TargetExperimentCondition::TargetingData.new(visitor&.variations, visitor&.visitor_visits)
         when ConditionType::TARGET_PERSONALIZATION
-          condition_data = TargetPersonalizationInfo.new(visitor&.personalizations)
+          condition_data = TargetPersonalizationCondition::TargetingData.new(
+            visitor&.personalizations, visitor&.visitor_visits
+          )
         when ConditionType::EXCLUSIVE_EXPERIMENT
           unless campaign_id.nil?
-            condition_data = ExclusiveExperimentInfo.new(campaign_id, visitor&.variations, visitor&.personalizations)
+            condition_data = ExclusiveExperimentCondition::TargetingData.new(
+              campaign_id, visitor&.variations, visitor&.personalizations, visitor&.visitor_visits
+            )
           end
         when ConditionType::FIRST_VISIT,
           ConditionType::LAST_VISIT,

data/lib/kameleoon/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module Kameleoon
-  SDK_VERSION = '3.19.0'
+  SDK_VERSION = '3.21.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.19.0
+  version: 3.21.0
 platform: ruby
 authors:
 - Kameleoon
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-04-22 00:00:00.000000000 Z
+date: 2026-07-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: em-http-request
@@ -178,6 +178,7 @@ files:
 - lib/kameleoon/targeting/conditions/visit_number_total_condition.rb
 - lib/kameleoon/targeting/conditions/visitor_code_condition.rb
 - lib/kameleoon/targeting/conditions/visitor_new_return_condition.rb
+- lib/kameleoon/targeting/conditions/visitor_scope_condition.rb
 - lib/kameleoon/targeting/models.rb
 - lib/kameleoon/targeting/targeting_manager.rb
 - lib/kameleoon/targeting/tree_builder.rb