amplitude-experiment 1.7.1 → 1.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6562a2b13fb38d240e3d83762e442a558478db59f3fff36bdff10b6589cfab0d
-  data.tar.gz: 432ea0ff64724c882ad97aae3ce95ae8d8a203f9c90bfe34afd5629e00dbba28
+  metadata.gz: d1474764e3ae979eb8f3799a76f42513ff707a7307d7dc2eae9d9d6da4bef36f
+  data.tar.gz: 889f7ba4cc9860523c7a5b6854b19e75b54ac8ae6330414007142779cbe7f2f3
 SHA512:
-  metadata.gz: 507368b7f4db8a28dfc866e0df203f724a1d2911af19dab24fada0bb7327e362d185057c891d534421c7816ec12953ad6555a0252b9bfa7d4922ffaea16bc935
-  data.tar.gz: d7ad16548702c918919a9d3b4afe874d396c8c5e98fb5010ebb3f8c0f0b476ad86d4568ed4660a74040a5ee85d4a9e01197560039b19d94659ec0e38d67b0868
+  metadata.gz: 705c6b31291bf96b3f9ea93ea3c166aa8e61f28b80bf0253261d42374895e1b8f923b3536b9308a3cd03b2ba9f7d4654abdfd2e2894fe19a802d3f658b454e3a
+  data.tar.gz: ff192b072846e12ede79277411bde7e38075be600707138a8a25090c6e325425aa1ed72c10b09fdda9c9a1e1c4dcb409c32f06ed26e3b36a27b4db0127ceeecc

data/lib/amplitude-experiment.rb

@@ -6,12 +6,18 @@ require 'experiment/user'
 require 'experiment/variant'
 require 'experiment/factory'
 require 'experiment/remote/client'
+require 'experiment/remote/fetch_options'
 require 'experiment/local/client'
 require 'experiment/local/config'
+require 'experiment/local/evaluate_options'
 require 'experiment/local/assignment/assignment'
 require 'experiment/local/assignment/assignment_filter'
 require 'experiment/local/assignment/assignment_service'
 require 'experiment/local/assignment/assignment_config'
+require 'experiment/local/exposure/exposure'
+require 'experiment/local/exposure/exposure_filter'
+require 'experiment/local/exposure/exposure_service'
+require 'experiment/local/exposure/exposure_config'
 require 'experiment/util/lru_cache'
 require 'experiment/util/hash'
 require 'experiment/util/user'

data/lib/experiment/local/assignment/assignment.rb

@@ -1,6 +1,7 @@
 module AmplitudeExperiment
   DAY_MILLIS = 86_400_000
   # Assignment
+  # @deprecated Assignment tracking is deprecated. Use Exposure with ExposureService instead.
   class Assignment
     attr_accessor :user, :results, :timestamp
 

data/lib/experiment/local/assignment/assignment_config.rb

@@ -1,5 +1,6 @@
 module AmplitudeExperiment
   # AssignmentConfig
+  # @deprecated Assignment tracking is deprecated. Use ExposureConfig with ExposureService instead.
   class AssignmentConfig < AmplitudeAnalytics::Config
     attr_accessor :api_key, :cache_capacity
 

data/lib/experiment/local/assignment/assignment_filter.rb

@@ -1,5 +1,6 @@
 module AmplitudeExperiment
   # AssignmentFilter
+  # @deprecated Assignment tracking is deprecated. Use ExposureFilter with ExposureService instead.
   class AssignmentFilter
     def initialize(size, ttl_millis = DAY_MILLIS)
       @cache = LRUCache.new(size, ttl_millis)

data/lib/experiment/local/assignment/assignment_service.rb

@@ -1,6 +1,7 @@
 require_relative '../../../amplitude'
 module AmplitudeExperiment
   # AssignmentService
+  # @deprecated Assignment tracking is deprecated. Use ExposureService with Exposure tracking instead.
   class AssignmentService
     def initialize(amplitude, assignment_filter)
       @amplitude = amplitude

data/lib/experiment/local/client.rb

@@ -26,6 +26,10 @@ module AmplitudeExperiment
       @assignment_service = nil
       @assignment_service = AssignmentService.new(AmplitudeAnalytics::Amplitude.new(config.assignment_config.api_key, configuration: config.assignment_config), AssignmentFilter.new(config.assignment_config.cache_capacity)) if config&.assignment_config
 
+      # Exposure service is always instantiated, using deployment key if no api key provided
+      @exposure_service = nil
+      @exposure_service = ExposureService.new(AmplitudeAnalytics::Amplitude.new(config.exposure_config.api_key, configuration: config.exposure_config), ExposureFilter.new(config.exposure_config.cache_capacity)) if config&.exposure_config
+
       @cohort_storage = InMemoryCohortStorage.new
       @flag_config_storage = InMemoryFlagConfigStorage.new
       @flag_config_fetcher = LocalEvaluationFetcher.new(@api_key, @logger, @config.server_url)
@@ -53,6 +57,7 @@ module AmplitudeExperiment
       AmplitudeExperiment.filter_default_variants(variants)
     end
 
+    # TODO: ruby backwards compatibility for evaluate_v2 to be looked at again
     # Locally evaluates flag variants for a user.
     #  This function will only evaluate flags for the keys specified in the flag_keys argument. If flag_keys is
     #  missing or None, all flags are evaluated. This function differs from evaluate as it will return a default
@@ -60,8 +65,9 @@ module AmplitudeExperiment
     #
     # @param [User] user The user to evaluate
     # @param [String[]] flag_keys The flags to evaluate with the user, if empty all flags are evaluated
+    # @param [EvaluateOptions] options Optional evaluation options
     # @return [Hash[String, Variant]] The evaluated variants
-    def evaluate_v2(user, flag_keys = [])
+    def evaluate_v2(user, flag_keys = [], options = nil)
       flags = @flag_config_storage.flag_configs
       return {} if flags.nil?
 
@@ -74,6 +80,8 @@ module AmplitudeExperiment
       result = @engine.evaluate(context, sorted_flags)
       @logger.debug("[Experiment] evaluate - result: #{result}") if @config.debug
       variants = AmplitudeExperiment.evaluation_variants_json_to_variants(result)
+      @exposure_service&.track(Exposure.new(user, variants)) if options&.tracks_exposure == true
+      # @deprecated Assignment tracking is deprecated. Use ExposureService with Exposure tracking instead.
       @assignment_service&.track(Assignment.new(user, variants))
       variants
     end

data/lib/experiment/local/config.rb

@@ -35,9 +35,14 @@ module AmplitudeExperiment
     attr_accessor :flag_config_polling_interval_millis
 
     # Configuration for automatically tracking assignment events after an evaluation.
+    # @deprecated use exposure_config instead
     # @return [AssignmentConfig] the config instance
     attr_accessor :assignment_config
 
+    # Configuration for automatically tracking exposure events after an evaluation.
+    # @return [ExposureConfig] the config instance
+    attr_accessor :exposure_config
+
     # Configuration for downloading cohorts required for flag evaluation
     # @return [CohortSyncConfig] the config instance
     attr_accessor :cohort_sync_config
@@ -48,7 +53,8 @@ module AmplitudeExperiment
     # @param [String] server_zone Location of the Amplitude data center to get flags and cohorts from, US or EU
     # @param [Hash] bootstrap The value of bootstrap.
     # @param [long] flag_config_polling_interval_millis The value of flag config polling interval in million seconds.
-    # @param [AssignmentConfig] assignment_config Configuration for automatically tracking assignment events after an evaluation.
+    # @param [AssignmentConfig] assignment_config Configuration for automatically tracking assignment events after an evaluation. @deprecated use exposure_config instead
+    # @param [ExposureConfig] exposure_config Configuration for automatically tracking exposure events after an evaluation.
     # @param [CohortSyncConfig] cohort_sync_config Configuration for downloading cohorts required for flag evaluation
     def initialize(server_url: DEFAULT_SERVER_URL,
                    server_zone: ServerZone::US,
@@ -57,6 +63,7 @@ module AmplitudeExperiment
                    debug: false,
                    logger: nil,
                    assignment_config: nil,
+                   exposure_config: nil,
                    cohort_sync_config: nil)
       @logger = logger
       if logger.nil?
@@ -73,6 +80,7 @@ module AmplitudeExperiment
       @bootstrap = bootstrap
       @flag_config_polling_interval_millis = flag_config_polling_interval_millis
       @assignment_config = assignment_config
+      @exposure_config = exposure_config
     end
   end
 end

data/lib/experiment/local/evaluate_options.rb

@@ -0,0 +1,10 @@
+module AmplitudeExperiment
+  # Options for evaluating variants for a user.
+  class EvaluateOptions
+    attr_accessor :tracks_exposure
+
+    def initialize(tracks_exposure: nil)
+      @tracks_exposure = tracks_exposure
+    end
+  end
+end

data/lib/experiment/local/exposure/exposure.rb

@@ -0,0 +1,22 @@
+module AmplitudeExperiment
+  # Exposure is a class that represents a user's exposure to a set of flags.
+  class Exposure
+    attr_accessor :user, :results, :timestamp
+
+    def initialize(user, results)
+      @user = user
+      @results = results
+      @timestamp = (Time.now.to_f * 1000).to_i
+    end
+
+    def canonicalize
+      sb = "#{@user&.user_id&.strip} #{@user&.device_id&.strip} "
+      results.sort.to_h.each do |key, value|
+        next unless value.key
+
+        sb += "#{key.strip} #{value.key&.strip} "
+      end
+      sb
+    end
+  end
+end

data/lib/experiment/local/exposure/exposure_config.rb

@@ -0,0 +1,12 @@
+module AmplitudeExperiment
+  # ExposureConfig
+  class ExposureConfig < AmplitudeAnalytics::Config
+    attr_accessor :api_key, :cache_capacity
+
+    def initialize(api_key = nil, cache_capacity = 65_536, **kwargs)
+      super(**kwargs)
+      @api_key = api_key
+      @cache_capacity = cache_capacity
+    end
+  end
+end

data/lib/experiment/local/exposure/exposure_filter.rb

@@ -0,0 +1,20 @@
+module AmplitudeExperiment
+  # ExposureFilter
+  class ExposureFilter
+    attr_accessor :ttl_millis
+
+    def initialize(size, ttl_millis = DAY_MILLIS)
+      @cache = LRUCache.new(size, ttl_millis)
+      @ttl_millis = ttl_millis
+    end
+
+    def should_track(exposure)
+      return false if exposure.results.empty?
+
+      canonical_exposure = exposure.canonicalize
+      track = @cache.get(canonical_exposure).nil?
+      @cache.put(canonical_exposure, 0) if track
+      track
+    end
+  end
+end

data/lib/experiment/local/exposure/exposure_service.rb

@@ -0,0 +1,71 @@
+require_relative '../../../amplitude'
+module AmplitudeExperiment
+  # ExposureService
+  class ExposureService
+    def initialize(amplitude, exposure_filter)
+      @amplitude = amplitude
+      @exposure_filter = exposure_filter
+    end
+
+    def track(exposure)
+      return unless @exposure_filter.should_track(exposure)
+
+      events = ExposureService.to_exposure_events(exposure, @exposure_filter.ttl_millis)
+      events.each do |event|
+        @amplitude.track(event)
+      end
+    end
+
+    def self.to_exposure_events(exposure, ttl_millis)
+      events = []
+      canonicalized = exposure.canonicalize
+      exposure.results.each do |flag_key, variant|
+        track_exposure = variant.metadata ? variant.metadata.fetch('trackExposure', true) : true
+        next unless track_exposure
+
+        # Skip default variant exposures
+        is_default = variant.metadata ? variant.metadata.fetch('default', false) : false
+        next if is_default
+
+        # Determine user properties to set and unset.
+        set_props = {}
+        unset_props = {}
+        flag_type = variant.metadata['flagType'] if variant.metadata
+        if flag_type != 'mutual-exclusion-group'
+          if variant.key
+            set_props["[Experiment] #{flag_key}"] = variant.key
+          elsif variant.value
+            set_props["[Experiment] #{flag_key}"] = variant.value
+          end
+        end
+
+        # Build event properties.
+        event_properties = {}
+        event_properties['[Experiment] Flag Key'] = flag_key
+        if variant.key
+          event_properties['[Experiment] Variant'] = variant.key
+        elsif variant.value
+          event_properties['[Experiment] Variant'] = variant.value
+        end
+        event_properties['metadata'] = variant.metadata if variant.metadata
+
+        # Build event.
+        event = AmplitudeAnalytics::BaseEvent.new(
+          '[Experiment] Exposure',
+          user_id: exposure.user.user_id,
+          device_id: exposure.user.device_id,
+          event_properties: event_properties,
+          user_properties: {
+            '$set' => set_props,
+            '$unset' => unset_props
+          },
+          insert_id: "#{exposure.user.user_id} #{exposure.user.device_id} #{AmplitudeExperiment.hash_code("#{flag_key} #{canonicalized}")} #{exposure.timestamp / ttl_millis}"
+        )
+        event.groups = exposure.user.groups if exposure.user.groups
+
+        events << event
+      end
+      events
+    end
+  end
+end

data/lib/experiment/remote/client.rb

@@ -25,7 +25,7 @@ module AmplitudeExperiment
     # @param [User] user
     # @return [Hash] Variants Hash
     def fetch(user)
-      AmplitudeExperiment.filter_default_variants(fetch_internal(user))
+      AmplitudeExperiment.filter_default_variants(fetch_internal(user, nil))
     rescue StandardError => e
       @logger.error("[Experiment] Failed to fetch variants: #{e.message}")
       {}
@@ -36,9 +36,10 @@ module AmplitudeExperiment
     # This method will automatically retry if configured (default). This function differs from fetch as it will
     # return a default variant object if the flag was evaluated but the user was not assigned (i.e. off).
     # @param [User] user
+    # @param [FetchOptions] fetch_options
     # @return [Hash] Variants Hash
-    def fetch_v2(user)
-      fetch_internal(user)
+    def fetch_v2(user, fetch_options = nil)
+      fetch_internal(user, fetch_options)
     rescue StandardError => e
       @logger.error("[Experiment] Failed to fetch variants: #{e.message}")
       {}
@@ -51,7 +52,7 @@ module AmplitudeExperiment
     # @yield [User, Hash] callback block takes user object and variants hash
     def fetch_async(user, &callback)
       Thread.new do
-        variants = fetch_internal(user)
+        variants = AmplitudeExperiment.filter_default_variants(fetch_internal(user, nil))
         yield(user, variants) unless callback.nil?
         variants
       rescue StandardError => e
@@ -67,10 +68,10 @@ module AmplitudeExperiment
     # This method will automatically retry if configured (default).
     # @param [User] user
     # @yield [User, Hash] callback block takes user object and variants hash
-    def fetch_async_v2(user, &callback)
+    def fetch_async_v2(user, fetch_options = nil, &callback)
       Thread.new do
-        variants = fetch_internal(user)
-        yield(user, filter_default_variants(variants)) unless callback.nil?
+        variants = fetch_internal(user, fetch_options)
+        yield(user, variants) unless callback.nil?
         variants
       rescue StandardError => e
         @logger.error("[Experiment] Failed to fetch variants: #{e.message}")
@@ -82,14 +83,15 @@ module AmplitudeExperiment
     private
 
     # @param [User] user
-    def fetch_internal(user)
+    # @param [FetchOptions] fetch_options
+    def fetch_internal(user, fetch_options)
       @logger.debug("[Experiment] Fetching variants for user: #{user.as_json}")
-      do_fetch(user, @config.connect_timeout_millis, @config.fetch_timeout_millis)
+      do_fetch(user, fetch_options, @config.connect_timeout_millis, @config.fetch_timeout_millis)
     rescue StandardError => e
       @logger.error("[Experiment] Fetch failed: #{e.message}")
       if should_retry_fetch?(e)
         begin
-          retry_fetch(user)
+          retry_fetch(user, fetch_options)
         rescue StandardError => err
           @logger.error("[Experiment] Retry Fetch failed: #{err.message}")
         end
@@ -98,7 +100,8 @@ module AmplitudeExperiment
     end
 
     # @param [User] user
-    def retry_fetch(user)
+    # @param [FetchOptions] fetch_options
+    def retry_fetch(user, fetch_options)
       return {} if @config.fetch_retries.zero?
 
       @logger.debug('[Experiment] Retrying fetch')
@@ -107,7 +110,7 @@ module AmplitudeExperiment
       @config.fetch_retries.times do
         sleep(delay_millis.to_f / 1000.0)
         begin
-          return do_fetch(user, @config.connect_timeout_millis, @config.fetch_retry_timeout_millis)
+          return do_fetch(user, fetch_options, @config.connect_timeout_millis, @config.fetch_retry_timeout_millis)
         rescue StandardError => e
           @logger.error("[Experiment] Retry failed: #{e.message}")
           err = e
@@ -118,15 +121,24 @@ module AmplitudeExperiment
     end
 
     # @param [User] user
+    # @param [FetchOptions] fetch_options
     # @param [Integer] connect_timeout_millis
     # @param [Integer] fetch_timeout_millis
-    def do_fetch(user, connect_timeout_millis, fetch_timeout_millis)
+    def do_fetch(user, fetch_options, connect_timeout_millis, fetch_timeout_millis)
       start_time = Time.now
       user_context = add_context(user)
       headers = {
         'Authorization' => "Api-Key #{@api_key}",
         'Content-Type' => 'application/json;charset=utf-8'
       }
+      unless fetch_options.nil?
+        unless fetch_options.tracks_assignment.nil?
+          headers['X-Amp-Exp-Track'] = fetch_options.tracks_assignment ? 'track' : 'no-track'
+        end
+        unless fetch_options.tracks_exposure.nil?
+          headers['X-Amp-Exp-Exposure-Track'] = fetch_options.tracks_exposure ? 'track' : 'no-track'
+        end
+      end
       connect_timeout = connect_timeout_millis.to_f / 1000 if (connect_timeout_millis.to_f / 1000) > 0
       read_timeout = fetch_timeout_millis.to_f / 1000 if (fetch_timeout_millis.to_f / 1000) > 0
       http = PersistentHttpClient.get(@uri, { open_timeout: connect_timeout, read_timeout: read_timeout }, @api_key)

data/lib/experiment/remote/fetch_options.rb

@@ -0,0 +1,19 @@
+module AmplitudeExperiment
+  # Fetch options
+  class FetchOptions
+    # Whether to track assignment events.
+    # If not provided, the default is null, which will use server default (to track assignment events).
+    # @return [Boolean, nil] the value of tracks_assignment
+    attr_accessor :tracks_assignment
+
+    # Whether to track exposure events.
+    # If not provided, the default is null, which will use server default (to not track exposure events).
+    # @return [Boolean, nil] the value of tracks_exposure
+    attr_accessor :tracks_exposure
+
+    def initialize(tracks_assignment: nil, tracks_exposure: nil)
+      @tracks_assignment = tracks_assignment
+      @tracks_exposure = tracks_exposure
+    end
+  end
+end

data/lib/experiment/version.rb

@@ -1,3 +1,3 @@
 module AmplitudeExperiment
-  VERSION = '1.7.1'.freeze
+  VERSION = '1.9.0'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: amplitude-experiment
 version: !ruby/object:Gem::Version
-  version: 1.7.1
+  version: 1.9.0
 platform: ruby
 authors:
 - Amplitude
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-12-04 00:00:00.000000000 Z
+date: 2026-01-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -213,9 +213,15 @@ files:
 - lib/experiment/local/assignment/assignment_service.rb
 - lib/experiment/local/client.rb
 - lib/experiment/local/config.rb
+- lib/experiment/local/evaluate_options.rb
+- lib/experiment/local/exposure/exposure.rb
+- lib/experiment/local/exposure/exposure_config.rb
+- lib/experiment/local/exposure/exposure_filter.rb
+- lib/experiment/local/exposure/exposure_service.rb
 - lib/experiment/persistent_http_client.rb
 - lib/experiment/remote/client.rb
 - lib/experiment/remote/config.rb
+- lib/experiment/remote/fetch_options.rb
 - lib/experiment/user.rb
 - lib/experiment/util/flag_config.rb
 - lib/experiment/util/hash.rb